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.
`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.
`run_command_line`	Run a command line string.
`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.

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, number_of_frames: int | None = None, start_frame: int | None = None, skip_frames: bool | None = None) → str[source]¶

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

Parameters:

video_file (str) – The path to the video file.
number_of_frames (int, optional) – The number of frames to process. Defaults to None.
start_frame (int, optional) – The starting frame position. Defaults to None.
skip_frames (int, optional) – The number of frames to skip. Defaults to None.

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.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.run_command_line(string) → None[source]¶

Run a command line string.

Parameters:: string (str) – The command line string to be executed

nicetoolbox.utils.video.sequential2frame_number(number: int, start_frame: int, skip_frames: 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.
skip_frames (int) – The number of frames to skip between each sequential number.

Returns:

The corresponding frame number.

Return type:

int

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

Split a video into individual frames.

Parameters:

video_file (str) – Path to the input video file.
output_base (str) – Base directory where the frames will be saved.
start_frame (int, optional) – The starting frame index. Defaults to None.
number_of_frames (int, optional) – The number of frames to extract. Defaults to None.
skip_frames (int, optional) – The number of frames to skip between each extracted frame. Defaults to None.
keep_indices (bool, optional) – Whether to keep the original frame indices or convert them to sequential numbers. Defaults to True.

Returns:

A tuple containing two lists - the list of: extracted frame filenames and the list of corresponding frame indices.

Return type:

Tuple[List[str], List[int]]

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.