mkv2cast 1.1.0

Smart MKV to Chromecast-compatible converter with hardware acceleration

mkv2cast

Smart MKV to Chromecast-compatible converter with hardware acceleration

Convert your MKV video files to formats compatible with Chromecast devices and Smart TVs, using intelligent codec detection and hardware-accelerated encoding.

---

Table of Contents

• Features
• Distribution
• Purpose
• Tested Devices
• Prerequisites
• Installation
• Configuration
• Usage
• Options Reference
• Examples
• Maintenance
• Points de Vigilance
• Troubleshooting
• Contributing
• Bug Reports
• Roadmap
• Acknowledgments
• License

---

Features

• Intelligent Codec Detection: Automatically analyzes video and audio streams to determine if transcoding is needed
• Hardware Acceleration: Supports Intel VAAPI and Quick Sync Video (QSV) for faster encoding
• Parallel Processing: Process multiple files simultaneously with configurable worker counts
• Rich Progress Display: Beautiful terminal UI with progress bars, ETA, and speed indicators
• Integrity Checking: Verifies source files before processing to avoid corrupted outputs
• Conversion History: Track all conversions with SQLite database and statistics
• Flexible Filtering: Include/exclude files using glob patterns or path filters
• XDG Compliant: Follows Linux standards for configuration, cache, and state directories
• Automatic Audio Selection: Prefers French audio tracks, falls back to first available
• Configurable: TOML/INI configuration file with sensible defaults
• Desktop Notifications: Get notified when conversions complete (via notify-send or plyer)
• Multi-Language Support: Available in English, French, Spanish, Italian, and German
• PyPI Distribution: Easy installation via pip install mkv2cast

---

Distribution

Version	1.1.0
Author	voldardard
Date	January 2026
License	GPL-3.0
Repository	https://github.com/voldardard/mkv2cast
PyPI	https://pypi.org/project/mkv2cast/
Documentation	https://mkv2cast.readthedocs.io

---

Purpose

mkv2cast was created to simplify the process of converting video files for playback on Chromecast devices and Smart TVs.

Many media files use codecs that aren't natively supported by Chromecast (like HEVC/H.265, AV1, or non-AAC audio). This tool:

1. Analyzes your MKV files to detect incompatible codecs
2. Transcodes only what's necessary (video, audio, or both)
3. Preserves compatible streams by copying them without re-encoding
4. Outputs Chromecast-compatible files ready for streaming

Integration with catt

This tool is designed to work seamlessly with catt (Cast All The Things), a command-line tool for casting videos to Chromecast devices:

# Convert your files first
mkv2cast movie.mkv

# Then cast to your TV
catt cast movie.h264.aac.cast.mkv

---

Tested Devices

mkv2cast has been tested and confirmed working with:

Device	Status	Notes
TCL 55C635	✅ Verified	Primary test device, 4K HDR
TCL 65C735	✅ Verified	Similar to 55C635
Chromecast (Gen 3)	✅ Verified	1080p
Chromecast with Google TV	✅ Verified	4K HDR
Chromecast Ultra	✅ Verified	4K HDR

Note: If you test with other devices, please submit a PR to update this list!

---

Prerequisites

Required

Dependency	Version	Installation
Python	3.8+	Pre-installed on most Linux systems
ffmpeg	4.0+	sudo pacman -S ffmpeg (Arch) / sudo apt install ffmpeg (Debian)
ffprobe	4.0+	Included with ffmpeg

Optional (Recommended)

Package	Purpose	Installation
rich	Beautiful progress UI	See below
tomli	TOML config support (Python < 3.11)	See below

Installing optional packages:

# Arch Linux (recommended - system packages)
sudo pacman -S python-rich
sudo pacman -S python-tomli  # Only needed for Python < 3.11

# Debian/Ubuntu
pip install --user rich tomli

# Other distributions
pip install --user rich tomli

Hardware Acceleration

For hardware-accelerated encoding:

• Intel VAAPI: Install intel-media-driver or libva-intel-driver
• Intel QSV: Install intel-media-sdk or oneVPL

Check your hardware support:

# List available encoders
ffmpeg -encoders 2>/dev/null | grep -E 'vaapi|qsv'

# Test VAAPI
ls -la /dev/dri/renderD128

# Check with mkv2cast
mkv2cast --check-requirements

---

Installation

PyPI (Recommended) 🚀

# Basic installation
pip install mkv2cast

# With all optional features (rich UI, notifications)
pip install "mkv2cast[full]"

Arch Linux (AUR)

yay -S mkv2cast

Script Install (One-Liner)

curl -fsSL https://raw.githubusercontent.com/voldardard/mkv2cast/main/install.sh | bash

The installer will:

