MKV2CAST(1)

NAME
mkv2cast - Smart MKV to Chromecast-compatible converter with hardware acceleration

SYNOPSIS
mkv2cast [OPTIONS] [FILE]

DESCRIPTION
mkv2cast is a smart video converter that transforms MKV files into formats compatible with Chromecast devices and Smart TVs. It intelligently detects which video and audio streams need transcoding and uses hardware acceleration (VAAPI, QSV) when available for faster encoding.

The tool features:

•   Automatic detection of compatible codecs (H.264, AAC)

•   Hardware acceleration via Intel VAAPI or Quick Sync Video (QSV)

•   Parallel processing with configurable workers

•   Recursive directory scanning

•   Rich progress display with ETA

•   Integrity checking of source files

•   Conversion history and statistics

When run without arguments, mkv2cast scans the current directory (recursively by default) for MKV files and converts those that need transcoding.

OPTIONS

  General Options

-V, --version
    Display version information, author, and license, then exit.

-h, --help
    Display help message and exit.

FILE
    Optional MKV file to process. If not specified, scans the current directory.

  Output Settings

--suffix SUFFIX
    Output file suffix. Default: .cast
    Example: movie.mkv becomes movie.h264.aac.cast.mkv

--container FORMAT
    Output container format. Choices: mkv, mp4. Default: mkv

  Scan Settings

-r, --recursive
    Scan directories recursively. This is the default behavior.

--no-recursive
    Disable recursive scanning; only process files in the current directory.

-I PATTERN, --ignore-pattern PATTERN
    Ignore files matching the glob pattern. Can be used multiple times.
    Examples: -I '*sample*', -I '*.eng.*'

--ignore-path PATH
    Ignore files in specific paths or folders. Can be used multiple times.
    Examples: --ignore-path Downloads/temp, --ignore-path SomeFolder

-i PATTERN, --include-pattern PATTERN
    Only process files matching the glob pattern. Can be used multiple times.
    Examples: -i '*2024*', -i '*.French.*'

--include-path PATH
    Only process files in matching paths. Can be used multiple times.
    Examples: --include-path Movies, --include-path /data/films

  Watch Mode

--watch
    Monitor a directory for new MKV files and convert automatically. Use the optional positional argument (file or directory) to set the watch path; defaults to the current directory.

--watch-interval SECONDS
    Polling interval for watch mode when watchdog/inotify is not available. Default: 5 seconds.

  Debug/Test Options

-d, --debug
    Enable debug output showing detailed processing information.

-n, --dryrun
    Dry run mode - show commands without executing them.

  Codec Decisions

--skip-when-ok
    Skip files that are already compatible. This is the default behavior.

--no-skip-when-ok
    Process all files even if they are already compatible.

--force-h264
    Force H.264 transcoding even if the video is already H.264.

--allow-hevc
    Allow HEVC (H.265) passthrough for SDR 8-bit content. By default, HEVC is transcoded to H.264 for better compatibility.

--force-aac
    Force AAC transcoding even if the audio is already AAC.

--keep-surround
    Keep surround audio channels. By default, audio is downmixed to stereo.

--no-silence
    Don't add a silent audio track if the source has no audio.

  Encoding Quality

--abr BITRATE
    Audio bitrate. Default: 192k

--crf VALUE
    CRF (Constant Rate Factor) value for CPU encoding. Lower values mean better quality but larger files. Default: 20
    Recommended range: 18-28

--preset PRESET
    x264 encoding preset. Slower presets give better compression.
    Choices: ultrafast, superfast, veryfast, faster, fast, medium, slow, slower, veryslow
    Default: slow

  Profiles

--profile NAME
    Apply encoding profile. Choices: fast, balanced, quality. Profiles set CRF, preset, and hardware quality defaults.

  Hardware Acceleration

--hw BACKEND
    Hardware acceleration backend to use.
    Choices: auto (default), nvenc, amf, qsv, vaapi, cpu

    auto
        Automatically detect the best available backend (priority: NVENC > AMF > QSV > VAAPI > CPU).

    nvenc
        Use NVIDIA NVENC (NVIDIA GPUs).

    amf Use AMD AMF (AMD GPUs with GCN 2.0+).

    qsv Use Intel Quick Sync Video.

    vaapi
        Use Video Acceleration API (Intel/AMD GPUs on Linux).

    cpu Use software encoding (libx264).

--vaapi-device PATH
    VAAPI device path. Default: /dev/dri/renderD128

--vaapi-qp VALUE
    VAAPI quantization parameter. Default: 23

