mkv2cast.config

Configuration management for mkv2cast.

Handles: - XDG Base Directory compliance - TOML/INI configuration file loading - Config dataclass with all options - Configuration merging (system -> user -> CLI) - Automatic script mode detection

Functions

apply_config_to_args(file_config, cfg[, ...])	Apply file config values to Config instance.
get_app_dirs()	Return all application directories, creating them if needed.
get_xdg_cache_home()	Get XDG cache home directory.
get_xdg_config_home()	Get XDG config home directory.
get_xdg_state_home()	Get XDG state home directory.
is_script_mode()	Detect if running as a library (not CLI).
load_config_file(config_dir)	Load config with priority: 1.
save_default_config(config_dir)	Create default config file (TOML if available, else INI).

Classes

Config(suffix, container, recursive, ...)

All configuration options for mkv2cast.

mkv2cast.config.is_script_mode() → bool

Detect if running as a library (not CLI).

Returns True if: - stdout is not a TTY (piped or redirected) - NO_COLOR environment variable is set - MKV2CAST_SCRIPT_MODE environment variable is set - Being imported as a library (not running as __main__)

Returns:

True if running in script mode, False otherwise.

mkv2cast.config.get_xdg_config_home() → Path

Get XDG config home directory.

mkv2cast.config.get_xdg_state_home() → Path

Get XDG state home directory.

mkv2cast.config.get_xdg_cache_home() → Path

Get XDG cache home directory.

mkv2cast.config.get_app_dirs() → Dict[str, Path]

Return all application directories, creating them if needed.

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)

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

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

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

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)

mkv2cast.config.load_config_file(config_dir: Path) → dict

Load config with priority: 1. User config: ~/.config/mkv2cast/config.toml (highest priority) 2. System config: /etc/mkv2cast/config.toml (lowest priority, optional)

User config values override system config values.

mkv2cast.config.save_default_config(config_dir: Path) → Path

Create default config file (TOML if available, else INI). Returns path.

mkv2cast.config.apply_config_to_args(file_config: dict, cfg: Config, cli_explicit: set | None = None) → None

Apply file config values to Config instance.

Only applies values from file config if they weren’t explicitly set on CLI. This ensures CLI arguments have priority over config file values.

Parameters:

• file_config – Dict from config file (TOML or INI)

• cfg – Config instance with CLI-parsed values

• cli_explicit – Optional set of attribute names explicitly set on CLI