• Download mkv2cast automatically
• Install to ~/.local/bin/
• Set up man page and shell completions
• Configure your PATH automatically (if needed)

After installation, reload your shell or run:

source ~/.bashrc  # or ~/.zshrc for Zsh users

Update

# PyPI
pip install --upgrade mkv2cast

# Script
curl -fsSL https://raw.githubusercontent.com/voldardard/mkv2cast/main/install.sh | bash -s -- --update

System-Wide Installation

For servers or multi-user systems, install to /usr/local:

curl -fsSL https://raw.githubusercontent.com/voldardard/mkv2cast/main/install.sh | sudo bash -s -- --system

System-wide cleanup: When cleanup commands are run as root, mkv2cast automatically cleans temp files and logs for all users:

# Clean temp files for all users (as root)
sudo mkv2cast --clean-tmp

# Clean logs for all users (as root)
sudo mkv2cast --clean-logs 30

A system-wide systemd timer is also available for automated cleanup.

Installation Options

Option	Description
--user	Install for current user only (default)
--system	Install system-wide (requires sudo)
--update	Update existing installation
--uninstall	Remove mkv2cast
--with-systemd	Install cleanup timer
--no-modify-rc	Don't modify shell config files

Alternative: Manual Clone

If you prefer to clone the repository:

git clone https://github.com/voldardard/mkv2cast.git
cd mkv2cast
./install.sh

Verify Installation

mkv2cast --version
mkv2cast --check-requirements
man mkv2cast

Uninstallation

# Quick uninstall
mkv2cast-uninstall

# Or via curl
curl -fsSL https://raw.githubusercontent.com/voldardard/mkv2cast/main/install.sh | bash -s -- --uninstall

Installation Paths

Mode	Script	Man Page	Completions	Config
User	~/.local/bin	~/.local/share/man/man1	~/.local/share/bash-completion	~/.config/mkv2cast
System	/usr/local/bin	/usr/local/share/man/man1	/etc/bash_completion.d	/etc/mkv2cast

---

Configuration

Configuration Files

mkv2cast uses a layered configuration system:

1. System config (optional): /etc/mkv2cast/config.toml

   • Applied to all users
   • Created only with --system installation

2. User config: ~/.config/mkv2cast/config.toml

   • Per-user settings
   • Overrides system config
   • Created automatically on first run

Priority: User config values always override system config values.

Example config.toml

[output]
suffix = ".cast"
container = "mkv"

[scan]
recursive = true
ignore_patterns = ["*sample*", "*.eng.*"]
ignore_paths = []
include_patterns = []
include_paths = []

[encoding]
backend = "auto"  # auto, vaapi, qsv, cpu
crf = 20
preset = "slow"
abr = "192k"

[workers]
encode = 0       # 0 = auto-detect
integrity = 0    # 0 = auto-detect

[integrity]
enabled = true
stable_wait = 3
deep_check = false

Directory Structure

mkv2cast follows the XDG Base Directory Specification:

User directories:

Directory	Purpose	Default Path
Config	User configuration	~/.config/mkv2cast/
State	History, logs	~/.local/state/mkv2cast/
Cache	Temporary files	~/.cache/mkv2cast/

System directories (only for system-wide installation):

Directory	Purpose	Default Path
Config	System-wide defaults	/etc/mkv2cast/

View all directories:

mkv2cast --show-dirs

---

Usage

Basic Usage

# Process all MKV files in current directory (recursive)
mkv2cast

# Process a single file
mkv2cast movie.mkv

# Process with debug output
mkv2cast --debug movie.mkv

# Dry run (show what would be done)
mkv2cast --dryrun

Output File Naming

Output files are named based on transformations applied:

Input	Output	Meaning
movie.mkv	movie.h264.cast.mkv	Video transcoded to H.264
movie.mkv	movie.aac.cast.mkv	Audio transcoded to AAC
movie.mkv	movie.h264.aac.cast.mkv	Both transcoded
movie.mkv	movie.remux.cast.mkv	Container changed only

Common Workflows

Convert entire movie collection

cd /path/to/movies
mkv2cast

Convert only French movies from 2024

mkv2cast -i '*French*' -i '*2024*'

Fast encoding (lower quality)

mkv2cast --hw cpu --preset fast --crf 23

High quality with hardware acceleration

mkv2cast --hw vaapi --vaapi-qp 20

Process without recursive scan

mkv2cast --no-recursive

---

Options Reference

General Options

Option	Description
-h, --help	Show help message
-V, --version	Show version information
--check-requirements	Check system requirements

Output Settings

Option	Default	Description
--suffix SUFFIX	.cast	Output file suffix
--container FORMAT	mkv	Output format: mkv or mp4

Scan Settings

