# How Media Files (Images and GIFs) Are Named in the Exercises Dataset

> Discover the deterministic naming pattern <id>-<media_id>.<ext> for media files in hasaneyldrm/exercises-dataset. Learn how images and GIFs are organized and validated.

- Repository: [Hasan Emir Yıldırım/exercises-dataset](https://github.com/hasaneyldrm/exercises-dataset)
- Tags: how-to-guide
- Published: 2026-07-29

---

**Media files use a deterministic naming pattern of `<id>-<media_id>.<ext>`, storing images in the `images/` directory and GIFs in the `videos/` directory with strict validation rules defined in the JSON schema.**

The `hasaneyldrm/exercises-dataset` repository organizes visual assets for each exercise through a strict naming convention that ties filenames directly to exercise identifiers. This systematic approach ensures every thumbnail and animation can be programmatically located and validated against the schema defined in [`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json).

## Naming Convention Structure

The dataset employs a consistent hyphen-delimited format that combines a zero-padded exercise ID with a unique media reference hash.

### Image Thumbnails

Static image files reside in the `images/` folder and follow the pattern:

```

<id>-<media_id>.jpg

```

Supported extensions include `.jpg`, `.jpeg`, and `.png`. For example, `images/0001-2gPfomN.jpg` represents the thumbnail for exercise 0001. The `id` component is always a four-digit zero-padded string, while `media_id` contains the original media reference identifier (e.g., "2gPfomN").

### Animation GIFs

Animated demonstrations are stored in the `videos/` directory using the pattern:

```

<id>-<media_id>.gif

```

Unlike images, GIFs strictly use the `.gif` extension. An example path would be `videos/0001-2gPfomN.gif`, maintaining the same ID and media reference components as its corresponding thumbnail.

## Schema Validation Rules

The naming conventions are enforced through regex patterns in [`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json). According to the source code, the image field must match `^images/.+\.(jpg|jpeg|png)$` (see [line 121](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json#L121)), while GIF paths must satisfy `^videos/.+\.gif$` (see [line 125](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json#L125)).

## Locating Media Files in the Dataset

Each exercise record in [`data/exercises.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json) contains explicit file pointers:

- **`image`**: Relative path to the thumbnail (e.g., `"images/0001-2gPfomN.jpg"`)
- **`gif_url`**: Relative path to the animation (e.g., `"videos/0001-2gPfomN.gif"`)

A concrete implementation appears in the first exercise entry at [line 99](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json#L99), demonstrating how the `id` field correlates with the filename prefix.

## Working with Media Files Programmatically

### Python: Resolve Full URLs for Exercise Media

This script constructs absolute GitHub raw URLs from the relative paths stored in the JSON:

```python
import json
from pathlib import Path

# Load the dataset

with open(Path(__file__).parent / "data" / "exercises.json", encoding="utf-8") as f:
    exercises = json.load(f)

def media_urls(exercise_id: str) -> dict:
    """Return absolute URLs for the image and GIF of a given exercise."""
    base_url = "https://github.com/hasaneyldrm/exercises-dataset/raw/main"
    ex = next(e for e in exercises if e["id"] == exercise_id)
    return {
        "image": f"{base_url}/{ex['image']}",
        "gif": f"{base_url}/{ex['gif_url']}",
    }

# Example usage

print(media_urls("0001"))

# Output:

# {

#   'image': 'https://github.com/hasaneyldrm/exercises-dataset/raw/main/images/0001-2gPfomN.jpg',

#   'gif': 'https://github.com/hasaneyldrm/exercises-dataset/raw/main/videos/0001-2gPfomN.gif'

# }

```

### Bash: List All Media File Mappings

This shell command extracts the ID-to-file mappings from the dataset:

```bash
#!/usr/bin/env bash
jq -r '.[] | "\(.id) \(.image) \(.gif_url)"' data/exercises.json |
while read -r id img gif; do
    echo "Exercise $id:"
    echo "  Image → $img"
    echo "  GIF   → $gif"
done

```

## Summary

- **Filename pattern**: All media files use `<id>-<media_id>.<ext>` where `id` is a zero-padded 4-digit exercise identifier.
- **Directory structure**: Images live in `images/` (`.jpg`, `.jpeg`, `.png`), while GIFs reside in `videos/` (`.gif` only).
- **Schema enforcement**: Patterns are validated via regex in [`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json) at lines 121 and 125.
- **JSON references**: Each exercise record points to its media via the `image` and `gif_url` fields in [`data/exercises.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.json).

## Frequently Asked Questions

### What is the exact filename pattern for exercise images?

Image files follow the pattern `images/<id>-<media_id>.<ext>`, where `<id>` is a four-digit zero-padded number (e.g., "0001") and `<ext>` must be `.jpg`, `.jpeg`, or `.png`. The `<media_id>` represents the original media reference identifier, such as "2gPfomN".

### Where are GIF animations stored in the repository?

Despite containing video content, all GIF files are stored in the `videos/` directory at the repository root, not in an `images/` or `gifs/` folder. Each file follows the naming convention `<id>-<media_id>.gif`, matching the corresponding exercise's thumbnail ID.

### How does the dataset validate media file paths?

The JSON schema in [`data/exercises.schema.json`](https://github.com/hasaneyldrm/exercises-dataset/blob/main/data/exercises.schema.json) enforces strict regex patterns: `^images/.+\.(jpg|jpeg|png)$` for images (line 121) and `^videos/.+\.gif$` for animations (line 125). These patterns ensure all referenced files conform to the expected directory structure and extensions.

### Can media files have extensions other than JPG or GIF?

No. According to the schema validation rules, images are restricted to `.jpg`, `.jpeg`, or `.png` extensions, while animations must use `.gif`. The dataset does not support WebP, MP4, or other media formats in the current schema implementation.