media

Media-related utility functions.

class deltona.media.CDDBQueryResult(artist: str, album: str, year: int, genre: str, tracks: tuple[str, ...])

Bases: NamedTuple

CDDB query result.

album : str

Album title.

artist : str

Artist name.

genre : str

Genre string.

tracks : tuple[str, ...]

Track titles.

year : int

Release year.

deltona.media.add_info_json_to_media_file(path: str | PathLike[str], info_json: str | PathLike[str] | None = None, *, debug: bool = False) → None

Add yt-dlp info.json file to media file at path.

On successful completion, the info.json file will be deleted.

This function remains until yt-dlp embeds info.json in all formats it supports where possible.

This function requires the following:

Parameters:
path : StrPath

Path to FLAC, MP3, MP4, or Opus media file.

info_json : StrPath | None

Path to info.json file. If not passed, path with suffix changed to info.json is used.

debug : bool

If True, show ffmpeg/mkvpropedit output.

deltona.media.archive_dashcam_footage(front_dir: StrPath, rear_dir: StrPath | None, output_dir: StrPath, *, chapters: bool = True, clip_length: int = 3, container: str = 'matroska', crf: int | None = 28, extension: str = 'mkv', hwaccel: str | None = 'auto', keep_audio: bool = False, level: int | str | None = 'auto', group_fn: Callable[[Sequence[tuple[Path, Path]], int, re.Pattern[str] | str, str], list[list[tuple[Path, Path]]]] = <function group_pairs>, max_offset: int = 1, no_delete: bool = False, overwrite: bool = False, match_re: re.Pattern[str] | str = '^(\\d+)_.*', pair_fn: Callable[[StrPath, StrPath, re.Pattern[str] | str, str, int], list[tuple[Path, Path]]] | None = <function pair_redtiger_dashcam_files>, preset: str | None = 'slow', rear_crop: str | None = '1920:1020:0:0', rear_view_scale_divisor: float | None = 2.5, setpts: str | None = '0.25*PTS', temp_dir: StrPath | None = None, tier: str | None = 'high', time_format: str = '%Y%m%d%H%M%S', video_bitrate: str | None = '0k', video_decoder: str | None = 'hevc_cuvid', video_encoder: str = 'libx265', video_max_bitrate: str | None = '30M') → None

Batch encode dashcam footage, merging rear and front camera footage.

This function’s defaults are intended for use with Red Tiger dashcam output and file structure.

The rear camera view will be placed in the bottom right of the video scaled by dividing the width and height by the rear_view_scale_divisor value specified. It will also be cropped using the rear_crop value unless it is None.

