Output¶

The scenedetect.output module contains functions which can be used to generate output based on the output of scene detection. This includes saving images for each scene, exporting to CSV/HTML, or splitting the input video into individual shots.

Splitting Video¶

See also

CLI: split-video | Config file: [split-video]

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 (Sequence[tuple[FrameTimecode, FrameTimecode]]) – List of scenes (pairs of FrameTimecodes) denoting the start/end of each scene.
output_dir (str | 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], str] | 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

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 (Sequence[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) – 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

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

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

Saving Images¶

See also

CLI: save-images | Config file: [save-images]

save_images(scene_list, video, num_images=None, 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, interval=None, min_images=1, max_images=None)¶

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 | None) – Number of images to generate for each scene. Minimum is 1. Defaults to 3 if interval is not set. Cannot be used with interval.
frame_margin (int | float | str | Timecode | FrameTimecode) – Padding around the beginning and end of each scene used when selecting which frames to extract. Accepts an int (frames), float (seconds), or str (e.g. "0.1s", "00:00:00.100"). Can be 0, but some video files may then fail 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 | PathLike[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.
interval (int | float | str | Timecode | FrameTimecode | None) – If set, the number of images for each scene depends on its length instead of being num_images: each scene gets floor(scene length / interval) + 1 images, spread over the scene the same way. Accepts the same values as frame_margin. Cannot be used with num_images.
min_images (int) – Minimum number of images to generate for each scene with interval. Minimum is 1. Can only be set with interval.
max_images (int | None) – Maximum number of images to generate for each scene with interval, or None for no limit. Can only be set with interval.

Returns:

Dictionary of the format {scene_num: [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.

Raises:

ValueError – Raised if any arguments are invalid or out of range (e.g. if num_images is negative).

Return type:

dict[int, list[str]]

Scene Lists¶

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 (str | PathLike[str] | bytes | PathLike[bytes] | TextIO) – Handle to open file in write mode, or a filesystem path. A path is opened with a context manager so the file is closed after writing.
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

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 | None) – 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 of the filenames of the images saved from that scene (the number of images can differ between scenes)
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

write_scene_list_edl(output_path, scene_list, title='PySceneDetect', reel='AX', start_timecode=None)¶

Writes the given list of scenes to output_path in CMX 3600 EDL format.

Parameters:

output_path (str | PathLike[str] | bytes | PathLike[bytes] | TextIO) – Open text file or path to write the EDL file to. Parent directories must exist. When a path is provided, the file is closed after writing.
scene_list (list[tuple[FrameTimecode, FrameTimecode]]) – List of scenes as pairs of FrameTimecodes denoting each scene’s start/end.
title (str) – Title header written as TITLE: in the EDL.
reel (str) – Reel name used for each event. Typically 2-8 uppercase characters.
start_timecode (str | None) – Optional SMPTE timecode (HH:MM:SS:FF or 8-digit HHMMSSFF) added to every event so the EDL aligns with the source media’s on-screen timecode. Applied to both source and record columns.

Timecodes are written as non-drop-frame (FCM: NON-DROP FRAME), counting frames at the nominal rate: 24 per timecode second at 23.976 fps, 30 at 29.97 fps, and so on. Rates with no nominal rate (e.g. the average rate of a VFR source) are approximated from wall-clock seconds.

write_scene_list_fcpx(output_path, scene_list, video_path, frame_rate, frame_size, video_name=None)¶

Writes the given list of scenes to output_path in Final Cut Pro X XML format (FCPXML 1.9).

The output follows Apple’s FCPXML schema with rational-second time values and a custom <format> derived from the source video’s frame rate and resolution. See https://developer.apple.com/documentation/professional-video-applications/fcpxml-reference

Parameters:

output_path (str | PathLike[str] | bytes | PathLike[bytes] | TextIO) – Open text file or path to write the FCPXML file to. Parent directories must exist. When a path is provided, the file is closed after writing.
scene_list (list[tuple[FrameTimecode, FrameTimecode]]) – List of scenes as pairs of FrameTimecodes. Must not be empty.
video_path (str | Path) – Path to the source video file; written into the output as a file:// URI.
frame_rate (Fraction) – Source frame rate as a rational Fraction (e.g. Fraction(24000, 1001)).
frame_size (tuple[int, int]) – Source resolution as a (width, height) tuple in pixels.
video_name (str | None) – Display name used for the asset, project, and event. Defaults to the stem of video_path.

write_scene_list_fcp7(output_path, scene_list, video_path, frame_rate, frame_size, video_name=None, source_duration=None)¶

Writes the given list of scenes to output_path in Final Cut Pro 7 XML (xmeml) format.

See the xmeml element reference at https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/FinalCutPro_XML/. pathurl is written as a valid file:// URI per the xmeml spec.

Parameters:

output_path (str | PathLike[str] | bytes | PathLike[bytes] | TextIO) – Open text file or path to write the xmeml file to. Parent directories must exist. When a path is provided, the file is closed after writing.
scene_list (list[tuple[FrameTimecode, FrameTimecode]]) – List of scenes as pairs of FrameTimecodes. Must not be empty.
video_path (str | Path) – Path to the source video file; written into the output as a file:// URI.
frame_rate (Fraction) – Source frame rate as a rational Fraction.
frame_size (tuple[int, int]) – Source resolution as a (width, height) tuple in pixels.
video_name (str | None) – Display name used for project and sequence. Defaults to the stem of video_path.
source_duration (FrameTimecode | None) – Total duration of the source media. Required on <file> so NLEs (DaVinci Resolve, Premiere) can seek into the source - without it the clip plays frozen. If None, falls back to the last scene’s end time.

write_scene_list_otio(output_path, scene_list, video_path, frame_rate, name=None, audio=True, source_duration=None)¶

Writes the given list of scenes to output_path as an OTIO Timeline.1 JSON document.

OTIO (OpenTimelineIO) timelines can be imported by many video editors.

Parameters:

output_path (str | PathLike[str] | bytes | PathLike[bytes] | TextIO) – Open text file or path to write the OTIO file to. Parent directories must exist. When a path is provided, the file is closed after writing.
scene_list (list[tuple[FrameTimecode, FrameTimecode]]) – List of scenes as pairs of FrameTimecodes.
video_path (str | Path) – Path to the source video file; written into the output as an absolute path.
frame_rate (Fraction) – Source frame rate as a rational Fraction. Exported as a float, as the current OTIO format does not support rational timings.
name (str | None) – Timeline name. Defaults to the stem of video_path.
audio (bool) – If True (default), include an audio track alongside the video track.
source_duration (FrameTimecode | None) – Total duration of the source media. Written as the media reference’s available range so NLEs can seek into the source. If None, the available range is left unspecified rather than inferred from the selected scenes.

Filename Formatting¶

See also

CLI: the -f/--filename option of split-video and save-images

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, $START_PTS, $END_PTS (presentation timestamp in milliseconds, accurate for VFR video)

Parameters:: template (str) –
Return type:: Callable[[VideoMetadata, SceneMetadata], str]

PathFormatter¶: alias of Callable[[VideoMetadata, SceneMetadata], str]

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

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