mkv-episode-matcher 0.8.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
• 🎨 Rich User Interface: Color-coded output and progress indicators
• 📝 Subtitle Extraction: Extracts subtitles from MKV files
• 🔊 Speech Recognition: Uses Whisper for accurate episode identification
• 🚀 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
• 🎮 Interactive Mode: User-friendly season selection and configuration

Prerequisites

• Python 3.9-3.12
• FFmpeg installed and available in system PATH
• TMDb API key (optional, for subtitle downloads)
• 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"

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

Documentation

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

Changelog

See CHANGELOG.md for a detailed list of changes.