mkv-episode-matcher 0.1.13__tar.gz → 0.3.0__tar.gz

mkv_episode_matcher-0.3.0/.github/workflows/documentation.yml

@@ -0,0 +1,41 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Configure Git
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          pip install mkdocs-material
+          pip install mkdocstrings[python]
+          pip install .
+
+      - name: Setup docs directory
+        run: |
+          cd docs
+          ln -sf ../README.md .
+
+      - name: Deploy documentation
+        run: mkdocs gh-deploy --force

mkv_episode_matcher-0.3.0/.python-version

@@ -0,0 +1 @@
+3.9

mkv_episode_matcher-0.3.0/.vscode/settings.json

@@ -0,0 +1,15 @@
+{
+    "python.testing.pytestArgs": [
+        "python.testing.pytestArgs": [
+            ".",
+            "--rootdir=.",
+            "-v",
+            "--tb=short"
+        ],
+        "python.testing.autoTestDiscoverOnSaveEnabled": true,
+        "python.testing.pytestEnabled": true,
+        "python.testing.unittestEnabled": false,
+        "python.testing.pytestArgs": [
+            "tests"
+        ]
+    }

mkv_episode_matcher-0.3.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.1
+Name: mkv-episode-matcher
+Version: 0.3.0
+Summary: The MKV Episode Matcher is a tool for identifying TV series episodes from MKV files and renaming the files accordingly.
+Home-page: https://github.com/Jsakkos/mkv-episode-matcher
+Author: Jonathan Sakkos
+Author-email: Jsakkos <jonathansakkos@gmail.com>
+License: MIT
+Project-URL: Documentation, https://github.com/Jsakkos/mkv-episode-matcher#readme
+Project-URL: Issues, https://github.com/Jsakkos/mkv-episode-matcher/issues
+Project-URL: Source, https://github.com/Jsakkos/mkv-episode-matcher
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: configparser>=7.1.0
+Requires-Dist: ffmpeg>=1.4
+Requires-Dist: loguru>=0.7.2
+Requires-Dist: openai-whisper>=20240930
+Requires-Dist: opensubtitlescom>=0.1.5
+Requires-Dist: pytesseract>=0.3.13
+Requires-Dist: rapidfuzz>=3.10.1
+Requires-Dist: requests>=2.32.3
+Requires-Dist: tmdb-client>=0.0.1
+Requires-Dist: wave>=0.0.2
+
+# MKV Episode Matcher
+
+[![Documentation Status](https://img.shields.io/github/actions/workflow/status/Jsakkos/mkv-episode-matcher/documentation.yml?label=docs)](https://jsakkos.github.io/mkv-episode-matcher/)
+[![PyPI version](https://badge.fury.io/py/mkv-episode-matcher.svg)](https://badge.fury.io/py/mkv-episode-matcher)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+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
+
+## Quick Start
+
+1. Install the package:
+```bash
+pip install mkv-episode-matcher
+```
+
+2. Run on your show directory:
+```bash
+mkv-match --show-dir "path/to/your/show" --season 1
+```
+
+## Requirements
+
+- Python 3.8 or higher
+- TMDb API key
+- OpenSubtitles account (optional, for subtitle downloads)
+
+## Documentation
+
+Full documentation is available at [https://jsakkos.github.io/mkv-episode-matcher/](https://jsakkos.github.io/mkv-episode-matcher/)
+
+## Basic Usage
+
+```python
+from mkv_episode_matcher import process_show
+
+# Process all seasons
+process_show()
+
+# Process specific season
+process_show(season=1)
+
+# Test run without making changes
+process_show(season=1, dry_run=True)
+
+# Process and download subtitles
+process_show(get_subs=True)
+```
+
+## 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
+```
+
+## 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](https://www.themoviedb.org/) for their excellent API
+- [OpenSubtitles](https://www.opensubtitles.com/) for subtitle integration
+- All contributors who have helped improve this project
+

mkv_episode_matcher-0.3.0/README.md

@@ -0,0 +1,90 @@
+# MKV Episode Matcher
+
+[![Documentation Status](https://img.shields.io/github/actions/workflow/status/Jsakkos/mkv-episode-matcher/documentation.yml?label=docs)](https://jsakkos.github.io/mkv-episode-matcher/)
+[![PyPI version](https://badge.fury.io/py/mkv-episode-matcher.svg)](https://badge.fury.io/py/mkv-episode-matcher)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+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
+
+## Quick Start
+
+1. Install the package:
+```bash
+pip install mkv-episode-matcher
+```
+
+2. Run on your show directory:
+```bash
+mkv-match --show-dir "path/to/your/show" --season 1
+```
+
+## Requirements
+
+- Python 3.8 or higher
+- TMDb API key
+- OpenSubtitles account (optional, for subtitle downloads)
+
+## Documentation
+
+Full documentation is available at [https://jsakkos.github.io/mkv-episode-matcher/](https://jsakkos.github.io/mkv-episode-matcher/)
+
+## Basic Usage
+
+```python
+from mkv_episode_matcher import process_show
+
+# Process all seasons
+process_show()
+
+# Process specific season
+process_show(season=1)
+
+# Test run without making changes
+process_show(season=1, dry_run=True)
+
+# Process and download subtitles
+process_show(get_subs=True)
+```
+
+## 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
+```
+
+## 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](https://www.themoviedb.org/) for their excellent API
+- [OpenSubtitles](https://www.opensubtitles.com/) for subtitle integration
+- All contributors who have helped improve this project
+

mkv_episode_matcher-0.3.0/docs/api/index.md

@@ -0,0 +1,38 @@
+# API Reference
+
+This section contains the automatically generated API documentation for MKV Episode Matcher.
+
+## Core Modules
+
+::: mkv_episode_matcher.episode_matcher
+    options:
+        show_root_heading: true
+        heading_level: 2
+
+## TMDB Client
+
+::: mkv_episode_matcher.tmdb_client
+    options:
+        show_root_heading: true
+        heading_level: 2
+
+## MKV Converter
+
+::: mkv_episode_matcher.mkv_to_srt
+    options:
+        show_root_heading: true
+        heading_level: 2
+
+## Utilities
+
+::: mkv_episode_matcher.utils
+    options:
+        show_root_heading: true
+        heading_level: 2
+
+## Configuration
+
+::: mkv_episode_matcher.config
+    options:
+        show_root_heading: true
+        heading_level: 2

mkv_episode_matcher-0.3.0/docs/cli.md

@@ -0,0 +1,91 @@
+# Command Line Interface
+
+## Basic Commands
+
+### Process Show
+
+```bash
+mkv-match --show-dir "/path/to/show"
+```
+
+### Process Specific Season
+
+```bash
+mkv-match --show-dir "/path/to/show" --season 1
+```
+
+## Command Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--show-dir` | Show directory path | None |
+| `--season` | Season number to process | None (all) |
+| `--dry-run` | Test without making changes | False |
+| `--get-subs` | Download subtitles | False |
+| `--tmdb-api-key` | TMDb API key | None |
+| `--tesseract-path` | Path to Tesseract | None |
+
+## Examples
+
+### Dry Run Mode
+
+```bash
+mkv-match --show-dir "/path/to/show" --dry-run true
+```
+
+### Download Subtitles
+
+```bash
+mkv-match --show-dir "/path/to/show" --get-subs true
+```
+
+### Set API Key
+
+```bash
+mkv-match --show-dir "/path/to/show" --tmdb-api-key "your_key"
+```
+
+### Multiple Options
+
+```bash
+mkv-match \
+  --show-dir "/path/to/show" \
+  --season 1 \
+  --get-subs true \
+  --dry-run true
+```
+
+## Environment Variables
+
+Alternative to command line options:
+
+```bash
+export TMDB_API_KEY="your_key"
+export SHOW_DIR="/path/to/shows"
+mkv-match
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Configuration error |
+| 3 | API error |
+
+## Logging
+
+Logs are stored in:
+```
+~/.mkv-episode-matcher/logs/
+├── stdout.log
+└── stderr.log
+```
+
+## Tips
+
+1. Always use quotes around paths
+2. Use dry-run first to test
+3. Check logs for details
+4. Use full paths for reliability

mkv_episode_matcher-0.3.0/docs/configuration.md

@@ -0,0 +1,105 @@
+# Configuration Guide
+
+## Configuration File
+
+MKV Episode Matcher uses a configuration file located at:
+
+- Windows: `%USERPROFILE%\.mkv-episode-matcher\config.ini`
+- Linux/Mac: `~/.mkv-episode-matcher/config.ini`
+
+## Configuration Options
+
+```ini
+[Config]
+# Required Settings
+tmdb_api_key = your_tmdb_api_key
+show_dir = /path/to/shows
+
+# Optional Settings
+max_threads = 4
+open_subtitles_api_key = your_opensubs_key
+open_subtitles_user_agent = your_user_agent
+open_subtitles_username = your_username
+open_subtitles_password = your_password
+tesseract_path = /path/to/tesseract
+```
+
+## Command Line Configuration
+
+All configuration options can be set via command line:
+
+```bash
+mkv-match \
+  --tmdb-api-key "your_key" \
+  --show-dir "/path/to/shows" \
+  --season 1 \
+  --dry-run true \
+  --get-subs true \
+  --tesseract-path "/path/to/tesseract"
+```
+
+## Environment Variables
+
+You can also use environment variables:
+
+```bash
+export TMDB_API_KEY="your_key"
+export SHOW_DIR="/path/to/shows"
+export OPEN_SUBTITLES_API_KEY="your_key"
+```
+
+## Configuration Priority
+
+Settings are loaded in the following order (later overrides earlier):
+
+1. Default values
+2. Configuration file
+3. Environment variables
+4. Command line arguments
+
+## Detailed Options
+
+### TMDb Configuration
+
+```ini
+[Config]
+tmdb_api_key = your_api_key
+```
+
+The TMDb API key is required for:
+- Show identification
+- Episode information
+- Season details
+
+### OpenSubtitles Configuration
+
+```ini
+[Config]
+open_subtitles_api_key = your_key
+open_subtitles_user_agent = your_agent
+open_subtitles_username = username
+open_subtitles_password = password
+```
+
+Required only if using subtitle download functionality.
+
+### Performance Settings
+
+```ini
+[Config]
+max_threads = 4
+```
+
+Adjust based on your system's capabilities:
+- Default: 4 threads
+- Minimum: 1 thread
+- Maximum: Number of CPU cores
+
+### OCR Configuration
+
+```ini
+[Config]
+tesseract_path = /path/to/tesseract
+```
+
+Required only if processing image-based subtitles.

mkv_episode_matcher-0.3.0/docs/installation.md

@@ -0,0 +1,81 @@
+# Installation Guide
+
+## Basic Installation
+
+Install MKV Episode Matcher using pip:
+
+```bash
+pip install mkv-episode-matcher
+```
+
+## Installation Options
+
+### GPU Support
+
+For GPU acceleration (recommended if you have a CUDA-capable GPU):
+
+```bash
+pip install "mkv-episode-matcher"
+```
+Find the appropriate CUDA version and upgrade Torch (e.g., for CUDA 12.4):
+```bash
+pip install -U torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124
+```
+
+
+### Development Installation
+
+For contributing or development:
+
+```bash
+# Clone the repository
+git clone https://github.com/Jsakkos/mkv-episode-matcher.git
+cd mkv-episode-matcher
+
+# Install UV
+pip install uv
+
+# Install with development dependencies
+uv venv
+uv pip install -e ".[dev]"
+```
+
+## API Keys Setup
+
+1. **TMDb API Key**
+    - Create an account at [TMDb](https://www.themoviedb.org/)
+    - Go to your account settings
+    - Request an API key
+
+2. **OpenSubtitles (Optional)**
+    - Register at [OpenSubtitles](https://www.opensubtitles.com/)
+    - Get your API key from the dashboard
+
+## System Requirements
+
+### For GPU Support
+- CUDA-capable NVIDIA GPU
+- CUDA Toolkit 12.1 or compatible version
+- At least 4GB GPU memory recommended for Whisper speech recognition
+
+### For CPU-Only
+- No special requirements beyond Python 3.9+
+
+## Verification
+
+Verify your installation:
+
+```bash
+mkv-match --version
+
+# Check GPU availability (if installed with GPU support)
+python -c "import torch; print(f'GPU available: {torch.cuda.is_available()}')"
+```
+
+## Troubleshooting
+
+If you encounter any issues:
+1. Ensure you have the latest pip: `pip install --upgrade pip`
+2. For GPU installations, verify CUDA is properly installed
+3. Check the [compatibility matrix](https://pytorch.org/get-started/locally/) for PyTorch and CUDA versions
+4. If you encounter any other issues, please [open an issue](https://github.com/Jsakkos/mkv-episode-matcher/issues) on GitHub

mkv_episode_matcher-0.3.0/docs/quickstart.md

@@ -0,0 +1,79 @@
+# Quick Start Guide
+
+Get started with MKV Episode Matcher in minutes.
+
+## Basic Usage
+
+### 1. Process a Single Season
+
+```bash
+mkv-match --show-dir "/path/to/show" --season 1
+```
+
+### 2. Process All Seasons
+
+```bash
+mkv-match --show-dir "/path/to/show"
+```
+
+### 3. Test Run (No Changes)
+
+```bash
+mkv-match --show-dir "/path/to/show" --dry-run true
+```
+
+### 4. Download Subtitles
+
+```bash
+mkv-match --show-dir "/path/to/show" --get-subs true
+```
+
+## 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
+```
+
+## Python API Usage
+
+```python
+from mkv_episode_matcher import process_show
+
+# Process all seasons
+process_show()
+
+# Process specific season
+process_show(season=1)
+
+# Test run
+process_show(season=1, dry_run=True)
+
+# With subtitles
+process_show(season=1, get_subs=True)
+```
+
+## Configuration
+
+Create a configuration file at `~/.mkv-episode-matcher/config.ini`:
+
+```ini
+[Config]
+tmdb_api_key = your_api_key
+open_subtitles_api_key = your_opensubs_key
+show_dir = /path/to/shows
+max_threads = 4
+```
+
+## Next Steps
+
+- Check the [Configuration Guide](configuration.md) for detailed setup
+- See [Tips and Tricks](tips.md) for advanced usage
+- Browse the [API Reference](api/episode_matcher.md) for detailed documentation