API Reference

mkv2cast can be used as a Python library for programmatic video conversion.

Main Modules

`mkv2cast`	mkv2cast - Smart MKV to Chromecast-compatible converter with hardware acceleration.
`mkv2cast.config`	Configuration management for mkv2cast.
`mkv2cast.converter`	Core conversion logic for mkv2cast.
`mkv2cast.history`	History database for mkv2cast conversions.
`mkv2cast.integrity`	File integrity checking for mkv2cast.
`mkv2cast.notifications`	Desktop notification support for mkv2cast.
`mkv2cast.i18n`	Internationalization (i18n) support for mkv2cast.

Quick Reference

Configuration

from mkv2cast import Config, get_app_dirs, load_config_file

# Create custom configuration
config = Config(
    suffix=".cast",
    container="mkv",
    hw="auto",
    crf=20,
    preset="slow",
    notify=True
)

# Get application directories
dirs = get_app_dirs()
print(dirs["config"])  # ~/.config/mkv2cast

Conversion

from mkv2cast import decide_for, pick_backend, convert_file
from pathlib import Path

# Analyze a file
decision = decide_for(Path("movie.mkv"))
print(f"Video: {decision.vcodec} -> need transcode: {decision.need_v}")
print(f"Audio: {decision.acodec} -> need transcode: {decision.need_a}")

# Auto-detect best backend
backend = pick_backend()
print(f"Using backend: {backend}")

# Convert file
success, output_path, message = convert_file(Path("movie.mkv"))

History

from mkv2cast import HistoryDB, get_app_dirs

dirs = get_app_dirs()
history = HistoryDB(dirs["state"])

# Get recent conversions
recent = history.get_recent(20)
for entry in recent:
    print(f"{entry['status']}: {entry['input_path']}")

# Get statistics
stats = history.get_stats()
print(f"Total done: {stats['by_status'].get('done', 0)}")

Notifications

from mkv2cast import send_notification

# Send a notification
send_notification(
    title="Conversion Complete",
    message="Successfully converted 5 files",
    urgency="normal"
)

Internationalization

from mkv2cast import setup_i18n, _

# Setup French translations
setup_i18n("fr")

# Use translations
print(_("Conversion complete"))  # "Conversion terminée"

Decision Class

class mkv2cast.converter.Decision(need_v: bool, need_a: bool, aidx: int, add_silence: bool, reason_v: str, vcodec: str, vpix: str, vbit: int, vhdr: bool, vprof: str, vlevel: int, acodec: str, ach: int, alang: str, format_name: str, sidx: int = -1, slang: str = '', sforced: bool = False)[source]

Bases: object

Decision about what transcoding is needed for a file.

need_v: bool

need_a: bool

aidx: int

add_silence: bool

reason_v: str

vcodec: str

vpix: str

vbit: int

vhdr: bool

vprof: str

vlevel: int

acodec: str

ach: int

alang: str

format_name: str

sidx: int = -1

slang: str = ''

sforced: bool = False

Config Class

class mkv2cast.config.Config(suffix: str = '.cast', container: str = 'mkv', recursive: bool = True, ignore_patterns: List[str] = <factory>, ignore_paths: List[str] = <factory>, include_patterns: List[str] = <factory>, include_paths: List[str] = <factory>, debug: bool = False, dryrun: bool = False, skip_when_ok: bool = True, force_h264: bool = False, allow_hevc: bool = False, force_aac: bool = False, keep_surround: bool = False, add_silence_if_no_audio: bool = True, abr: str = '192k', crf: int = 20, preset: str = 'slow', profile: str | None = None, vaapi_device: str = '/dev/dri/renderD128', vaapi_qp: int = 23, qsv_quality: int = 23, nvenc_cq: int = 23, amf_quality: int = 23, hw: str = 'auto', audio_lang: str | None = None, audio_track: int | None = None, subtitle_lang: str | None = None, subtitle_track: int | None = None, prefer_forced_subs: bool = True, no_subtitles: bool = False, preserve_metadata: bool = True, preserve_chapters: bool = True, preserve_attachments: bool = True, integrity_check: bool = True, stable_wait: int = 3, deep_check: bool = False, disk_min_free_mb: int = 1024, disk_min_free_tmp_mb: int = 512, max_output_mb: int = 0, max_output_ratio: float = 0.0, progress: bool = True, bar_width: int = 26, ui_refresh_ms: int = 120, stats_period: float = 0.2, pipeline: bool = True, encode_workers: int = 0, integrity_workers: int = 0, notify: bool = True, notify_on_success: bool = True, notify_on_failure: bool = True, lang: str | None = None, json_progress: bool = False, retry_attempts: int = 1, retry_delay_sec: float = 2.0, retry_fallback_cpu: bool = True)[source]

