[cli] Add new save-xml command

Supports Final Cut Pro X and 7 formats, but there are still *many* TODOs to address.

The output has not yet been validated and may not be usable yet.

Author: Breakthrough

scenedetect.cfg

@@ -314,6 +314,21 @@
 #disable-shift = no
 
 
+
+[save-xml]
+
+# 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 (default)
+#  - fcp:   Final Cut Pro 7
+#format = fcpx
+
+# Folder to output XML file to. Overrides [global] output option.
+#output = /usr/tmp/images
+
+
 #
 # BACKEND OPTIONS
 #

scenedetect/_cli/__init__.py

@@ -35,6 +35,7 @@
     CONFIG_MAP,
     DEFAULT_JPG_QUALITY,
     DEFAULT_WEBP_QUALITY,
+    XmlFormat,
 )
 from scenedetect._cli.context import USER_CONFIG, CliContext, check_split_video_requirements
 from scenedetect.backends import AVAILABLE_BACKENDS
@@ -1569,6 +1570,57 @@ def save_qp_command(
     ctx.add_command(cli_commands.save_qp, save_qp_args)
 
 
+SAVE_XML_HELP = """Save cuts in XML format."""
+
+
+@click.command("save-xml", cls=Command, help=SAVE_XML_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")),
+)
+@click.option(
+    "--format",
+    metavar="TYPE",
+    type=click.Choice(CHOICE_MAP["save-xml"]["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"),
+    ),
+)
+@click.option(
+    "--output",
+    "-o",
+    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)),
+)
+@click.pass_context
+def save_xml_command(
+    ctx: click.Context,
+    filename: ty.Optional[ty.AnyStr],
+    format: ty.Optional[ty.AnyStr],
+    output: ty.Optional[ty.AnyStr],
+):
+    ctx = ctx.obj
+    assert isinstance(ctx, CliContext)
+
+    # TODO: Change config parser so get_value returns enums directly.
+    format = XmlFormat[ctx.config.get_value("save-xml", "format", format).upper()]
+    save_xml_args = {
+        "filename": ctx.config.get_value("save-xml", "filename", filename),
+        "format": format,
+        "output": ctx.config.get_value("save-xml", "output", output),
+    }
+    ctx.add_command(cli_commands.save_xml, save_xml_args)
+
+
 # ----------------------------------------------------------------------
 # CLI Sub-Command Registration
 # ----------------------------------------------------------------------
