Skip to content

MKV Episode Matcher

Development Status PyPI version License: MIT Documentation Status Downloads GitHub last commit GitHub issues Tests codecov

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