Video Splitting — PySceneDetect 0.6.5-dev1 documentation

# 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):

> - FFmpeg: [ https://ffmpeg.org/download.html ]

> - mkvmerge: [ https://mkvtoolnix.download/downloads.html ]

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:

    - index (int) –

    - start (FrameTimecode) –

    - end (FrameTimecode) –

  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 = 'ffmpeg'

  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`]

PySceneDetect API Tests

These tests demonstrate common workflow patterns used when integrating the PySceneDetect API.

tests.test_api.test_api_detect(test_video_file)

  Demonstrate usage of the detect() function to process a complete video.

  Parameters:

    test_video_file (str) –

tests.test_api.test_api_detect_start_end_time(test_video_file)

  Demonstrate usage of the detect() function to process a subset of a video.

  Parameters:

    test_video_file (str) –

tests.test_api.test_api_detect_stats(test_video_file)

  Demonstrate usage of the detect() function to generate a statsfile.

  Parameters:

    test_video_file (str) –

tests.test_api.test_api_device_callback(test_video_file)

  Demonstrate how to use a webcam/device/pipe and a callback function. Instead of calling open_video(), an existing cv2.VideoCapture can be used by wrapping it with a VideoCaptureAdapter.

  Parameters:

    test_video_file (str) –

tests.test_api.test_api_scene_manager(test_video_file)

  Demonstrate how to use a SceneManager to implement a function similar to detect().

  Parameters:

    test_video_file (str) –

tests.test_api.test_api_scene_manager_callback(test_video_file)

  Demonstrate how to use a callback with the SceneManager detect_scenes method.

  Parameters:

    test_video_file (str) –

tests.test_api.test_api_scene_manager_start_end_time(test_video_file)

  Demonstrate how to use a SceneManager to process a subset of the input video.

  Parameters:

    test_video_file (str) –

tests.test_api.test_api_stats_manager(test_video_file)

  Demonstrate using a StatsManager to save per-frame statistics to disk.

  Parameters:

    test_video_file (str) –

tests.test_api.test_api_timecode_types()

  Demonstrate all different types of timecodes that can be used.