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

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.

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. According to the source code, the image field must match ^images/.+\.(jpg|jpeg|png)$ (see line 121), while GIF paths must satisfy ^videos/.+\.gif$ (see line 125).

Locating Media Files in the Dataset

Each exercise record in 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, 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:

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:

#!/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 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.

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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}