MKV Episode Matcher

Automatically match and rename your MKV TV episodes using The Movie Database (TMDb).

Features

• 🎯 Automatic Episode Matching: Uses TMDb to accurately identify episodes
• 📝 Subtitle Extraction: Extracts subtitles from MKV files
• 🔍 OCR Support: Handles image-based subtitles
• 🚀 Multi-threaded: Fast processing of multiple files
• ⬇️ Subtitle Downloads: Integration with OpenSubtitles
• ✨ Bulk Processing: Handle entire seasons at once
• 🧪 Dry Run Mode: Test changes before applying

Prerequisites

• Python 3.9 or higher
• FFmpeg installed and available in system PATH
• Tesseract OCR installed (required for image-based subtitle processing)
• TMDb API key
• OpenSubtitles account (optional, for subtitle downloads)

Quick Start

1. Install the package:

pip install mkv-episode-matcher

2. Run on your show directory:

mkv-match --show-dir "path/to/your/show" --get-subs true

Documentation

Full documentation is available at https://jsakkos.github.io/mkv-episode-matcher/

Directory Structure

MKV Episode Matcher expects your TV shows to be organized as follows:

Show Name/
├── Season 1/
│   ├── episode1.mkv
│   ├── episode2.mkv
├── Season 2/
│   ├── episode1.mkv
│   └── episode2.mkv

Reference Subtitle File Structure

Subtitle files that are not automatically downloaded using the --get-subs flag should be named as follows:

~/.mkv-episode-matcher/cache/data/Show Name/
├── Show Name - S01E01.srt
├── Show Name - S01E02.srt
└── ...

On Windows, the cache directory is located at C:\Users\{username}\.mkv-episode-matcher\cache\data\

Reference subtitle files should follow this naming pattern: {show_name} - S{season:02d}E{episode:02d}.srt

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.

Acknowledgments

• TMDb for their excellent API
• OpenSubtitles for subtitle integration
• All contributors who have helped improve this project