[cli] Add new save-edl command (#495)

Output is still not verified but this is a good starting point.

Author: Breakthrough

docs/cli.rst

@@ -67,7 +67,7 @@ Options
 
 .. option:: -m TIMECODE, --min-scene-len TIMECODE
 
-  Minimum length of any scene. TIMECODE can be specified as number of frames (:option:`-m 10 <-m>`), time in seconds (:option:`-m 2.5 <-m>`), or timecode (:option:`-m 00:02:53.633 <-m>`).
+  Minimum length of any scene. TIMECODE can be specified as number of frames (-m 10), time in seconds (-m 2.5), or timecode (-m 00:02:53.633).
 
   Default: ``0.6s``
 
@@ -81,7 +81,7 @@ Options
 
 .. option:: -b BACKEND, --backend BACKEND
 
-  Backend to use for video input. Backend options can be set using a config file (:option:`-c/--config <-c>`). [available: opencv, pyav, moviepy]
+  Backend to use for video input. Backend options can be set using a config file (:option:`-c/--config <-c>`). [available: opencv, pyav]
 
   Default: ``opencv``
 
@@ -91,11 +91,11 @@ Options
 
 .. option:: -d N, --downscale N
 
-  Integer factor to downscale video by before processing. If unset, value is selected based on resolution. Set :option:`-d 1 <-d>` to disable downscaling.
+  Integer factor to downscale video by before processing. If unset, value is selected based on resolution. Set -d 1 to disable downscaling.
 
 .. option:: -fs N, --frame-skip N
 
-  Skip N frames during processing. Reduces processing speed at expense of accuracy. :option:`-fs 1 <-fs>` skips every other frame processing 50% of the video, :option:`-fs 2 <-fs>` processes 33% of the video frames, :option:`-fs 3 <-fs>` processes 25%, etc...
+  Skip N frames during processing. Reduces processing speed at expense of accuracy. -fs 1 skips every other frame processing 50% of the video, -fs 2 processes 33% of the video frames, -fs 3 processes 25%, etc...
 
   Default: ``0``
 
@@ -208,7 +208,7 @@ Options
 
 .. option:: -m TIMECODE, --min-scene-len TIMECODE
 
-  Minimum length of any scene. Overrides global option :option:`-m/--min-scene-len <scenedetect -m>`. TIMECODE can be specified in frames (:option:`-m 100 <-m>`), in seconds with `s` suffix (:option:`-m 3.5s <-m>`), or timecode (:option:`-m 00:01:52.778 <-m>`).
+  Minimum length of any scene. Overrides global option :option:`-m/--min-scene-len <scenedetect -m>`. TIMECODE can be specified in frames (-m 100), in seconds with `s` suffix (-m 3.5s), or timecode (-m 00:01:52.778).
 
 
 .. _command-detect-content:
@@ -424,7 +424,7 @@ Options
 
 .. option:: -m TIMECODE, --min-scene-len TIMECODE
 
-  Minimum length of any scene. Overrides global option :option:`-m/--min-scene-len <scenedetect -m>`. TIMECODE can be specified in frames (:option:`-m 100 <-m>`), in seconds with `s` suffix (:option:`-m 3.5s <-m>`), or timecode (:option:`-m 00:01:52.778 <-m>`).
+  Minimum length of any scene. Overrides global option :option:`-m/--min-scene-len <scenedetect -m>`. TIMECODE can be specified in frames (-m 100), in seconds with `s` suffix (-m 3.5s), or timecode (-m 00:01:52.778).
 
 
 ************************************************************************
@@ -506,7 +506,7 @@ Options
 
 .. option:: -f NAME, --filename NAME
 
-  Filename format to use for the scene list CSV file. You can use the $VIDEO_NAME macro in the file name. Note that you may have to wrap the name using single quotes or use escape characters (e.g. :option:`-f \$VIDEO_NAME-Scenes.csv <-f>`).
+  Filename format to use for the scene list CSV file. You can use the $VIDEO_NAME macro in the file name. Note that you may have to wrap the name using single quotes or use escape characters (e.g. -f \$VIDEO_NAME-Scenes.csv).
 
   Default: ``$VIDEO_NAME-Scenes.csv``
 
@@ -558,6 +558,84 @@ Options
   Default: ``"Start Frame"``
 
 
+.. _command-save-edl:
+
+.. program:: scenedetect save-edl
+
+
+``save-edl``
+========================================================================
+
+Save cuts in EDL format (CMX 3600).
+
+
+Options
+------------------------------------------------------------------------
+
+
+.. option:: -f NAME, --filename NAME
+
+  Filename format to use.
+
+  Default: ``$VIDEO_NAME.edl``
+
+.. option:: -t NAME, --title NAME
+
+  Title format to use.
+
+  Default: ``$VIDEO_NAME``
+
+.. option:: -r REEL, --reel REEL
+
+  Reel name to use.
+
+  Default: ``AX``
+
+.. option:: -o DIR, --output DIR
+
+  Output directory to save EDL file to. Overrides global option :option:`-o/--output <scenedetect -o>`.
+
+
+.. _command-save-html:
+
+.. program:: scenedetect save-html
+
+
+``save-html``
+========================================================================
+
+Save scene list to HTML file.
+
+To customize image generation, specify the :ref:`save-images <command-save-images>` command before :ref:`save-html <command-save-html>`. This command always uses the result of the preceeding :ref:`save-images <command-save-images>` command, or runs it with the default config values unless ``--no-images`` is set.
+
+
+Options
+------------------------------------------------------------------------
+
+
+.. option:: -f NAME, --filename NAME
+
+  Filename format to use for the scene list HTML file. You can use the $VIDEO_NAME macro in the file name. Note that you may have to wrap the format name using single quotes.
+
+  Default: ``$VIDEO_NAME-Scenes.html``
+
+.. option:: -n, --no-images
+
+  Do not include images with the result.
+
+.. option:: -w pixels, --image-width pixels
+
+  Width in pixels of the images in the resulting HTML table.
+
+.. option:: -h pixels, --image-height pixels
+
+  Height in pixels of the images in the resulting HTML table.
+
+.. option:: -s, --show
+
+  Automatically open resulting HTML when processing is complete.
+
+
 .. _command-save-images:
 
 .. program:: scenedetect save-images
@@ -590,13 +668,13 @@ Options
 
 .. option:: -f NAME, --filename NAME
 
-  Filename format *without* extension to use when saving images. You can use the $VIDEO_NAME, $SCENE_NUMBER, $IMAGE_NUMBER, and $FRAME_NUMBER macros in the file name. You may have to use escape characters (e.g. :option:`-f \$SCENE_NUMBER-Image-\$IMAGE_NUMBER <-f>`) or single quotes.
+  Filename format *without* extension to use when saving images. You can use the $VIDEO_NAME, $SCENE_NUMBER, $IMAGE_NUMBER, and $FRAME_NUMBER macros in the file name. You may have to use escape characters (e.g. -f \$SCENE_NUMBER-Image-\$IMAGE_NUMBER) or single quotes.
 
   Default: ``$VIDEO_NAME-Scene-$SCENE_NUMBER-$IMAGE_NUMBER``
 
 .. option:: -n N, --num-images N
 
-  Number of images to generate per scene. Will always include start/end frame, unless :option:`-n 1 <-n>`, in which case the image will be the frame at the mid-point of the scene.
+  Number of images to generate per scene. Will always include start/end frame, unless -n 1, in which case the image will be the frame at the mid-point of the scene.
 
   Default: ``3``
 
@@ -675,6 +753,38 @@ Options
   Disable shifting frame numbers by start time.
 
 
+.. _command-save-xml:
+
+.. program:: scenedetect save-xml
+
+
+``save-xml``
+========================================================================
+
+Save cuts in XML format.
+
+
+Options
+------------------------------------------------------------------------
+
+
+.. option:: -f NAME, --filename NAME
+
+  Filename format to use.
+
+  Default: ``$VIDEO_NAME.xml``
+
+.. option:: --format TYPE
+
+  Format to export. TYPE must be one of: fcpx, fcp.
+
+  Default: ``XmlFormat.FCPX``
+
+.. option:: -o DIR, --output DIR
+
+  Output directory to save XML file to. Overrides global option :option:`-o/--output <scenedetect -o>`.
+
+
 .. _command-split-video:
 
 .. program:: scenedetect split-video
@@ -713,7 +823,7 @@ Options
 
 .. option:: -f NAME, --filename NAME
 
-  File name format to use when saving videos, with or without extension. You can use $VIDEO_NAME and $SCENE_NUMBER macros in the filename. You may have to wrap the format in single quotes or use escape characters to avoid variable expansion (e.g. :option:`-f \$VIDEO_NAME-Scene-\$SCENE_NUMBER <-f>`).
+  File name format to use when saving videos, with or without extension. You can use $VIDEO_NAME and $SCENE_NUMBER macros in the filename. You may have to wrap the format in single quotes or use escape characters to avoid variable expansion (e.g. -f \$VIDEO_NAME-Scene-\$SCENE_NUMBER).
 
   Default: ``$VIDEO_NAME-Scene-$SCENE_NUMBER``
 

scenedetect.cfg

@@ -302,6 +302,21 @@
 #start-col-name = Start Frame
 
 
+[save-edl]
+
+# Filename format of EDL file. Can use $VIDEO_NAME macro.
+#filename = $VIDEO_NAME.edl
+
+# Folder to output EDL file to. Overrides [global] output option.
+#output = /usr/tmp/images
+
+# Reel/tape name to use.
+#reel = AX
+
+# Title to use for the EDL file. Can use $VIDEO_NAME macro.
+#title = $VIDEO_NAME
+
+
 [save-qp]
 
 # Filename format of QP file. Can use $VIDEO_NAME macro.
@@ -314,7 +329,6 @@
 #disable-shift = no
 
 
-
 [save-xml]
 
 # Filename format of XML file. Can use $VIDEO_NAME macro.

scenedetect/_cli/__init__.py

@@ -1520,6 +1520,62 @@ def save_images_command(
     ctx.save_images = True
 
 
+SAVE_EDL_HELP = """Save cuts in EDL format (CMX 3600)."""
+
+
+@click.command("save-edl", cls=Command, help=SAVE_EDL_HELP)
+@click.option(
+    "--filename",
+    "-f",
+    metavar="NAME",
+    default=None,
+    type=click.STRING,
+    help="Filename format to use.%s" % (USER_CONFIG.get_help_string("save-edl", "filename")),
+)
+@click.option(
+    "--title",
+    "-t",
+    metavar="NAME",
+    default=None,
+    type=click.STRING,
+    help="Title format to use.%s" % (USER_CONFIG.get_help_string("save-edl", "title")),
+)
+@click.option(
+    "--reel",
+    "-r",
+    metavar="REEL",
+    default=None,
+    type=click.STRING,
+    help="Reel name to use.%s" % (USER_CONFIG.get_help_string("save-edl", "reel")),
+)
+@click.option(
+    "--output",
+    "-o",
+    metavar="DIR",
+    type=click.Path(exists=False, dir_okay=True, writable=True, resolve_path=False),
+    help="Output directory to save EDL file to. Overrides global option -o/--output.%s"
+    % (USER_CONFIG.get_help_string("save-edl", "output", show_default=False)),
+)
+@click.pass_context
+def save_edl_command(
+    ctx: click.Context,
+    filename: ty.Optional[ty.AnyStr],
+    title: ty.Optional[ty.AnyStr],
+    reel: ty.Optional[ty.AnyStr],
+    output: ty.Optional[ty.AnyStr],
+):
+    ctx = ctx.obj
+    assert isinstance(ctx, CliContext)
+
+    save_edl_args = {
+        "filename": ctx.config.get_value("save-edl", "filename", filename),
+        "title": ctx.config.get_value("save-edl", "title", title),
+        "reel": ctx.config.get_value("save-edl", "reel", reel),
+        "output": ctx.config.get_value("save-edl", "output", output),
+    }
+    ctx.add_command(cli_commands.save_edl, save_edl_args)
+
+
 SAVE_QP_HELP = """Save cuts as keyframes (I-frames) for video encoding.
 
 The resulting QP file can be used with the `--qpfile` argument in x264/x265.
@@ -1643,6 +1699,7 @@ def save_xml_command(
 
 # Output
 scenedetect.add_command(list_scenes_command)
+scenedetect.add_command(save_edl_command)
 scenedetect.add_command(save_html_command)
 scenedetect.add_command(save_images_command)
 scenedetect.add_command(save_qp_command)

scenedetect/_cli/commands.py

@@ -26,6 +26,7 @@
 
 from scenedetect._cli.config import XmlFormat
 from scenedetect._cli.context import CliContext
+from scenedetect.frame_timecode import FrameTimecode
 from scenedetect.platform import get_and_create_path
 from scenedetect.scene_manager import (
     CutList,
@@ -255,6 +256,65 @@ def split_video(
         logger.info("Video splitting completed, scenes written to disk.")
 
 
+def save_edl(
+    context: CliContext,
+    scenes: SceneList,
+    cuts: CutList,
+    filename: str,
+    output: str,
+    title: str,
+    reel: str,
+):
+    """Handles the `save-edl` command. Outputs in CMX 3600 format."""
+    # We only use scene information.
+    del cuts
+
+    # Converts FrameTimecode to HH:MM:SS:FF
+    # TODO: This should be part of the FrameTimecode object itself.
+    def get_edl_timecode(timecode: FrameTimecode):
+        total_seconds = timecode.get_seconds()
+        hours = int(total_seconds // 3600)
+        minutes = int((total_seconds % 3600) // 60)
+        seconds = int(total_seconds % 60)
+        frames_part = int((total_seconds * timecode.get_framerate()) % timecode.get_framerate())
+        return f"{hours:02d}:{minutes:02d}:{seconds:02d}:{frames_part:02d}"
+
+    edl_content = []
+
+    title = Template(title).safe_substitute(VIDEO_NAME=context.video_stream.name)
+    edl_content.append(f"TITLE: {title}")
+    edl_content.append("FCM: NON-DROP FRAME")
+    edl_content.append("")
+
+    # Add each shot as an edit entry
+    for i, (start, end) in enumerate(scenes):
+        # TODO: Handle start time shift.
+        in_tc = get_edl_timecode(start)
+        out_tc = get_edl_timecode(end)
+
+        # TODO: How should the source/rec timestamps be aligned? One example I found showed:
+        #
+        # 001  AX V     C        00:00:00:00 00:00:10:00 00:00:00:00 00:00:10:00
+        # 002  AX V     C        00:00:10:01 00:00:20:00 00:00:10:00 00:00:20:00
+        # 003  AX V     C        00:00:20:01 00:00:30:00 00:00:20:00 00:00:30:00
+        # 004  AX V     C        00:00:30:01 00:00:40:00 00:00:30:00 00:00:40:00
+        #                                  ^
+        #                                  |- Shifted by 1 frame here
+
+        # Format the edit entry according to CMX 3600 format
+        event_line = f"{(i + 1):03d}  {reel} V     C        {in_tc} {out_tc} {in_tc} {out_tc}"
+        edl_content.append(event_line)
+
+    edl_path = get_and_create_path(
+        Template(filename).safe_substitute(VIDEO_NAME=context.video_stream.name),
+        output,
+    )
+    logger.info(f"Writing scenes in EDL format to {edl_path}")
+    with open(edl_path, "w") as f:
+        f.write("\n".join(edl_content))
+        f.write("\n")
+
+
 def _save_xml_fcpx(
     context: CliContext,
     scenes: SceneList,

scenedetect/_cli/config.py

@@ -397,6 +397,12 @@ class XmlFormat(Enum):
         "output": None,
         "verbosity": "info",
     },
+    "save-edl": {
+        "filename": "$VIDEO_NAME.edl",
+        "output": None,
+        "reel": "AX",
+        "title": "$VIDEO_NAME",
+    },
     "save-html": {
         "filename": "$VIDEO_NAME-Scenes.html",
         "image-height": 0,