Add New Output Methods to Python API + Finalize FCPX Support (#543)

* [cli] Finalize `save-xml` for release

Tested FCPX and FCP7 formats on DaVinci Resolve.

* [api] Add EDL, FCP7/X, and OTIO formats to scenedetect.output

Rename save-xml -> save-fcp.

* [docs] Regenerate CLI docs

Author: Breakthrough

docs/api/migration_guide.rst

@@ -203,4 +203,4 @@ CLI Changes
 
 - The ``-d``/``--min-delta-hsv`` option on ``detect-adaptive`` has been removed. Use ``-c``/``--min-content-val`` instead.
 - VFR videos now work correctly with both the OpenCV and PyAV backends.
-- New ``save-xml`` command for exporting scenes in Final Cut Pro XML format.
+- New ``save-fcp`` command for exporting scenes in Final Cut Pro XML format.

docs/api/output.rst

@@ -20,6 +20,14 @@ Ouptut
 
 .. autofunction:: scenedetect.output.write_scene_list
 
+.. autofunction:: scenedetect.output.write_scene_list_edl
+
+.. autofunction:: scenedetect.output.write_scene_list_fcpx
+
+.. autofunction:: scenedetect.output.write_scene_list_fcp7
+
+.. autofunction:: scenedetect.output.write_scene_list_otio
+
 .. autoclass:: scenedetect.output.SceneMetadata
 
 .. autoclass:: scenedetect.output.VideoMetadata

docs/cli.rst

@@ -178,8 +178,6 @@ Options
 
   Default: ``15.0``
 
-
-
 .. option:: -f VAL, --frame-window VAL
 
   Size of window to detect deviations from mean. Represents how many frames before/after the current one to use for mean.
@@ -552,6 +550,38 @@ Options
   Output directory to save EDL file to. Overrides global option :option:`-o/--output <scenedetect -o>`.
 
 
+.. _command-save-fcp:
+
+.. program:: scenedetect save-fcp
+
+
+``save-fcp``
+========================================================================
+
+Save cuts in Final Cut Pro XML format (FCP7 xmeml or FCPX).
+
+
+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, fcp7.
+
+  Default: ``FcpFormat.FCPX``
+
+.. option:: -o DIR, --output DIR
+
+  Output directory to save XML file to. Overrides global option :option:`-o/--output <scenedetect -o>`.
+
+
 .. _command-save-html:
 
 .. program:: scenedetect save-html
@@ -658,11 +688,11 @@ Options
 
   Default: ``3``
 
-.. option:: -m N, --frame-margin N
+.. option:: -m DURATION, --frame-margin DURATION
 
-  Number of frames to ignore at beginning/end of scenes when saving images. Controls temporal padding on scene boundaries.
+  Padding around the beginning/end of each scene used when selecting which frames to extract. DURATION can be specified in frames (-m 1), in seconds with `s` suffix (-m 0.1s), or timecode (-m 00:00:00.100).
 
-  Default: ``3``
+  Default: ``1``
 
 .. option:: -s S, --scale S
 

scenedetect.cfg

@@ -345,6 +345,20 @@
 #disable-shift = no
 
 
+[save-fcp]
+
+# Filename format of XML file. Can use $VIDEO_NAME macro.
+#filename = $VIDEO_NAME.xml
+
+# Format of the XML file. Must be one of:
+#  - fcpx:  Final Cut Pro X (FCPXML, default)
+#  - fcp7:  Final Cut Pro 7 (xmeml)
+#format = fcpx
+
+# Folder to output XML file to. Overrides [global] output option.
+#output = /usr/tmp/images
+
+
 #
 # BACKEND OPTIONS
 #

scenedetect/_cli/__init__.py

@@ -1614,27 +1614,27 @@ def save_qp_command(
     ctx.add_command(cli_commands.save_qp, save_qp_args)
 
 
-SAVE_XML_HELP = """[IN DEVELOPMENT] Save cuts in XML format."""
+SAVE_FCP_HELP = """Save cuts in Final Cut Pro XML format (FCP7 xmeml or FCPX)."""
 
 
-@click.command("save-xml", cls=Command, help=SAVE_XML_HELP, hidden=True)
+@click.command("save-fcp", cls=Command, help=SAVE_FCP_HELP)
 @click.option(
     "--filename",
     "-f",
     metavar="NAME",
     default=None,
     type=click.STRING,
-    help="Filename format to use.%s" % (USER_CONFIG.get_help_string("save-xml", "filename")),
+    help="Filename format to use.%s" % (USER_CONFIG.get_help_string("save-fcp", "filename")),
 )
 @click.option(
     "--format",
     metavar="TYPE",
-    type=click.Choice(CHOICE_MAP["save-xml"]["format"], False),
+    type=click.Choice(CHOICE_MAP["save-fcp"]["format"], False),
     default=None,
     help="Format to export. TYPE must be one of: %s.%s"
     % (
-        ", ".join(CHOICE_MAP["save-xml"]["format"]),
-        USER_CONFIG.get_help_string("save-xml", "format"),
+        ", ".join(CHOICE_MAP["save-fcp"]["format"]),
+        USER_CONFIG.get_help_string("save-fcp", "format"),
     ),
 )
 @click.option(
@@ -1643,10 +1643,10 @@ def save_qp_command(
     metavar="DIR",
     type=click.Path(exists=False, dir_okay=True, writable=True, resolve_path=False),
     help="Output directory to save XML file to. Overrides global option -o/--output.%s"
-    % (USER_CONFIG.get_help_string("save-xml", "output", show_default=False)),
+    % (USER_CONFIG.get_help_string("save-fcp", "output", show_default=False)),
 )
 @click.pass_context
-def save_xml_command(
+def save_fcp_command(
     ctx: click.Context,
     filename: ty.Optional[ty.AnyStr],
     format: ty.Optional[ty.AnyStr],
@@ -1655,12 +1655,12 @@ def save_xml_command(
     ctx = ctx.obj
     assert isinstance(ctx, CliContext)
 
-    save_xml_args = {
-        "filename": ctx.config.get_value("save-xml", "filename", filename),
-        "format": ctx.config.get_value("save-xml", "format", format),
-        "output": ctx.config.get_value("save-xml", "output", output),
+    save_fcp_args = {
+        "filename": ctx.config.get_value("save-fcp", "filename", filename),
+        "format": ctx.config.get_value("save-fcp", "format", format),
+        "output": ctx.config.get_value("save-fcp", "output", output),
     }
-    ctx.add_command(cli_commands.save_xml, save_xml_args)
+    ctx.add_command(cli_commands.save_fcp, save_fcp_args)
 
 
 SAVE_OTIO_HELP = """Save cuts as an OTIO timeline.
@@ -1757,7 +1757,7 @@ def save_otio_command(
 scenedetect.add_command(save_html_command)
 scenedetect.add_command(save_images_command)
 scenedetect.add_command(save_qp_command)
-scenedetect.add_command(save_xml_command)
+scenedetect.add_command(save_fcp_command)
 scenedetect.add_command(save_otio_command)
 scenedetect.add_command(split_video_command)