Ouptut

scenedetect.output.save_images(scene_list, video, num_images=3, frame_margin=1, image_extension='jpg', encoder_param=95, image_name_template='$VIDEO_NAME-Scene-$SCENE_NUMBER-$IMAGE_NUMBER', output_dir=None, show_progress=False, scale=None, height=None, width=None, interpolation=Interpolation.CUBIC, threading=True)

Save a set number of images from each scene, given a list of scenes and the associated video/frame source.

Parameters:

  • scene_list (List[Tuple[FrameTimecode, FrameTimecode]]) – A list of scenes (pairs of FrameTimecode objects) returned from calling a SceneManager’s detect_scenes() method.

  • video (VideoStream) – A VideoStream object corresponding to the scene list. Note that the video will be closed/re-opened and seeked through.

  • num_images (int) – Number of images to generate for each scene. Minimum is 1.

  • frame_margin (int) – Number of frames to pad each scene around the beginning and end (e.g. moves the first/last image into the scene by N frames). Can set to 0, but will result in some video files failing to extract the very last frame.

  • image_extension (str) – Type of image to save (must be one of ‘jpg’, ‘png’, or ‘webp’).

  • encoder_param (int) – Quality/compression efficiency, based on type of image: ‘jpg’ / ‘webp’: Quality 0-100, higher is better quality. 100 is lossless for webp. ‘png’: Compression from 1-9, where 9 achieves best filesize but is slower to encode.

  • image_name_template (str) – Template to use for naming image files. Can use the template variables $VIDEO_NAME, $SCENE_NUMBER, $IMAGE_NUMBER, $TIMECODE, $FRAME_NUMBER, $TIMESTAMP_MS. Should not include an extension.

  • output_dir (str | None) – Directory to output the images into. If not set, the output is created in the working directory.

  • show_progress (bool | None) – If True, shows a progress bar if tqdm is installed.

  • scale (float | None) – Optional factor by which to rescale saved images. A scaling factor of 1 would not result in rescaling. A value < 1 results in a smaller saved image, while a value > 1 results in an image larger than the original. This value is ignored if either the height or width values are specified.

  • height (int | None) – Optional value for the height of the saved images. Specifying both the height and width will resize images to an exact size, regardless of aspect ratio. Specifying only height will rescale the image to that number of pixels in height while preserving the aspect ratio.

  • width (int | None) – Optional value for the width of the saved images. Specifying both the width and height will resize images to an exact size, regardless of aspect ratio. Specifying only width will rescale the image to that number of pixels wide while preserving the aspect ratio.

  • interpolation (Interpolation) – Type of interpolation to use when resizing images.

  • threading (bool) – Offload image encoding and disk IO to background threads to improve performance.

Returns:

[image_paths] }, where scene_num is the number of the scene in scene_list (starting from 1), and image_paths is a list of the paths to the newly saved/created images.

Return type:

Dictionary of the format { scene_num

Raises:

  • ValueError – Raised if any arguments are invalid or out of range (e.g.

  • if num_images is negative). –

scenedetect.output.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.output.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)

Split input_video_path using ffmpeg based on the scenes in scene_list.

Parameters:

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

  • scene_list (Iterable[Tuple[FrameTimecode, FrameTimecode]]) – List of scenes (pairs of FrameTimecodes) denoting the start/end 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 | None) – 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.output.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.output.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)

Split input_video_path using mkvmerge based on the scenes in scene_list.

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 (str | Path | None) – Directory to output videos. If not set, output will be in working directory.

  • output_file_template (str | Path | None) – 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 | None) – 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.output.write_scene_list_html(output_html_filename, scene_list, cut_list=None, css=None, css_class='mytable', image_filenames=None, image_width=None, image_height=None)

Writes the given list of scenes to an output file handle in html format.

Parameters:

  • output_html_filename (str) – filename of output html file

  • scene_list (List[Tuple[FrameTimecode, FrameTimecode]]) – List of pairs of FrameTimecodes denoting each scene’s start/end FrameTimecode.

  • cut_list (List[FrameTimecode] | None) – Optional list of FrameTimecode objects denoting the cut list (i.e. the frames in the video that need to be split to generate individual scenes). If not passed, the start times of each scene (besides the 0th scene) is used instead.

  • css (str) – String containing all the css information for the resulting html page.

  • css_class (str) – String containing the named css class

  • image_filenames (Dict[int, List[str]] | None) – dict where key i contains a list with n elements (filenames of the n saved images from that scene)

  • image_width (int | None) – Optional desired width of images in table in pixels

  • image_height (int | None) – Optional desired height of images in table in pixels

scenedetect.output.write_scene_list(output_csv_file, scene_list, include_cut_list=True, cut_list=None, col_separator=',', row_separator='\n')

Writes the given list of scenes to an output file handle in CSV format.

Parameters:

  • output_csv_file (TextIO) – Handle to open file in write mode.

  • scene_list (List[Tuple[FrameTimecode, FrameTimecode]]) – List of pairs of FrameTimecodes denoting each scene’s start/end FrameTimecode.

  • include_cut_list (bool) – Bool indicating if the first row should include the timecodes where each scene starts. Should be set to False if RFC 4180 compliant CSV output is required.

  • cut_list (List[FrameTimecode] | None) – Optional list of FrameTimecode objects denoting the cut list (i.e. the frames in the video that need to be split to generate individual scenes). If not specified, the cut list is generated using the start times of each scene following the first one.

  • col_separator (str) – Delimiter to use between values. Must be single character.

  • row_separator (str) – Line terminator to use between rows.

Raises:

TypeError – “delimiter” must be a 1-character string

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

Information about the scene being extracted.

Parameters:
class scenedetect.output.VideoMetadata(name, path, total_scenes)

Information about the video being split.

Parameters:

  • name (str) –

  • path (Path) –

  • total_scenes (int) –

scenedetect.output.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]