@@ -1590,10 +1642,11 @@ def save_qp_command(
 scenedetect.add_command(detect_threshold_command)
 
 # Output
-scenedetect.add_command(save_html_command)
-scenedetect.add_command(save_qp_command)
 scenedetect.add_command(list_scenes_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(split_video_command)
 
 # Deprecated Commands (Hidden From Help Output)

scenedetect/_cli/commands.py

@@ -18,8 +18,13 @@
 import logging
 import typing as ty
 import webbrowser
+from datetime import datetime
+from pathlib import Path
 from string import Template
+from xml.dom import minidom
+from xml.etree import ElementTree
 
+from scenedetect._cli.config import XmlFormat
 from scenedetect._cli.context import CliContext
 from scenedetect.platform import get_and_create_path
 from scenedetect.scene_manager import (
@@ -248,3 +253,175 @@ def split_video(
         )
     if scenes:
         logger.info("Video splitting completed, scenes written to disk.")
+
+
+def _save_xml_fcpx(
+    context: CliContext,
+    scenes: SceneList,
+    filename: str,
+    output: str,
+):
+    """Saves scenes in Final Cut Pro X XML format."""
+    ASSET_ID = "asset1"
+    FORMAT_ID = "format1"
+    # TODO: Need to handle other video formats!
+    VIDEO_FORMAT_TODO_HANDLE_OTHERS = "FFVideoFormat1080p24"
+
+    root = ElementTree.Element("fcpxml", version="1.9")
+    resources = ElementTree.SubElement(root, "resources")
+    ElementTree.SubElement(resources, "format", id="format1", name=VIDEO_FORMAT_TODO_HANDLE_OTHERS)
+
+    video_name = context.video_stream.name
+
+    # TODO: We should calculate duration from the scene list.
+    duration = context.video_stream.duration
+    duration = str(duration.get_seconds()) + "s"  # TODO: Is float okay here?
+    # TODO: This should be an absolute path, but the path types between VideoStream impls aren't
+    # consistent. Need to make a breaking change to the API so that they return pathlib.Path types.
+    path = context.video_stream.path
+    ElementTree.SubElement(
+        resources,
+        "asset",
+        id=ASSET_ID,
+        name=video_name,
+        src=path,
+        duration=duration,
+        hasVideo="1",
+        hasAudio="1",  # TODO: Handle case of no audio.
+        format=FORMAT_ID,
+    )
+
+    library = ElementTree.SubElement(root, "library")
+    now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    event = ElementTree.SubElement(library, "event", name=f"Shot Detection {now}")
+    project = ElementTree.SubElement(
+        event, "project", name=video_name
+    )  # TODO: Allow customizing project name.
+    sequence = ElementTree.SubElement(project, "sequence", format=FORMAT_ID, duration=duration)
+    spine = ElementTree.SubElement(sequence, "spine")
+
+    for i, (start, end) in enumerate(scenes):
+        start_seconds = start.get_seconds()
+        duration_seconds = (end - start).get_seconds()
+        clip = ElementTree.SubElement(
+            spine,
+            "clip",
+            name=f"Shot {i + 1}",
+            duration=f"{duration_seconds:.3f}s",
+            start=f"{start_seconds:.3f}s",
+            offset=f"{start_seconds:.3f}s",
+        )
+        ElementTree.SubElement(
+            clip,
+            "asset-clip",
+            ref=ASSET_ID,
+            duration=f"{duration_seconds:.3f}s",
+            start=f"{start_seconds:.3f}s",
+            offset="0s",
+            name=f"Shot {i + 1}",
+        )
+
+    pretty_xml = minidom.parseString(ElementTree.tostring(root, encoding="unicode")).toprettyxml(
+        indent="  "
+    )
+    xml_path = get_and_create_path(
+        Template(filename).safe_substitute(VIDEO_NAME=context.video_stream.name),
+        output,
+    )
+    logger.info(f"Writing scenes in FCPX format to {xml_path}")
+    with open(xml_path, "w") as f:
+        f.write(pretty_xml)
+
+
+def _save_xml_fcp(
+    context: CliContext,
+    scenes: SceneList,
+    filename: str,
+    output: str,
+):
+    """Saves scenes in Final Cut Pro 7 XML format."""
+    root = ElementTree.Element("xmeml", version="5")
+    project = ElementTree.SubElement(root, "project")
+    ElementTree.SubElement(project, "name").text = context.video_stream.name
+    sequence = ElementTree.SubElement(project, "sequence")
+    ElementTree.SubElement(sequence, "name").text = context.video_stream.name
+
+    # TODO: We should calculate duration from the scene list.
+    duration = context.video_stream.duration
+    duration = str(duration.get_seconds())  # TODO: Is float okay here?
+    ElementTree.SubElement(sequence, "duration").text = duration
+
+    rate = ElementTree.SubElement(sequence, "rate")
+    ElementTree.SubElement(rate, "timebase").text = str(context.video_stream.frame_rate)
+    ElementTree.SubElement(rate, "ntsc").text = "FALSE"
+
+    timecode = ElementTree.SubElement(sequence, "timecode")
+    tc_rate = ElementTree.SubElement(timecode, "rate")
+    ElementTree.SubElement(tc_rate, "timebase").text = str(context.video_stream.frame_rate)
+    ElementTree.SubElement(tc_rate, "ntsc").text = "FALSE"
+    ElementTree.SubElement(timecode, "frame").text = "0"
+    ElementTree.SubElement(timecode, "displayformat").text = "NDF"
+
+    media = ElementTree.SubElement(sequence, "media")
+    video = ElementTree.SubElement(media, "video")
+    format = ElementTree.SubElement(video, "format")
+    ElementTree.SubElement(format, "samplecharacteristics")
+    track = ElementTree.SubElement(video, "track")
+
+    # Add clips for each shot boundary
+    for i, (start, end) in enumerate(scenes):
+        clip = ElementTree.SubElement(track, "clipitem")
+        ElementTree.SubElement(clip, "name").text = f"Shot {i + 1}"
+        ElementTree.SubElement(clip, "enabled").text = "TRUE"
+        ElementTree.SubElement(clip, "rate").append(
+            ElementTree.fromstring(f"<timebase>{context.video_stream.frame_rate}</timebase>")
+        )
+        # TODO: Are these supposed to be frame numbers or another format?
+        ElementTree.SubElement(clip, "start").text = str(start.get_frames())
+        ElementTree.SubElement(clip, "end").text = str(end.get_frames())
+        ElementTree.SubElement(clip, "in").text = str(start.get_frames())
+        ElementTree.SubElement(clip, "out").text = str(end.get_frames())
+
+        file_ref = ElementTree.SubElement(clip, "file", id=f"file{i + 1}")
+        ElementTree.SubElement(file_ref, "name").text = context.video_stream.name
+        # TODO: Turn this into absolute path, see TODO in the FCPX function for details.
+        path = context.video_stream.path
+        ElementTree.SubElement(file_ref, "pathurl").text = f"file://{path}"
+
+        media_ref = ElementTree.SubElement(file_ref, "media")
+        video_ref = ElementTree.SubElement(media_ref, "video")
+        ElementTree.SubElement(video_ref, "samplecharacteristics")
+        link = ElementTree.SubElement(clip, "link")
+        ElementTree.SubElement(link, "linkclipref").text = f"file{i + 1}"
+        ElementTree.SubElement(link, "mediatype").text = "video"
+
+    pretty_xml = minidom.parseString(ElementTree.tostring(root, encoding="unicode")).toprettyxml(
+        indent="  "
+    )
+    xml_path = get_and_create_path(
+        Template(filename).safe_substitute(VIDEO_NAME=context.video_stream.name),
+        output,
+    )
+    logger.info(f"Writing scenes in FCP format to {xml_path}")
+    with open(xml_path, "w") as f:
+        f.write(pretty_xml)
+
+
+def save_xml(
+    context: CliContext,
+    scenes: SceneList,
+    cuts: CutList,
+    filename: str,
+    format: XmlFormat,
+    output: str,
+):
+    """Handles the `save-xml` command."""
+    # We only use scene information.
+    del cuts
+
+    if format == XmlFormat.FCPX:
+        _save_xml_fcpx(context, scenes, filename, output)
+    elif format == XmlFormat.FCP:
+        _save_xml_fcp(context, scenes, filename, output)
+    else:
+        logger.error(f"Unknown format: {format}")

scenedetect/_cli/config.py

@@ -305,6 +305,15 @@ def format(self, timecode: FrameTimecode) -> str:
         raise RuntimeError("Unhandled format specifier.")
 
 
+class XmlFormat(Enum):
+    """Format to use with the `save-xml` command."""
+
+    FCPX = 0
+    """Final Cut Pro X XML Format"""
+    FCP = 1
+    """Final Cut Pro 7 XML Format"""
+
+
 ConfigValue = ty.Union[bool, int, float, str]
 ConfigDict = ty.Dict[str, ty.Dict[str, ConfigValue]]
 
@@ -414,6 +423,11 @@ def format(self, timecode: FrameTimecode) -> str:
         "filename": "$VIDEO_NAME.qp",
         "output": None,
     },
+    "save-xml": {
+        "format": XmlFormat.FCPX,
+        "filename": "$VIDEO_NAME.xml",
+        "output": None,
+    },
     "split-video": {
         "args": DEFAULT_FFMPEG_ARGS,
         "copy": False,
@@ -430,6 +444,8 @@ def format(self, timecode: FrameTimecode) -> str:
 The types of these values are used when decoding the configuration file. Valid choices for
 certain string options are stored in `CHOICE_MAP`."""
 
+# TODO: Use the fact that all enums derive from the Enum class to avoid duplicating their values
+# here in the choice map.
 CHOICE_MAP: ty.Dict[str, ty.Dict[str, ty.List[str]]] = {
     "backend-pyav": {
         "threading_mode": [mode.lower() for mode in PYAV_THREADING_MODES],
@@ -456,6 +472,9 @@ def format(self, timecode: FrameTimecode) -> str:
         "format": ["jpeg", "png", "webp"],
         "scale-method": [value.name.lower() for value in Interpolation],
     },
+    "save-xml": {
+        "format": [value.name.lower() for value in XmlFormat],
+    },
     "split-video": {
         "preset": [
             "ultrafast",

website/pages/changelog.md

@@ -624,6 +624,11 @@ Development
 
 ## PySceneDetect 0.6.6 (In Development)
 
+### Work In Progress
+- [feature] New `save-xml` command supports saving scenes in Final Cut Pro format [#156](https://github.com/Breakthrough/PySceneDetect/issues/156)
+
+### Complete
+
  - [general] The `export-html` command is now deprecated, use `save-html` instead
  - [bugfix] Fix incorrect help entries for short-form arguments which suggested invalid syntax [#493](https://github.com/Breakthrough/PySceneDetect/issues/493)
  - [bugfix] Fix crash when using `split-video` with `-m`/`--mkvmerge` option [#473](https://github.com/Breakthrough/PySceneDetect/issues/473)