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.

scenedetect.video_splitter.DEFAULT_FFMPEG_ARGS = '-map 0 -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 = None

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]

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_file_template='$VIDEO_NAME-Scene-$SCENE_NUMBER.mp4', video_name=None, arg_override='-map 0 -c:v libx264 -preset veryfast -crf 22 -c:a aac', show_progress=False, show_output=False, suppress_output=None, hide_progress=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[Tuple[FrameTimecode, FrameTimecode]]) – List of scenes (pairs of FrameTimecodes) denoting the start/end frames of each scene.

  • output_file_template (str) – Template to use for generating the output filenames. Can use $VIDEO_NAME and $SCENE_NUMBER in this format, for example: $VIDEO_NAME - Scene $SCENE_NUMBER.mp4

  • 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.

Returns:

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

scenedetect.video_splitter.split_video_mkvmerge(input_video_path, scene_list, 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_file_template (str) – Template to use for output files. Mkvmerge always adds the suffix “-$SCENE_NUMBER”. Can use $VIDEO_NAME as a template parameter (e.g. “$VIDEO_NAME.mkv”).

  • 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.