Episode Matcher

A tool to automatically classify, organize, and rename TV show episode files for use with media servers like Jellyfin.

Features

• Automatic Classification: Distinguishes between episode files and extras based on file size and video duration
• TVDB Integration: Fetches episode data from TheTVDB for accurate matching and validation
• Jellyfin Compatible: Renames files using Jellyfin naming convention (Show Name s01e01.mkv)
• Extras Organization: Moves extra files (deleted scenes, behind-the-scenes, etc.) to an "extras" subfolder
• Duration Matching: Matches files to episodes based on video duration for accurate episode numbering
• Validation: Ensures all expected episodes for a season are processed

Installation

1. Clone or download this repository
2. Install dependencies:

   pip install -r requirements.txt
   

3. (Optional) Set up your TVDB API key:

   python setup_config.py
   

   Or manually edit config.json and replace YOUR_TVDB_API_KEY_HERE with your actual API key.

Configuration

The tool uses a config.json file for settings:

{
  "tvdb_api_key": "YOUR_TVDB_API_KEY_HERE",
  "default_episode_duration": 45,
  "classification_thresholds": {
    "size_threshold_ratio": 0.3,
    "duration_threshold_ratio": 0.4
  }
}

• tvdb_api_key: Your TVDB API key (get one free at https://thetvdb.com/api-information)
• default_episode_duration: Default episode length in minutes for mock data
• classification_thresholds: Ratios used to classify files as extras

Usage

Basic usage (API key from config.json):

python episode_matcher.py "/path/to/episode/folder" "Show Name" 1

With command-line API key (overrides config):

python episode_matcher.py "/path/to/episode/folder" "Game of Thrones" 1 --api-key YOUR_TVDB_API_KEY

Dry run (preview changes without modifying files):

python episode_matcher.py "/path/to/episode/folder" "Breaking Bad" 2 --dry-run --verbose

Setup configuration interactively:

python setup_config.py

Arguments

• folder_path: Path to the folder containing MKV files
• show_name: Name of the TV show (e.g., "Game of Thrones")
• season_number: Season number (1, 2, 3, etc.)
• --api-key: Optional TVDB API key (overrides config.json setting)
• --dry-run: Preview changes without modifying files
• --verbose: Show detailed analysis and file information

How It Works

1. File Analysis: Scans the folder for MKV files and analyzes their file sizes and video durations
2. Classification: Uses statistical analysis to identify which files are likely episodes vs. extras
3. TVDB Lookup: Fetches episode information from TheTVDB including episode count and durations
4. Duration Matching: Matches video files to episodes based on duration similarity
5. Organization: Moves extras to "extras" subfolder and renames episodes using Jellyfin format
6. Validation: Ensures all expected episodes were processed successfully

File Naming Convention

Episodes are renamed following the Jellyfin standard:

• Format: Show Name s##e##.mkv
• Examples:
  • Game of Thrones s01e04.mkv
  • Breaking Bad s02e13.mkv
  • The Office s03e01.mkv

Classification Logic

Files are classified as extras if they:

• Are significantly smaller than the average file size (< 30% of average)
• Have significantly shorter duration than average (< 40% of average)
• Exceed the expected number of episodes for the season

TVDB API

To get accurate episode data, you can obtain a free API key from TheTVDB. Without an API key, the tool will use mock data with typical episode counts and durations.

Example Output

=== Episode Matcher ===
Folder: /Users/user/TV/Game of Thrones/Season 1
Show: Game of Thrones
Season: 1

Fetching episode data for 'Game of Thrones' season 1...
Found 10 episodes in TVDB data

=== Classification Results ===
Episodes: 10
Extras: 3

=== Moving 3 extras to subfolder ===
Moved to extras: deleted_scenes.mkv
Moved to extras: making_of.mkv
Moved to extras: cast_commentary.mkv

=== Renaming 10 episodes ===
Renamed: GOT.S01E01.1080p.mkv → Game of Thrones s01e01.mkv
Renamed: GOT.S01E02.1080p.mkv → Game of Thrones s01e02.mkv
...

✓ Successfully renamed all 10 episodes for season 1

Requirements

• Python 3.6+
• pymediainfo (for video duration analysis)
• requests (for TVDB API calls)

Limitations

• Currently supports MKV files only
• Requires MediaInfo for accurate duration detection
• TVDB API has rate limits (should not be an issue for normal usage)