Bases: object

All configuration options for mkv2cast.

suffix: str = '.cast'

container: str = 'mkv'

recursive: bool = True

ignore_patterns: List[str]

ignore_paths: List[str]

include_patterns: List[str]

include_paths: List[str]

debug: bool = False

dryrun: bool = False

skip_when_ok: bool = True

force_h264: bool = False

allow_hevc: bool = False

force_aac: bool = False

keep_surround: bool = False

add_silence_if_no_audio: bool = True

abr: str = '192k'

crf: int = 20

preset: str = 'slow'

profile: str | None = None

vaapi_device: str = '/dev/dri/renderD128'

vaapi_qp: int = 23

qsv_quality: int = 23

nvenc_cq: int = 23

amf_quality: int = 23

hw: str = 'auto'

audio_lang: str | None = None

audio_track: int | None = None

subtitle_lang: str | None = None

subtitle_track: int | None = None

prefer_forced_subs: bool = True

no_subtitles: bool = False

preserve_metadata: bool = True

preserve_chapters: bool = True

preserve_attachments: bool = True

integrity_check: bool = True

stable_wait: int = 3

deep_check: bool = False

disk_min_free_mb: int = 1024

disk_min_free_tmp_mb: int = 512

max_output_mb: int = 0

max_output_ratio: float = 0.0

progress: bool = True

bar_width: int = 26

ui_refresh_ms: int = 120

stats_period: float = 0.2

pipeline: bool = True

encode_workers: int = 0

integrity_workers: int = 0

notify: bool = True

notify_on_success: bool = True

notify_on_failure: bool = True

lang: str | None = None

json_progress: bool = False

retry_attempts: int = 1

retry_delay_sec: float = 2.0

retry_fallback_cpu: bool = True

apply_script_mode() → None[source]

Automatically disable UI features when running in script mode.

Call this method when using mkv2cast as a library to ensure no unwanted output is generated.

Disables: - progress: No progress bars - notify: No desktop notifications - pipeline: No Rich UI (use simple sequential mode)

apply_profile(name: str, only_if_default: bool = False) → None[source]

Apply a preset profile to common encoding settings.

Parameters:

name – Profile name (“fast”, “balanced”, “quality”).
only_if_default – If True, only apply fields still at default values.

classmethod for_library(**kwargs) → Config[source]

Create a Config instance optimized for library usage.

Automatically disables UI features (progress bars, notifications, Rich UI) that are not suitable for programmatic use.

Parameters:: **kwargs – Configuration options to override defaults.
Returns:: Config instance with script mode settings applied.

Example

>>> config = Config.for_library(hw="vaapi", crf=20)
>>> success, output, msg = convert_file(path, cfg=config)

HistoryDB Class

class mkv2cast.history.HistoryDB(state_dir: Path)[source]

Bases: object

History storage with SQLite primary and JSONL text fallback.

record_start(input_path: Path, backend: str, input_size: int = 0) → int[source]: Record conversion start, return entry ID.

record_finish(entry_id: int, output_path: Path | None, status: str, encode_time: float = 0, integrity_time: float = 0, output_size: int = 0, duration_ms: int = 0, error_msg: str | None = None) → None[source]: Update entry with completion info.

record_skip(input_path: Path, reason: str, backend: str) → None[source]: Record a skipped file.

get_recent(limit: int = 20) → List[dict][source]: Get recent conversions.

get_stats() → dict[source]: Get conversion statistics.

clean_old(days: int) → int[source]: Remove entries older than N days. Returns count removed.