nicetoolbox.utils.video¶

Helper functions for video processing, conversion, splitting, …

Functions

`frames_to_video`	Convert a folder of frames to a video using ffmpeg.
`get_ffmpeg_base_args`	Constructs the base argument list for running ffmpeg.
`json_to_video_info`	Parse ffprobe video json to compact video info.
`probe_video`	Parse video information using ffprobe.
`render_subtitled_track_video`	Render a single subtitled video for one transcription track.
`split_into_frames`	Split a video into individual frames using ffmpeg.

Classes

VideoInfo

class nicetoolbox.utils.video.VideoInfo(video_path: pathlib.Path, codec: str, fps: float | None, frames: int | None, width: int, height: int, duration_in_sec: int | None)[source]¶

nicetoolbox.utils.video.frames_to_video(input_folder: str | None, out_filename: str, fps: float = 30.0, start_frame: int = 0, audio_path: str | None = None, srt_path: str | None = None, frame_limit: int | None = None) → int[source]¶

Convert a folder of frames to a video using ffmpeg.

Parameters:

input_folder (Optional[str]) – Path to the folder containing the frames. If None, a black fallback video is generated.
out_filename (str) – Path to the output video file.
fps (float, optional) – Frames per second of the output video. Defaults to 30.0.
start_frame (int, optional) – The starting frame number. Defaults to 0.
audio_path (Optional[str], optional) – Path to an audio file to include. Defaults to None.
srt_path (Optional[str], optional) – Path to a subtitle (SRT) file to include. Defaults to None.
frame_limit (int, optional) – Limit on how many frames to compose. Defaults to None.

Returns:

Return code of the ffmpeg command.

Return type:

int

nicetoolbox.utils.video.get_ffmpeg_base_args(video_file: str) → list[source]¶

Constructs the base argument list for running ffmpeg.

Parameters:: video_file (str) – The path to the video file.
Returns:: The ffmpeg base arguments as a list of strings.
Return type:: list

nicetoolbox.utils.video.json_to_video_info(data: dict) → VideoInfo[source]¶

Parse ffprobe video json to compact video info.

Parameters:: data (dict) – Dictionary holds video information.
Returns:: Video meta information.
Return type:: VideoInfo

nicetoolbox.utils.video.probe_video(video_path: str) → dict[source]¶

Parse video information using ffprobe. The collected information: codec, fps, number_of_frames, width, height, duration

Parameters:: video_path (str) – Path to the video file.
Returns:: Return the dictionary holds the video information.
Return type:: dict

nicetoolbox.utils.video.render_subtitled_track_video(srt_path: str, audio_path: str, output_path: str, fps: float, default_start_frame: int = 0, video_recipe=None, camera: str | None = None, fallback_camera: str | None = None) → bool[source]¶

Render a single subtitled video for one transcription track.

Encapsulates the per-track work shared by transcription detectors: it skips missing or empty SRT files, resolves the frame folder from the video recipe for the track’s own camera (or renders a black background when unavailable), and bakes the subtitles into the video via frames_to_video(). Callers only need to provide the per-track paths inside their own track loop.

Parameters:

srt_path (str) – Path to the SRT subtitle file for this track.
audio_path (str) – Path to the track’s audio source.
out_filename (str) – Path to the output .mp4 (its directory is created if missing).
fps (float) – Default frames per second (overridden by the recipe range when available).
default_start_frame (int, optional) – Start frame used when no video recipe is given.
video_recipe (optional) – Video input recipe exposing root_path, camera_names, range_start and range_end. When None a black background video is produced.
camera (Optional[str]) – Camera to overlay subtitles on. None or a name not present in the recipe falls back to fallback_camera; if that is also unavailable a black background video is produced.
fallback_camera (Optional[str]) – Camera to use when camera is unavailable.

Returns:

True if a video was rendered, False if the track was skipped.

Return type:

bool

nicetoolbox.utils.video.split_into_frames(video_file: str, output_base: str, n_frames_expected: int | None, keep_indices: bool = True) → None[source]¶

Split a video into individual frames using ffmpeg.

Parameters:

video_file (str) – Path to the input video file.
output_base (str) – Base directory where the frames will be saved.
n_frames_expected (Optional[int]) – Expected number of frames
keep_indices (bool, optional) – Whether to keep the original frame indices or convert them to sequential numbers. Defaults to True.

Raises:

AssertionError – If splitting the video into frames fails.

Note

This function uses ffmpeg to split the video into frames. Make sure ffmpeg: is installed and accessible in the system’s PATH.