Option	Default	Description
-r, --recursive	enabled	Scan directories recursively
--no-recursive	-	Disable recursive scanning
-I, --ignore-pattern PATTERN	-	Ignore files matching glob pattern
--ignore-path PATH	-	Ignore specific paths/folders
-i, --include-pattern PATTERN	-	Only process matching files
--include-path PATH	-	Only process files in path

Codec Decisions

Option	Default	Description
--skip-when-ok	enabled	Skip compatible files
--no-skip-when-ok	-	Process all files
--force-h264	disabled	Force H.264 transcoding
--allow-hevc	disabled	Allow HEVC passthrough
--force-aac	disabled	Force AAC transcoding
--keep-surround	disabled	Keep surround audio
--no-silence	-	Don't add silence track

Encoding Quality

Option	Default	Description
--abr BITRATE	192k	Audio bitrate
--crf VALUE	20	CRF for CPU encoding (18-28)
--preset PRESET	slow	x264 preset

Hardware Acceleration

Option	Default	Description
--hw BACKEND	auto	Backend: auto, vaapi, qsv, cpu
--vaapi-device PATH	/dev/dri/renderD128	VAAPI device
--vaapi-qp VALUE	23	VAAPI quality
--qsv-quality VALUE	23	QSV quality

Integrity Checks

Option	Default	Description
--integrity-check	enabled	Enable integrity check
--no-integrity-check	-	Disable integrity check
--stable-wait SECONDS	3	Wait for file stability
--deep-check	disabled	Deep decode verification

Parallelism

Option	Default	Description
--pipeline	enabled	Parallel processing
--no-pipeline	-	Sequential mode
--encode-workers N	0 (auto)	Parallel encoding workers
--integrity-workers N	0 (auto)	Parallel integrity workers

Utility Commands

Option	Description
--show-dirs	Show XDG directory paths
--history [N]	Show recent conversions (default: 20, max: 1000)
--history-stats	Show conversion statistics
--clean-tmp	Remove orphaned temp files (all users if root)
--clean-logs DAYS	Remove old log files (all users if root)
--clean-history DAYS	Remove old history entries

---

Examples

Filtering Examples

# Ignore sample files and English tracks
mkv2cast -I '*sample*' -I '*.eng.*'

# Process only French content
mkv2cast -i '*French*' -i '*VFF*' -i '*FRENCH*'

# Ignore specific folders
mkv2cast --ignore-path Downloads/temp --ignore-path "To Sort"

# Process only specific folder
mkv2cast --include-path Movies/2024

Encoding Examples

# Use CPU with fast preset (quick, lower quality)
mkv2cast --hw cpu --preset fast --crf 23

# Use VAAPI with high quality
mkv2cast --hw vaapi --vaapi-qp 18

# Keep surround sound
mkv2cast --keep-surround --abr 256k

# Output to MP4 instead of MKV
mkv2cast --container mp4

Parallel Processing Examples

# Use 3 parallel encoders
mkv2cast --encode-workers 3

# Disable parallel processing
mkv2cast --no-pipeline

# Custom worker configuration
mkv2cast --encode-workers 2 --integrity-workers 4

Maintenance Examples

# View conversion history (default: 20 lines)
mkv2cast --history

# View more history (50 or 100 lines)
mkv2cast --history 50
mkv2cast --history 100

# View statistics
mkv2cast --history-stats

# Clean temporary files
mkv2cast --clean-tmp

# Clean logs older than 30 days
mkv2cast --clean-logs 30

# Clean history older than 90 days
mkv2cast --clean-history 90

---

Maintenance

Automatic Cleanup with systemd

Install the systemd timer for weekly automatic cleanup:

./install.sh --with-systemd

Or manually:

# Copy service files
cp systemd/mkv2cast-cleanup.* ~/.config/systemd/user/

# Enable timer
systemctl --user enable --now mkv2cast-cleanup.timer

# Check status
systemctl --user status mkv2cast-cleanup.timer

Automatic Cleanup with cron

Add to your crontab (crontab -e):

# Weekly cleanup on Sunday at 3 AM
0 3 * * 0 mkv2cast --clean-tmp && mkv2cast --clean-logs 30

Manual Cleanup

# Clean orphaned temp files
mkv2cast --clean-tmp

# Clean logs older than 30 days
mkv2cast --clean-logs 30

# Clean history older than 90 days
mkv2cast --clean-history 90

---

Points de Vigilance

Important Notes

1. Recursive Scanning is Default

   • mkv2cast scans subdirectories by default
   • Use --no-recursive to process only the current directory
   • Be careful when running in large directory trees!

2. Original Files are Preserved

   • mkv2cast creates new output files, it does NOT modify originals
   • Output files have a distinct suffix (.cast.mkv by default)

