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.

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

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 | Path) – Path to write the EDL file to. Parent directories must exist.

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

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 | Path) – Path to write the xmeml file to. Parent directories must exist.

  • 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_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 | Path) – Path to write the FCPXML file to. Parent directories must exist.

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

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

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 | Path) – Path to write the OTIO file to. Parent directories must exist.

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