Understanding the Exercises Media File Naming Convention (Thumbnails and GIFs)

The hasaneyldrm/exercises-dataset repository stores exercise preview thumbnails as GIF files in the videos/ directory using the pattern <exercise-id>-<unique-hash>.gif, where the numeric ID is zero-padded to four digits to match the id field in data/exercises.json.

The exercises media file naming convention enables reliable programmatic access to thumbnail assets without requiring you to store unpredictable hash strings in your application database. By scanning the videos/ folder for files matching the predictable ID prefix, you can dynamically resolve the full filename for any exercise in the dataset.

The Thumbnail Naming Pattern

According to the source code structure in hasaneyldrm/exercises-dataset, every preview GIF resides in the videos/ directory and follows a strict two-part naming convention:

<exercise-id>-<unique-hash>.gif

For example, the files 0111-6HiHHe0.gif and 0010-8K0w2yA.gif illustrate this pattern for exercise IDs 111 and 10, respectively.

Filename Components

• <exercise-id>: A zero-padded four-digit numeric identifier that corresponds exactly to the id field in data/exercises.json. For instance, exercise 111 becomes the prefix 0111-.

• <unique-hash>: An alphanumeric string typically 6–8 characters in length, generated when the GIF is created to prevent filename collisions across different resolutions or variants.

• .gif: All thumbnails use the GIF format for small file size and broad browser compatibility.

Locating Thumbnails Programmatically

Because the hash component is not predictable or stored in the JSON metadata, the most reliable approach is to scan the videos/ directory using the zero-padded ID as a search prefix.

import os
import glob

VIDEOS_DIR = "videos"

def thumbnail_path(exercise_id: int) -> str | None:
    """Return the filesystem path of the thumbnail GIF for a given exercise ID."""
    prefix = f"{exercise_id:04d}-"
    pattern = os.path.join(VIDEOS_DIR, f"{prefix}*.gif")
    matches = glob.glob(pattern)
    return matches[0] if matches else None

# Example: resolve the thumbnail for exercise #111

path = thumbnail_path(111)
print(path)   # → videos/0111-6HiHHe0.gif

This pattern matching approach allows your application to resolve the full filename—including the unpredictable hash—at runtime.

Referencing Thumbnails in Web Applications

Once you have constructed the full filename, you can reference the raw file directly from the repository:

<img src="https://github.com/hasaneyldrm/exercises-dataset/raw/main/videos/0111-6HiHHe0.gif"
     alt="Exercise 111 thumbnail" />

Alternatively, serve the files from a local clone or CDN mirror that preserves the videos/ directory structure.

Summary

• Exercises media file naming convention follows the strict pattern <id>-<hash>.gif within the videos/ directory.
• The exercise ID is zero-padded to four digits (e.g., 0111 for ID 111) to match the schema in data/exercises.json.
• The unique hash prevents filename collisions but requires directory scanning or glob patterns to resolve programmatically.
• All thumbnails are stored as GIF files for consistent rendering across platforms.

Frequently Asked Questions

What is the exact format for exercise thumbnail filenames?

Thumbnail filenames follow <exercise-id>-<unique-hash>.gif, where the exercise ID is zero-padded to four digits and the unique hash is a 6–8 character alphanumeric string. For example, exercise 10 uses the filename 0010-8K0w2yA.gif.

How do I find the thumbnail for a specific exercise ID?

Scan the videos/ directory for files matching the pattern {id:04d}-*.gif using glob.glob() or similar directory listing methods. Since the hash is not predictable, you must match against the zero-padded ID prefix rather than constructing the full filename directly.

Why does the filename include a random hash?

The hash component prevents collisions when multiple media assets are generated for the same exercise, such as different resolutions or processing variants. This allows the repository to store multiple versions without overwriting existing files.

Are all media files in the repository GIF format?

Yes, according to the current implementation in hasaneyldrm/exercises-dataset, all thumbnail previews in the videos/ directory use the .gif extension, which provides small file size and universal browser support.

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