Video Splitting

scenedetect.video_splitter Module

The scenedetect.video_splitter module contains functions to split existing videos into clips using ffmpeg or mkvmerge.

These programs can be obtained from following URLs (note that mkvmerge is a part mkvtoolnix):

If you are a Linux user, you can likely obtain the above programs from your package manager.

Once installed, ensure the program can be accessed system-wide by calling the mkvmerge or ffmpeg command from a terminal/command prompt. PySceneDetect will automatically use whichever program is available on the computer, depending on the specified command-line options.

class scenedetect.video_splitter.SceneMetadata(index, start, end)

Information about the scene being extracted.

Parameters:
end: FrameTimecode

Last frame.

index: int

0-based index of this scene.

start: FrameTimecode

First frame.

class scenedetect.video_splitter.VideoMetadata(name, path, total_scenes)

Information about the video being split.

Parameters:

  • name (str) –

  • path (Path) –

  • total_scenes (int) –

name: str

Expected name of the video. May differ from path.

path: Path

Path to the input file.

total_scenes: int

Total number of scenes that will be written.

scenedetect.video_splitter.default_formatter(template)

Formats filenames using a template string which allows the following variables:

$VIDEO_NAME, $SCENE_NUMBER, $START_TIME, $END_TIME, $START_FRAME, $END_FRAME

Parameters:

template (str) –

Return type:

Callable[[VideoMetadata, SceneMetadata], AnyStr]

scenedetect.video_splitter.is_ffmpeg_available()

Is ffmpeg Available: Gracefully checks if ffmpeg command is available.

Returns:

True if ffmpeg can be invoked, False otherwise.

Return type:

bool

scenedetect.video_splitter.is_mkvmerge_available()

Is mkvmerge Available: Gracefully checks if mkvmerge command is available.

Returns:

True if mkvmerge can be invoked, False otherwise.

Return type:

bool

scenedetect.video_splitter.split_video_ffmpeg(input_video_path, scene_list, output_dir=None, output_file_template='$VIDEO_NAME-Scene-$SCENE_NUMBER.mp4', video_name=None, arg_override='-map 0:v:0 -map 0:a? -map 0:s? -c:v libx264 -preset veryfast -crf 22 -c:a aac', show_progress=False, show_output=False, suppress_output=None, hide_progress=None, formatter=None)

Calls the ffmpeg command on the input video, generating a new video for each scene based on the start/end timecodes.

Parameters:

  • input_video_path (str) – Path to the video to be split.

  • scene_list (List[ty.Tuple[FrameTimecode, FrameTimecode]]) – List of scenes (pairs of FrameTimecodes) denoting the start/end frames of each scene.

  • output_dir (Path | None) – Directory to output videos. If not set, output will be in working directory.

  • output_file_template (str) – Template to use for generating output filenames. The following variables will be replaced in the template for each scene: $VIDEO_NAME, $SCENE_NUMBER, $START_TIME, $END_TIME, $START_FRAME, $END_FRAME

  • video_name (str) – Name of the video to be substituted in output_file_template. If not passed will be calculated from input_video_path automatically.

  • arg_override (str) – Allows overriding the arguments passed to ffmpeg for encoding.

  • show_progress (bool) – If True, will show progress bar provided by tqdm (if installed).

  • show_output (bool) – If True, will show output from ffmpeg for first split.

  • suppress_output – [DEPRECATED] DO NOT USE. For backwards compatibility only.

  • hide_progress – [DEPRECATED] DO NOT USE. For backwards compatibility only.

  • formatter (Callable[[VideoMetadata, SceneMetadata], AnyStr] | None) – Custom formatter callback. Overrides output_file_template.

Returns:

Return code of invoking ffmpeg (0 on success). If scene_list is empty, will still return 0, but no commands will be invoked.

Return type:

int

scenedetect.video_splitter.split_video_mkvmerge(input_video_path, scene_list, output_dir=None, output_file_template='$VIDEO_NAME.mkv', video_name=None, show_output=False, suppress_output=None)

Calls the mkvmerge command on the input video, splitting it at the passed timecodes, where each scene is written in sequence from 001.

Parameters:

  • input_video_path (str) – Path to the video to be split.

  • scene_list (Iterable[Tuple[FrameTimecode, FrameTimecode]]) – List of scenes as pairs of FrameTimecodes denoting the start/end times.

  • output_dir (Path | None) – Directory to output videos. If not set, output will be in working directory.

  • output_file_template (str) – Template to use for generating output files. Note that mkvmerge always adds the suffix “-$SCENE_NUMBER” to the output paths. Only the $VIDEO_NAME variable is supported by this function.

  • video_name (str) – Name of the video to be substituted in output_file_template for $VIDEO_NAME. If not specified, will be obtained from the filename.

  • show_output (bool) – If False, adds the –quiet flag when invoking mkvmerge.

  • suppress_output – [DEPRECATED] DO NOT USE. For backwards compatibility only.

Returns:

Return code of invoking mkvmerge (0 on success). If scene_list is empty, will still return 0, but no commands will be invoked.

Return type:

int

scenedetect.video_splitter.DEFAULT_FFMPEG_ARGS = '-map 0:v:0 -map 0:a? -map 0:s? -c:v libx264 -preset veryfast -crf 22 -c:a aac'

Default arguments passed to ffmpeg when invoking the split_video_ffmpeg function.

scenedetect.video_splitter.FFMPEG_PATH: str | None = '/opt/hostedtoolcache/Python/3.12.7/x64/lib/python3.12/site-packages/imageio_ffmpeg/binaries/ffmpeg-linux64-v4.2.2'

Relative path to the ffmpeg binary on this system, if any (will be None if not available).

scenedetect.video_splitter.TimecodePair

Named type for pairs of timecodes, which typically represents the start/end of a scene.

alias of Tuple[FrameTimecode, FrameTimecode]