--qsv-quality VALUE
    QSV quality value. Default: 23

--nvenc-cq VALUE
    NVENC constant quality (0-51, lower = better). Default: 23

--amf-quality VALUE
    AMD AMF quality (0-51, lower = better). Default: 23

  Audio Selection

--audio-lang LANGS
    Comma-separated language priority for audio tracks (e.g., fre,fra,fr,eng). Falls back to the first available track.

--audio-track INDEX
    Explicit audio track index (0-based). Overrides language preference when set.

  Subtitle Selection

--subtitle-lang LANGS
    Comma-separated subtitle languages to include (e.g., fre,eng).

--subtitle-track INDEX
    Explicit subtitle track index (0-based).

--prefer-forced-subs
    Prefer forced subtitles in the selected audio language (default).

--no-forced-subs
    Do not prefer forced subtitles when selecting tracks.

--no-subtitles
    Disable all subtitle embedding.

  Preservation

--no-metadata
    Disable metadata preservation.

--no-chapters
    Disable chapter preservation.

--no-attachments
    Disable MKV attachment preservation (fonts, cover art).

  Integrity Checks

--integrity-check
    Enable integrity check of source files before processing. This is the default.

--no-integrity-check
    Disable integrity check.

--stable-wait SECONDS
    Seconds to wait for file size stability check. Default: 3
    This helps ensure files are fully downloaded/copied before processing.

--deep-check
    Enable deep decode check. This decodes the entire video stream to verify integrity but is slow.

  Disk Guards

--min-free-mb MB
    Minimum free space to keep in the output filesystem. Default: 1024.

--min-free-tmp-mb MB
    Minimum free space to keep in the temp filesystem. Default: 512.

--max-output-mb MB
    Maximum output size per file (0 disables). Default: 0.

--max-output-ratio RATIO
    Maximum output size ratio vs input (0 disables). Default: 0.0.

  UI Settings

--no-progress
    Disable progress bar display.

--bar-width WIDTH
    Progress bar width for legacy mode. Default: 26

--ui-refresh-ms MS
    UI refresh interval in milliseconds. Default: 120

--stats-period SECONDS
    FFmpeg stats period in seconds. Default: 0.2

  Pipeline Mode

--pipeline
    Enable parallel processing pipeline. This is the default.

--no-pipeline
    Disable parallel processing; use sequential mode.

--json-progress
    Output structured JSON progress events to stdout. Each line is a JSON object with event type and progress data. Useful for integration with web UIs, monitoring tools, or custom scripts.
    Events: start, file_checking, file_start, progress, file_done, complete.

  Parallelism

--encode-workers N
    Number of parallel encoding workers. Default: 0 (auto-detect based on system resources).

--integrity-workers N
    Number of parallel integrity check workers. Default: 0 (auto-detect).

  Reliability

--retry-attempts N
    Number of retries after failure (0 disables). Default: 1.

--retry-delay SECONDS
    Delay between retries. Default: 2.0.

--no-retry-fallback-cpu
    Disable CPU fallback on the last retry.

  Notifications

--notify
    Send desktop notification when processing completes. This is the default. Uses notify-send (libnotify) or plyer as fallback.

--no-notify
    Disable desktop notifications.

  Internationalization

--lang LANG
    Force user interface language. Supported languages: en (English), fr (French), es (Spanish), it (Italian), de (German).
    If not specified, the language is auto-detected from the system locale. Can also be set via the MKV2CAST_LANG environment variable.

  Utility Commands
These commands perform a specific action and exit immediately.

--show-dirs
    Show XDG directory paths used by mkv2cast and exit.

--history [N]
    Show recent conversion history and exit. Optionally specify the number of entries to display (default: 20, max: 1000).
    Examples: --history (20 lines), --history 50, --history 100

--history-stats
    Show conversion statistics and exit.

--clean-tmp
    Clean orphaned temporary files from cache directory and exit.
    When run as root, cleans temp files for all users on the system.

--clean-logs DAYS
    Remove log files older than N days and exit.
    When run as root, cleans logs for all users on the system.

--clean-history DAYS
    Remove history entries older than N days and exit.

--check-requirements
    Check system requirements and Python dependencies, then exit. Useful for troubleshooting installation issues.

FILES
mkv2cast follows the XDG Base Directory Specification.

  User Configuration

~/.config/mkv2cast/config.toml
    User configuration file (TOML format if tomllib/tomli available).

~/.config/mkv2cast/config.ini
    User configuration file (INI format fallback).

  System Configuration (optional)