3. Temporary Files

   • During encoding, temp files are created in ~/.cache/mkv2cast/tmp/
   • They are automatically cleaned on successful completion
   • Use --clean-tmp to remove orphaned temp files after interruption

4. French Audio Preference

   • By default, mkv2cast selects French audio tracks when available
   • Falls back to the first audio track if no French track found

5. HEVC/H.265 Transcoding

   • By default, HEVC content is transcoded to H.264
   • Use --allow-hevc if your device supports HEVC

6. Disk Space

   • Ensure sufficient disk space for output files
   • Temporary files can also consume significant space during encoding

---

Troubleshooting

Common Issues

"ffmpeg not found"

# Arch Linux
sudo pacman -S ffmpeg

# Debian/Ubuntu
sudo apt install ffmpeg

# Fedora
sudo dnf install ffmpeg

"VAAPI encoding failed"

# Check VAAPI device exists
ls -la /dev/dri/

# Install Intel drivers (for Intel GPUs)
sudo pacman -S intel-media-driver  # Arch
sudo apt install intel-media-va-driver  # Debian

# Test with mkv2cast
mkv2cast --check-requirements

"No progress display"

Install the rich Python package:

# Arch Linux
sudo pacman -S python-rich

# Other distributions
pip install --user rich

"Permission denied" errors

Ensure the script is executable and in your PATH:

chmod +x ~/.local/bin/mkv2cast
echo $PATH | grep -q ".local/bin" || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

"TOML config not loading"

For Python < 3.11, install tomli:

# Arch Linux
sudo pacman -S python-tomli

# Other distributions
pip install --user tomli

Getting Help

# Check requirements
mkv2cast --check-requirements

# View debug output
mkv2cast --debug movie.mkv

# Dry run to see commands
mkv2cast --dryrun movie.mkv

# Check logs
ls ~/.local/state/mkv2cast/logs/

---

Contributing

Contributions are welcome! Here's how to get started:

Development Setup

# Clone the repository
git clone https://github.com/voldardard/mkv2cast.git
cd mkv2cast

# Install development dependencies
# Arch Linux:
sudo pacman -S python-rich python-tomli
# Other distributions:
pip install --user rich tomli

# Run tests
python mkv2cast.py --check-requirements

Submitting Changes

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes
4. Test thoroughly
5. Commit with descriptive message: git commit -m "Add feature X"
6. Push to your fork: git push origin feature/my-feature
7. Open a Pull Request

Code Style

• Follow PEP 8 for Python code
• Add docstrings to new functions
• Update documentation for new features
• Test on both CPU and hardware-accelerated backends if possible

---

Bug Reports

Found a bug? Please report it!

How to Report

1. Go to GitHub Issues
2. Click "New Issue"
3. Include:
   • Your operating system and version
   • Python version (python3 --version)
   • FFmpeg version (ffmpeg -version)
   • mkv2cast version (mkv2cast --version)
   • Output of mkv2cast --check-requirements
   • Steps to reproduce the bug
   • Error messages or log files (from ~/.local/state/mkv2cast/logs/)

Example Bug Report

### Environment
- OS: Arch Linux 2026.01
- Python: 3.12.1
- FFmpeg: 7.0
- mkv2cast: 1.0.0

### Description
Encoding fails with VAAPI on AMD GPU...

### Steps to Reproduce
1. Run `mkv2cast --hw vaapi movie.mkv`
2. Error occurs at 15%

### Error Output
[paste error here]

---

Roadmap

Feature	Priority	Complexity	Status
Docker & WebUI	Medium	High	Planned
Watch mode (inotify)	Medium	Medium	Planned
NVIDIA NVENC support	Medium	Medium	Planned
Profiles (fast/balanced/quality)	Low	Low	Planned
Subtitle extraction	Low	Medium	Planned
HDR to SDR tone mapping	Low	High	Planned
Integration Plex/Jellyfin	Low	High	Planned

Recent Additions (v1.1.0)

• ✅ Multi-language support (EN, FR, ES, IT, DE)
• ✅ Desktop notifications
• ✅ PyPI distribution
• ✅ Comprehensive test suite
• ✅ GitHub Actions CI/CD
• ✅ AUR & Debian packaging
• ✅ Sphinx documentation

Have a feature request? Open an issue!

---

Acknowledgments

This section will be updated as the project grows.

Thanks to:

• The FFmpeg team for their incredible media processing tools
• The rich library for beautiful terminal interfaces
• All contributors and users who report bugs and suggest improvements

---

License

This project is licensed under the GNU General Public License v3.0.

mkv2cast - Smart MKV to Chromecast-compatible converter
Copyright (C) 2024-2026 voldardard

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.

See the LICENSE file for the full license text.

---

Made with ❤️ for the media enthusiast community