mkv-episode-matcher 1.3.2

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 advanced speech recognition and subtitle matching.

✨ Key Features

• 🌐 Modern Web Interface: Premium React-based UI with glassmorphism design and dark mode
• 🤖 Advanced Speech Recognition: OpenAI Whisper ASR via faster-whisper for accurate episode identification
• 🎯 Intelligent Matching: Multi-segment analysis with confidence scoring and fallback strategies
• ⬇️ Smart Subtitle Integration: Automatic subtitle downloads from OpenSubtitles with local caching
• ✨ Bulk Processing: Handle entire libraries with automatic series/season detection
• 📊 Real-time Progress: WebSocket-powered progress tracking with live updates
• ⚡ Performance Optimized: Caching, background model loading, and efficient processing

[!NOTE] First-Time Model Loading: The Whisper ASR model takes approximately 5-10 seconds to download and load on first use. The web UI shows a "System Loading" indicator during this time. Subsequent operations reuse the cached model and are much faster.

Prerequisites

• Python 3.10-3.12
• FFmpeg installed and available in system PATH
• TMDb API key
• OpenSubtitles.com account

🚀 Quick Start

1. Install MKV Episode Matcher

Option A: Windows Standalone Executable Download the latest Windows executable from GitHub Releases. No Python installation required!

Option B: pip (Cross-platform)

pip install mkv-episode-matcher[cpu]

Or for CUDA support:

pip install mkv-episode-matcher[cu128]

Option C: From Source with uv (For development/latest features)

First, install uv if you don't have it:

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

Then clone and install:

git clone https://github.com/Jsakkos/mkv-episode-matcher.git
cd mkv-episode-matcher

# Basic installation
uv sync --extra cpu

# Or with CUDA support for GPU acceleration
uv sync --extra cu128

For complete installation options, see the Installation Guide.

2. Launch the Application

🌐 Web interface (Recommended)

• Windows Executable: Double-click mkv-match.exe. It will launch the server and open your browser automatically.
• Pip/Source: Run the following command:

  mkv-match serve
  

  Access the UI at http://localhost:8001

💻 CLI Mode For automation and advanced users.

Windows Executable: Open a terminal in the folder containing the executable:

mkv-match.exe match "C:\Path\To\Show"

Pip/Source:

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

3. Build Standalone Executable

You can build a self-contained executable that bundles the backend and frontend.

Standard Build (CPU)

uv sync --extra cpu
uv run pyinstaller mkv_match.spec

CUDA-Enabled Build (NVIDIA GPU) To build an executable that utilizes your NVIDIA GPU for faster processing:

# 1. Install dependencies with CUDA support
uv sync --extra cu128

# 2. Build the executable
uv run pyinstaller mkv_match.spec

Output in dist/mkv-match/

🖥️ Web Interface Features

The new React-based interface provides:

• 🎨 Premium Design: Modern aesthetics with glassmorphism and smooth animations
• 📂 Visual File Browser: Intuitive navigation of your local file system
• ⏱️ Live Status: Real-time job tracking via WebSockets
• 📱 Responsive: Works identically on local machine or remote server access

Required API Keys:

• OpenSubtitles API Key: Required for subtitle downloads (Get one here)
• TMDb API Key: Optional, for enhanced episode metadata (Get one here)

OpenSubtitles Setup:

• Username and password (recommended for better rate limits)
• API key from the OpenSubtitles developer console

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.