/etc/mkv2cast/config.toml
    System-wide configuration file. User config overrides system config. Only created during system-wide installation.

  State and Cache

~/.local/state/mkv2cast/history.db
    SQLite database storing conversion history.

~/.local/state/mkv2cast/history.log
    JSONL fallback for history if SQLite unavailable.

~/.local/state/mkv2cast/logs/
    Directory containing per-conversion log files.

~/.cache/mkv2cast/tmp/
    Temporary files during encoding (automatically cleaned).

OUTPUT NAMING
Output files are named based on the transformations applied:

movie.h264.cast.mkv
    Video transcoded to H.264, audio copied.

movie.aac.cast.mkv
    Video copied, audio transcoded to AAC.

movie.h264.aac.cast.mkv
    Both video and audio transcoded.

movie.remux.cast.mkv
    File remuxed (container changed, streams copied).

EXIT STATUS

0   Success - all files processed without errors.

2   Some files failed to convert.

130 Interrupted by user (SIGINT/Ctrl+C).

EXAMPLES

mkv2cast
    Process all MKV files in the current directory recursively.

mkv2cast movie.mkv
    Process a single file.

mkv2cast --hw cpu --preset fast
    Use CPU encoding with fast preset for quicker (lower quality) encoding.

mkv2cast --debug --dryrun
    Show what would be done without actually processing files.

mkv2cast -I '*sample*' -I '*.eng.*'
    Ignore sample files and files with .eng. in the name.

mkv2cast -i '*French*' -i '*2024*'
    Only process files with French or 2024 in the filename.

mkv2cast --encode-workers 2 --integrity-workers 3
    Use 2 parallel encoding processes and 3 integrity checkers.

mkv2cast --no-recursive --container mp4
    Process only current directory, output to MP4 format.

mkv2cast --allow-hevc --keep-surround
    Allow HEVC passthrough and keep surround sound.

mkv2cast --check-requirements
    Verify all system requirements are installed.

CONFIGURATION
A default configuration file is created on first run at ~/.config/mkv2cast/config.toml (or config.ini if TOML is unavailable).

Example config.toml:

    [output]
    suffix = ".cast"
    container = "mkv"
    [scan]
    recursive = true
    ignore_patterns = []
    ignore_paths = []
    [encoding]
    backend = "auto"
    crf = 20
    preset = "slow"
    abr = "192k"
    [workers]
    encode = 0
    integrity = 0
    [integrity]
    enabled = true
    stable_wait = 3
    deep_check = false

Command-line arguments override configuration file values.

ENVIRONMENT

MKV2CAST_LANG
    Override interface language. Takes precedence over system locale.
    Example: MKV2CAST_LANG=fr mkv2cast

MKV2CAST_SCRIPT_MODE
    When set to any value, forces script mode (disables UI features). Useful when embedding mkv2cast in scripts.

NO_COLOR
    When set, disables all colored output (https://no-color.org/). Also triggers script mode detection.

XDG_CONFIG_HOME
    Configuration directory. Default: ~/.config

XDG_STATE_HOME
    State directory (history, logs). Default: ~/.local/state

XDG_CACHE_HOME
    Cache directory (temp files). Default: ~/.cache

NOTES

  Chromecast Compatibility
Chromecast devices support H.264 video (up to level 4.1) with AAC audio in MP4 or MKV containers. This tool ensures output files meet these requirements.

  Audio Track Selection
By default, mkv2cast prefers French audio tracks. If no French track is found, it uses the first available audio track.

  Recursive Scanning
The --recursive option is enabled by default. Use --no-recursive to process only the current directory.

  Temporary Files
During encoding, temporary files are created in ~/.cache/mkv2cast/tmp/. These are automatically cleaned on successful completion. Use --clean-tmp to remove orphaned temp files.

  System-wide Cleanup (Root)
When --clean-tmp or --clean-logs is run as root, mkv2cast automatically cleans temp files and logs for all users on the system. This is useful for system-wide installations with a systemd timer.
System-wide cleanup respects each user's configuration.

SEE ALSO
ffmpeg(1), ffprobe(1), catt(1)

Project homepage (https://github.com/voldardard/mkv2cast)

Google Cast supported media formats (https://developers.google.com/cast/docs/media)

BUGS
Report bugs at: https://github.com/voldardard/mkv2cast/issues

AUTHOR
Written by voldardard.

COPYRIGHT
Copyright © 2024-2026 voldardard.
License: GPL-3.0 https://www.gnu.org/licenses/gpl-3.0.html

This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.