nicetoolbox.utils.video¶

Helper functions for video processing, conversion, splitting, …

Functions

`cut_length`	Cuts a specified length from a video file and saves it as a new file.
`equal_splits_by_frames`	Splits a video into equal segments based on the number of frames.
`frames_to_video`	Convert a folder of frames to a video using ffmpeg.
`get_ffmpeg_input_string`	Constructs the input string for running ffmpeg in the command line.
`get_fps`	Get the frame rate of a video file.
`get_number_of_frames`	Get the number of frames in a video file.
`json_to_video_info`	Parse ffprobe video json to compact video info.
`probe_video`	Parse video information using ffprobe.
`read_segments_list_from_file`	Reads a CSV file containing a list of segments and returns a list of tuples.
`remove_last_segment_from_file`	Removes the last segment from the given segments list file.
`sequential2frame_number`	Converts a sequential number to a frame number based on the given start frame and skip frames.
`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.cut_length(video_file: str, output_base: str, start_frame: int | None = None, number_of_frames: int | None = None) → str[source]¶

Cuts a specified length from a video file and saves it as a new file.

Parameters:

video_file (str) – The path to the input video file.
output_base (str) – The base name for the output file. The file extension will be added automatically.
start_frame (int, optional) – The starting frame index for the cut. Defaults to None.
number_of_frames (int, optional) – The number of frames to include in the cut. Defaults to None.

Returns:

The path to the output file.

Return type:

str

nicetoolbox.utils.video.equal_splits_by_frames(video_file: str, output_base: str, frames_per_split: int, keep_last_split: bool = True, start_frame: int | None = None, number_of_frames: int | None = None) → list[source]¶

Splits a video into equal segments based on the number of frames.

Parameters:

video_file (str) – The path to the input video file.
output_base (str) – The base path for the output segments.
frames_per_split (int) – The number of frames per split segment.
keep_last_split (bool, optional) – Whether to keep the last split segment if it is shorter than the others. Defaults to True.
start_frame (int, optional) – The starting frame index. Defaults to None.
number_of_frames (int, optional) – The total number of frames to consider. Defaults to None.

Returns:

A list of paths to the created segments.

Return type:

List[str]

Raises:

AssertionError – If the total number of frames is less than the frames per split.

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

Convert a folder of frames to a video using ffmpeg.

Parameters:

input_folder (str) – Path to the folder containing the frames.
out_filename (str) – Path to the output video file.
fps (float, optional) – Frames per second of the output video. Defaults to 30.0.

Returns:

Return code of the ffmpeg command.

Return type:

int

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

Constructs the input string for running ffmpeg in the command line.

Parameters:: video_file (str) – The path to the video file.
Returns:: The constructed ffmpeg input string.
Return type:: str

nicetoolbox.utils.video.get_fps(video_file) → int[source]¶

Get the frame rate of a video file.

Parameters:: video_file (str) – The path to the video file.
Returns:: The frame rate of the video file.
Return type:: int

nicetoolbox.utils.video.get_number_of_frames(video_file: str) → int[source]¶

Get the number of frames in a video file.

Parameters:: video_file (str) – The path to the video file.
Returns:: The number of frames in the video file.
Return type:: int

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.read_segments_list_from_file(segments_list_file: str) → list[source]¶

Reads a CSV file containing a list of segments and returns a list of tuples.

Parameters:

segments_list_file (str) – The path to the CSV file containing the list of segments. The CSV file should have columns named ‘file’, ‘start’, and ‘end’.

Returns:

A list of tuples, where each tuple represents a: segment. Each tuple contains the video file name, the start time of the segment, and the end time of the segment.

Return type:

List[Tuple[str, float, float]]

nicetoolbox.utils.video.remove_last_segment_from_file(segments_list_file: str) → None[source]¶

Removes the last segment from the given segments list file.

This function reads the segments list file into a pandas DataFrame, drops the last row, and then writes the updated DataFrame back to the CSV file.

Parameters:: segments_list_file (str) – The path to the CSV file containing the list of segments.
Returns:: None

nicetoolbox.utils.video.sequential2frame_number(number: int, start_frame: int) → int[source]¶

Converts a sequential number to a frame number based on the given start frame and skip frames.

Parameters:

number (int) – The sequential number.
start_frame (int) – The starting frame number.

Returns:

The corresponding frame number.

Return type:

int

nicetoolbox.utils.video.split_into_frames(video_file: str, output_base: str, n_frames_expected: int | None, start_frame: int = 0, 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
start_frame (int, optional) – The starting frame index. Defaults to 0.
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.

Warning

The skip_frames option is not properly working yet. Its output is not fully: understood yet.