Files are automatically grouped using the regular expression passed with match_re. The RE must contain at least one group, and only the first group will be considered. Make dubious use of non-capturing groups if necessary. The captured group string is expected to be usable with the time format specified with time_format (see strptime documentation at https://docs.python.org/3/library/datetime.html#datetime.datetime.strptime).

Front and rear files are paired by timestamp proximity (within max_offset seconds). Files without a corresponding partner are logged and skipped without deletion.

Original files whose content is successfully converted are sent to the wastebin.

Default parameters are set to use libx265 software encoding with CUVID hardware decoding.

Example:

Parameters:
front_dir : StrPath

Directory containing front footage.

rear_dir : StrPath | None

Directory containing rear footage. If None, single-camera mode is used.

output_dir : StrPath

Will be created if it does not exist, including parents.

chapters : bool

Embed chapter markers in the output file. Each clip pair becomes a chapter named after the front file stem without the trailing letter suffix (e.g. 20260318101701_025194).

clip_length : int

Clip length in minutes.

container : str

Container to use. Must match the extension. Passed to ffmpeg’s -f option.

crf : int | None

Constant rate factor.

extension : str

Output file extension. Defaults to mkv.

hwaccel : str | None

String passed to ffmpeg’s -hwaccel option. If None, do not use hardware acceleration for decoding.

keep_audio : bool

Keep audio in the output video. Defaults to False.

level : int | str | None

Level (HEVC).

group_fn : Callable[[Sequence[tuple[Path, Path]], int, re.Pattern[str] | str, str],

list[list[tuple[Path, Path]]]] Function to group pairs into recording sessions. Defaults to group_pairs().

max_offset : int

Maximum seconds between front and rear timestamps for pairing.

no_delete : bool

Do not delete original files after successful conversion.

overwrite : bool

Overwrite existing files.

match_re : re.Pattern[str] | str

Regular expression used for finding the timestamp in a filename. Must contain at least one group and only the first group is considered.

pair_fn : Callable[[StrPath, StrPath, re.Pattern[str] | str, str, int],

list[tuple[Path, Path]]] | None Function to pair front and rear files. Defaults to pair_redtiger_dashcam_files(). If None, single-camera mode is used.

preset : str | None

Preset (various codecs).

rear_crop : str | None

Crop string for the rear video. See ffmpeg crop filter for more information.

rear_view_scale_divisor : float | None

Scaling divisor for rear view.

setpts : str | None

Change the PTS. See ffmpeg setpts filter for more information. The default speeds the video up by 4x.

temp_dir : StrPath | None

Temporary directory root.

tier : str | None

Tier (HEVC).

time_format : str

Time format string. See strptime() Format Codes for more information.

video_bitrate : str | None

Video bitrate string.

video_decoder : str | None

Video decoder.

video_encoder : str

Video encoder.

video_max_bitrate : str | None

Maximum video bitrate.

Raises:

subprocess.CalledProcessError – If an FFmpeg invocation fails.

async deltona.media.cddb_query(disc_id: str, *, accept_first_match: bool = False, app: str = 'deltona cddb_query', host: str | None = None, timeout: float = 5, username: str | None = None, version: str = '0.0.1') → CDDBQueryResult

Run a query against a CDDB host.

Defaults to the host in the keyring under the gnudb key and the current user name.

It is advised to except typical niquests exceptions when calling this.

Parameters:
disc_id : str

Disc ID string in CDDB query format.

accept_first_match : bool

If True, accept the first match when multiple results are returned.

app : str

App name.

host : str | None

Hostname to query.

timeout : float

HTTP timeout.

username : str | None

Username for keyring and for the hello parameter to the CDDB server.

version : str

Application version.

Returns:

Tuple with artist, album, year, genre, and tracks.

Return type:

CDDBQueryResult

Raises:

ValueError – If the username or host is empty, if the server returns multiple matches and accept_first_match is False, or if the server response code is not '200' or '210' (these are CDDB codes not HTTP status codes).

deltona.media.create_static_text_video(audio_file: str | PathLike[str], text: str, font: str = 'Roboto', font_size: int = 150, output_file: str | PathLike[str] | None = None, *, debug: bool = False, nvenc: bool = False, videotoolbox: bool = False) → None

Create a video with static text overlay from an audio file.

Parameters:
audio_file : StrPath

Path to the audio file.

text : str

Text to overlay on the video.

font : str

Font name to use. Default is 'Roboto'.

font_size : int

Font size in points. Default is 150.

output_file : StrPath | None

Output file path. If None, defaults to <audio_file>-video.mkv.

debug : bool

If True, show ffmpeg/ImageMagick output.

nvenc : bool

If True, use NVENC hardware encoding.

videotoolbox : bool

If True, use VideoToolbox hardware encoding.

Raises:
deltona.media.ffprobe(path: str | PathLike[str]) → ProbeDict

Run ffprobe and decode its JSON output.

Parameters:
path : StrPath

Path to the media file.

Returns:

Parsed JSON output from ffprobe.

Return type:

ProbeDict

deltona.media.get_info_json(path: str | PathLike[str], *, raw: bool = False) → Any

Get info.json content in path.

Parameters:
path : StrPath

Path to FLAC, MP3, MP4, or Opus media file.

raw : bool

If True, do not decode.

Returns:

The JSON data decoded. Currently not typed.

Return type:

Any

Raises:

NotImplementedError – If the file type is not supported.

deltona.media.group_pairs(pairs: collections.abc.Sequence[tuple[Path, Path]], clip_length: int = 3, match_re: re.Pattern[str] | str = '^(\\d+)_.*', time_format: str = '%Y%m%d%H%M%S') → list[list[tuple[Path, Path]]]

Group paired dashcam files into recording sessions by timestamp proximity.

Consecutive pairs whose front file timestamps are within clip_length minutes of each other are placed in the same group. A gap exceeding clip_length starts a new group.

Parameters:
pairs : Sequence[tuple[Path, Path]]

Pairs of (rear_file, front_file) sorted by front file timestamp.

clip_length : int

Maximum gap in minutes between consecutive pairs in a group.

match_re : re.Pattern[str] | str

Regular expression to extract the timestamp from filenames.

time_format : str

Format string for parsing the extracted timestamp.

Returns:

Groups of pairs, each group representing a recording session.

Return type:

list[list[tuple[Path, Path]]]

deltona.media.hlg_to_sdr(input_file: StrPath, crf: int = 20, output_codec: 'libx265' | 'libx264' = 'libx265', output_file: StrPath | None = None, input_args: collections.abc.Sequence[str] | None = None, output_args: collections.abc.Sequence[str] | None = None, *, delete_after: bool = False, fast: bool = False) → None

Convert an HLG HDR video to SDR using tone mapping.

Parameters:
input_file : StrPath

Path to the input HLG video file.

crf : int

Constant rate factor. Default is 20.

output_codec : Literal['libx265', 'libx264']

Output video codec. Default is 'libx265'.

output_file : StrPath | None

Output file path. If None, defaults to <input_file>-sdr.<ext>.

input_args : Sequence[str] | None

Additional input arguments for FFmpeg.

output_args : Sequence[str] | None

Additional output arguments for FFmpeg.

delete_after : bool

If True, send the input file to the wastebin after conversion.

fast : bool

If True, use fewer filters for faster but lower quality conversion.

deltona.media.is_audio_input_format_supported(input_device: str, format: str, rate: int) → bool

Check if an audio format is supported by a device.

Parameters:
input_device : str

Device name (platform-specific).

format : str

Audio format to check, such as 's16le'.

rate : int

Sample rate in Hz.

Returns:

True if the format and rate are supported.

Return type:

bool

deltona.media.pair_redtiger_dashcam_files(front_dir: str | PathLike[str], rear_dir: str | PathLike[str], match_re: Pattern[str] | str = '^(\\d+)_.*', time_format: str = '%Y%m%d%H%M%S', max_offset: int = 1) → list[tuple[Path, Path]]

Pair front and rear dashcam files by timestamp proximity.

For each front file, finds the closest rear file whose timestamp is within max_offset seconds. Files without a match are logged and skipped.

Parameters:
front_dir : StrPath

Directory containing front footage.

rear_dir : StrPath

Directory containing rear footage.

match_re : re.Pattern[str] | str

Regular expression to extract the timestamp from filenames.

time_format : str

Format string for parsing the extracted timestamp.

max_offset : int

Maximum seconds between front and rear timestamps for pairing.

Returns:

Pairs of (rear_file, front_file) sorted by front file timestamp.

Return type:

list[tuple[Path, Path]]

deltona.media.parse_timestamp(name: str, match_re: Pattern[str] | str, time_format: str) → datetime

Extract and parse a timestamp from a filename.

Parameters:
name : str

Filename to extract the timestamp from.

match_re : re.Pattern[str] | str

Regular expression with at least one group capturing the timestamp portion.

time_format : str

Format string for strptime().

Returns:

Parsed datetime object.

Return type:

datetime

deltona.media.supported_audio_input_formats(input_device: str, formats: collections.abc.Sequence[str] = ..., rates: collections.abc.Sequence[int] = ...) → tuple[tuple[str, str], ...]

Get supported input formats and sample rates by invoking ffmpeg.

For possible formats, invoke ffmpeg: ffmpeg -formats | grep PCM | cut '-d ' -f3.

Parameters:
input_device : str

Device name (platform-specific). Examples: 'hw:Audio', 'hw:NVidia'.

formats : Sequence[str]

Formats to check.

rates : Sequence[int]

Rates in Hz to check. The default set is taken from possible frequencies for DTS format.

Returns:

A tuple of (format, rate) tuples.

Return type:

tuple[tuple[str, int], …]

Raises:

OSError – If the device is not found or busy.