mkv-episode-matcher 0.4.0

The MKV Episode Matcher is a tool for identifying TV series episodes from MKV files and renaming the files accordingly.

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. Download .srt subtitles files to ~/.mkv-episode-matcher/cache/data/Show Name/

3. Run on your show directory:

mkv-match --show-dir "path/to/your/show"

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