145 lines
4.6 KiB
Markdown
145 lines
4.6 KiB
Markdown
# 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)
|