# 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:
   ```bash
   pip install -r requirements.txt
   ```
3. (Optional) Set up your TVDB API key:
   ```bash
   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:

```json
{
  "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):
```bash
python episode_matcher.py "/path/to/episode/folder" "Show Name" 1
```

With command-line API key (overrides config):
```bash
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):
```bash
python episode_matcher.py "/path/to/episode/folder" "Breaking Bad" 2 --dry-run --verbose
```

Setup configuration interactively:
```bash
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](https://thetvdb.com/api-information). 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)