Settings

Encoding settings: the immutable description of what to do.

remote_compression.settings.DEFAULT_EXTENSIONS = frozenset({'.3gp', '.avi', '.flv', '.m2ts', '.m4v', '.mkv', '.mov', '.mp4', '.mpeg', '.mpg', '.mts', '.ts', '.webm', '.wmv'})

Extensions scanned by default (always compared lowercase).

remote_compression.settings.ENCODER_TO_CODEC = {'libaom-av1': 'av1', 'librav1e': 'av1', 'libsvtav1': 'av1', 'libvpx': 'vp8', 'libvpx-vp9': 'vp9', 'libx264': 'h264', 'libx265': 'hevc', 'mpeg4': 'mpeg4'}

Encoder name (ffmpeg -c:v value) -> codec name (as reported by ffprobe).

remote_compression.settings.INTERLACED_FIELD_ORDERS = frozenset({'bb', 'bt', 'tb', 'tt'})

ffprobe field_order values meaning the source is interlaced.

remote_compression.settings.MKV_COPY_SUBS = frozenset({'ass', 'dvb_subtitle', 'dvd_subtitle', 'hdmv_pgs_subtitle', 'srt', 'ssa', 'subrip', 'webvtt'})

Subtitle codecs that matroska accepts as-is (-c:s copy).

class remote_compression.settings.Settings(codec: str = 'libx265', codec_name: str | None = None, crf: int | None = None, ffmpeg_preset: str | None = None, height: int | None = 720, container: str = 'mkv', map_streams: bool = True, replace: bool = False, hostname: str = 'remote_host', remote_ffmpeg: str | None = None, remote_workdir: str | None = None, remote_workdir_sftp: str | None = None, extensions: frozenset = frozenset({'.3gp', '.avi', '.flv', '.m2ts', '.m4v', '.mkv', '.mov', '.mp4', '.mpeg', '.mpg', '.mts', '.ts', '.webm', '.wmv'}), auto_local: bool = True, auto_purge_days: float | None = 7.0)

Resolved encoding settings (immutable).

codec

ffmpeg encoder used for transcoding (free choice: libx264, libsvtav1, hevc_nvenc…).

Type:

str

codec_name

ffprobe codec name considered compliant (no transcode needed). Derived from codec when None; an explicit value is required when the derivation fails.

Type:

str, optional

crf

Constant rate factor. None keeps the encoder default.

Type:

int, optional

ffmpeg_preset

ffmpeg -preset (medium, slow…). None keeps the encoder default.

Type:

str, optional

height

Maximal definition, understood as the short side of the display frame (rotation-aware): a 1920x1080 landscape and a 1080x1920 portrait are both “1080p” and both get downscaled to 720p when this is 720. None disables resizing (the CLI/TOML sentinel for None is 0).

Type:

int, optional

container

Output container (extension without dot). Everything is muxed to mkv by default: it accepts about any codec/subtitle combination.

Type:

str

map_streams

Explicitly map video/audio/subtitle streams (-map 0:V -map 0:a? -map 0:s?). When False, keep ffmpeg default stream selection.

Type:

bool

replace

When True, the original file is deleted after a successful compression. When False, it is kept next to the output, renamed ori_<name>.

Type:

bool

hostname

SSH alias of the compression server (resolved through ~/.ssh/config), or local to compress on this machine.

Type:

str

remote_ffmpeg

Explicit path of the ffmpeg binary on the remote server, for hosts whose non-interactive PATH misses it (typical on Synology). Must be a space-free ASCII path; forward slashes work on Windows servers too.

Type:

str, optional

remote_workdir

Workspace directory on the server as seen by the shell running ffmpeg (default: .rcomp, relative to the login home). Space-free ASCII.

Type:

str, optional

remote_workdir_sftp

The same workspace as seen by the SFTP channel, when the two views differ. Synology chroots SFTP into a virtual share tree: its /home is the login home, so remote_workdir_sftp = "/home/.rcomp" (with the default remote_workdir) points both channels at the same physical directory. Defaults to remote_workdir.

Type:

str, optional

extensions

File extensions (lowercase, with dot) considered as videos when scanning.

Type:

frozenset of str

auto_local

When True, a hostname that resolves to this very machine switches to local mode automatically.

Type:

bool

auto_purge_days

Age threshold for the opportunistic purge of the remote workspace at connection time. None disables it (the TOML sentinel for None is 0).

Type:

float, optional

property effective_codec_name

ffprobe codec name considered compliant.

Raises:

ValueError – If codec_name is not set and cannot be derived from codec.

Type:

str

remote_compression.settings.TEXT_CONVERT_SUBS = frozenset({'mov_text', 'text'})

Text subtitle codecs that must be converted for matroska (-c:s srt).

remote_compression.settings.derive_codec_name(encoder)

Derive the ffprobe codec name matching an encoder name.

Parameters:

encoder (str) – ffmpeg encoder (-c:v value), e.g. libx265, hevc_nvenc.

Returns:

Codec name as reported by ffprobe (e.g. hevc), or None if it cannot be derived. Callers must then require an explicit codec_name.

Return type:

str or None

Examples

>>> derive_codec_name('libx265')
'hevc'
>>> derive_codec_name('hevc_nvenc')
'hevc'
>>> derive_codec_name('libsvtav1')
'av1'
>>> derive_codec_name('mystery_encoder') is None
True