[feat] Add start TC shift to save-edl functionality #515

Author: Breakthrough

scenedetect/_cli/__init__.py

@@ -1597,13 +1597,26 @@ def save_images_command(
         USER_CONFIG.get_help_string("save-edl", "output", show_default=False)
     ),
 )
+@click.option(
+    "--start-timecode",
+    "-s",
+    metavar="TIMECODE",
+    default=None,
+    type=click.STRING,
+    help=(
+        "Start timecode added to every event so the EDL aligns with the source media's "
+        "on-screen timecode. Accepts SMPTE HH:MM:SS:FF or 8 digits (HHMMSSFF, e.g. 01000000)."
+        "{}"
+    ).format(USER_CONFIG.get_help_string("save-edl", "start-timecode", show_default=False)),
+)
 @click.pass_context
 def save_edl_command(
     ctx: click.Context,
     filename: str | None,
     title: str | None,
     reel: str | None,
     output: str | None,
+    start_timecode: str | None,
 ):
     ctx = ctx.obj
     assert isinstance(ctx, CliContext)
@@ -1613,6 +1626,7 @@ def save_edl_command(
         "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),
+        "start_timecode": ctx.config.get_value("save-edl", "start-timecode", start_timecode),
     }
     ctx.add_command(cli_commands.save_edl, save_edl_args)
 

scenedetect/_cli/commands.py

@@ -263,6 +263,7 @@ def save_edl(
     output: str,
     title: str,
     reel: str,
+    start_timecode: str | None,
 ):
     """Handles the `save-edl` command. Outputs in CMX 3600 format."""
     del cuts  # We only use scene information.
@@ -277,6 +278,7 @@ def save_edl(
         scene_list=scenes,
         title=Template(title).safe_substitute(VIDEO_NAME=video_name),
         reel=reel,
+        start_timecode=start_timecode,
     )
 
 

scenedetect/_cli/config.py

@@ -424,6 +424,7 @@ class FcpFormat(Enum):
         "filename": "$VIDEO_NAME.edl",
         "output": None,
         "reel": "AX",
+        "start-timecode": None,
         "title": "$VIDEO_NAME",
     },
     "save-html": {

scenedetect/output/__init__.py

@@ -18,6 +18,7 @@
 import csv
 import json
 import logging
+import math
 import typing as ty
 from fractions import Fraction
 from pathlib import Path
@@ -253,11 +254,36 @@ def _edl_timecode(timecode: FrameTimecode) -> str:
     return f"{hours:02d}:{minutes:02d}:{seconds:02d}:{frames_part:02d}"
 
 
+def _parse_edl_start_timecode(value: str, framerate: Fraction | float) -> int:
+    """Parse a SMPTE ``HH:MM:SS:FF`` (or 8-digit ``HHMMSSFF``) start timecode into a frame count."""
+    stripped = value.strip()
+    if ":" in stripped:
+        parts = stripped.split(":")
+    elif stripped.isdigit() and len(stripped) == 8:
+        parts = [stripped[0:2], stripped[2:4], stripped[4:6], stripped[6:8]]
+    else:
+        raise ValueError(
+            f"Invalid start timecode {value!r}: expected HH:MM:SS:FF or 8 digits (HHMMSSFF)."
+        )
+    if len(parts) != 4 or not all(p.isdigit() for p in parts):
+        raise ValueError(
+            f"Invalid start timecode {value!r}: expected HH:MM:SS:FF or 8 digits (HHMMSSFF)."
+        )
+    hours, minutes, seconds, frames = (int(p) for p in parts)
+    max_frames = math.ceil(float(framerate))
+    if minutes >= 60 or seconds >= 60 or frames >= max_frames:
+        raise ValueError(
+            f"Invalid start timecode {value!r}: MM<60, SS<60, FF<{max_frames} required."
+        )
+    return round((hours * 3600 + minutes * 60 + seconds) * float(framerate)) + frames
+
+
 def write_scene_list_edl(
     output_path: str | Path,
     scene_list: SceneList,
     title: str = "PySceneDetect",
     reel: str = "AX",
+    start_timecode: str | None = None,
 ):
     """Writes the given list of scenes to `output_path` in CMX 3600 EDL format.
 
@@ -266,12 +292,20 @@ def write_scene_list_edl(
         scene_list: List of scenes as pairs of FrameTimecodes denoting each scene's start/end.
         title: Title header written as ``TITLE:`` in the EDL.
         reel: Reel name used for each event. Typically 2-8 uppercase characters.
+        start_timecode: 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.
     """
     output_path = Path(output_path)
+    offset_frames = 0
+    if start_timecode is not None and start_timecode.strip() and scene_list:
+        framerate = scene_list[0][0].framerate
+        assert framerate is not None
+        offset_frames = _parse_edl_start_timecode(start_timecode, framerate)
     lines = [f"TITLE: {title}", "FCM: NON-DROP FRAME", ""]
     for i, (start, end) in enumerate(scene_list):
-        in_tc = _edl_timecode(start)
-        out_tc = _edl_timecode(end)
+        in_tc = _edl_timecode(start + offset_frames)
+        out_tc = _edl_timecode(end + offset_frames)
         lines.append(f"{(i + 1):03d}  {reel} V     C        {in_tc} {out_tc} {in_tc} {out_tc}")
     logger.info("Writing scenes in EDL format to %s", output_path)
     with open(output_path, "w") as f:

tests/test_output.py

@@ -269,6 +269,84 @@ def test_write_scene_list_edl_accepts_str_path(tmp_path: Path):
     assert output_path.exists()
 
 
+def test_write_scene_list_edl_with_start_timecode_smpte(tmp_path: Path):
+    """`start_timecode` shifts every event by the supplied SMPTE offset (source + record)."""
+    scenes = _fake_scenes(_FPS_CFR, [(0, 30), (30, 60)])
+    output_path = tmp_path / "scenes.edl"
+    write_scene_list_edl(output_path, scenes, start_timecode="01:00:00:00")
+
+    content = output_path.read_text()
+    assert "001  AX V     C        01:00:00:00 01:00:01:00 01:00:00:00 01:00:01:00" in content
+    assert "002  AX V     C        01:00:01:00 01:00:02:00 01:00:01:00 01:00:02:00" in content
+
+
+def test_write_scene_list_edl_with_start_timecode_digits(tmp_path: Path):
+    """8-digit form (numpad-friendly) yields the same output as the colon-separated form."""
+    scenes = _fake_scenes(_FPS_CFR, [(0, 30), (30, 60)])
+    smpte_path = tmp_path / "smpte.edl"
+    digits_path = tmp_path / "digits.edl"
+    write_scene_list_edl(smpte_path, scenes, start_timecode="01:00:00:00")
+    write_scene_list_edl(digits_path, scenes, start_timecode="01000000")
+
+    assert smpte_path.read_text() == digits_path.read_text()
+
+
+def test_write_scene_list_edl_with_start_timecode_subsecond(tmp_path: Path):
+    """A sub-second frame offset (FF component) is added to every event."""
+    scenes = _fake_scenes(_FPS_CFR, [(0, 30)])
+    output_path = tmp_path / "scenes.edl"
+    write_scene_list_edl(output_path, scenes, start_timecode="00:00:00:15")
+
+    content = output_path.read_text()
+    assert "001  AX V     C        00:00:00:15 00:00:01:15 00:00:00:15 00:00:01:15" in content
+
+
+def test_write_scene_list_edl_default_no_offset(tmp_path: Path):
+    """Omitting `start_timecode` (or passing ``None``/empty) preserves the existing baseline."""
+    scenes = _fake_scenes(_FPS_CFR, [(0, 30), (30, 60)])
+    baseline = tmp_path / "baseline.edl"
+    explicit_none = tmp_path / "none.edl"
+    explicit_empty = tmp_path / "empty.edl"
+    write_scene_list_edl(baseline, scenes)
+    write_scene_list_edl(explicit_none, scenes, start_timecode=None)
+    write_scene_list_edl(explicit_empty, scenes, start_timecode="   ")
+
+    assert baseline.read_text() == explicit_none.read_text() == explicit_empty.read_text()
+
+
+@pytest.mark.parametrize(
+    "bad_value",
+    [
+        "bogus",
+        "00:00:00",  # 3 segments, not 4
+        "00:00:00:00:00",  # 5 segments
+        "1234567",  # 7 digits
+        "123456789",  # 9 digits
+        "ab:cd:ef:gh",  # non-numeric
+    ],
+)
+def test_write_scene_list_edl_with_start_timecode_invalid_format(tmp_path: Path, bad_value: str):
+    """Malformed start timecodes raise ValueError before writing."""
+    scenes = _fake_scenes(_FPS_CFR, [(0, 30)])
+    with pytest.raises(ValueError):
+        write_scene_list_edl(tmp_path / "scenes.edl", scenes, start_timecode=bad_value)
+
+
+@pytest.mark.parametrize(
+    "bad_value",
+    [
+        "00:60:00:00",  # MM=60
+        "00:00:60:00",  # SS=60
+        "00:00:00:99",  # FF beyond ceil(30 fps)
+    ],
+)
+def test_write_scene_list_edl_with_start_timecode_out_of_range(tmp_path: Path, bad_value: str):
+    """Out-of-range SMPTE components raise ValueError."""
+    scenes = _fake_scenes(_FPS_CFR, [(0, 30)])
+    with pytest.raises(ValueError):
+        write_scene_list_edl(tmp_path / "scenes.edl", scenes, start_timecode=bad_value)
+
+
 def test_write_scene_list_fcpx(tmp_path: Path):
     """FCPXML output declares version 1.9, rational time strings, and an asset-clip per scene."""
     scenes = _fake_scenes(_FPS_NTSC, [(48, 96), (96, 144)])

website/pages/changelog.md

@@ -678,6 +678,7 @@ Although there have been minimal changes to most API examples, there are several
 - [feature] VFR videos are handled correctly by the OpenCV and PyAV backends, and should work correctly with default parameters
 - [feature] New `save-fcp` command allows exporting in Final Cut Pro format (FCP7/FCPX) [#156](https://github.com/Breakthrough/PySceneDetect/issues/156)
 - [feature] `--min-scene-len`/`-m` and `save-images --frame-margin`/`-m` now accept seconds (e.g. `0.6s`) and timecodes (e.g. `00:00:00.600`) in addition to a frame count [#531](https://github.com/Breakthrough/PySceneDetect/issues/531)
+- [feature] `save-edl` accepts a new `--start-timecode`/`-s` flag (SMPTE `HH:MM:SS:FF` or 8-digit `HHMMSSFF`) to stamp every event with a custom start timecode so generated EDLs align with the source media's on-screen timecode [#515](https://github.com/Breakthrough/PySceneDetect/issues/515)
 - [bugfix] Fix floating-point precision error in `save-otio` output where frame values near integer boundaries (e.g. `90.00000000000001`) were serialized with spurious precision
 - [bugfix] Add mitigation for transient `OSError` in the MoviePy backend as it is susceptible to subprocess pipe races on slow or heavily loaded systems [#496](https://github.com/Breakthrough/PySceneDetect/issues/496)
 - [refactor] Remove deprecated `-d`/`--min-delta-hsv` option from `detect-adaptive` command
@@ -687,6 +688,7 @@ Although there have been minimal changes to most API examples, there are several
 **VFR & Timestamp Overhaul:**
 
  * Add `write_scene_list_edl`, `write_scene_list_fcpx`, `write_scene_list_fcp7`, and `write_scene_list_otio` to the `scenedetect.output` module so `save-edl`, `save-fcp`, and `save-otio` can be invoked directly from Python (previously CLI-only)
+ * `write_scene_list_edl` accepts an optional `start_timecode` parameter (SMPTE `HH:MM:SS:FF` or 8-digit `HHMMSSFF`) that is added to every event's source and record columns [#515](https://github.com/Breakthrough/PySceneDetect/issues/515)
  * Add new `Timecode` type to represent frame timings in terms of the video's source timebase
  * Add `time_base` and `pts` properties to `FrameTimecode` for more accurate timing information
  * All backends (PyAV, OpenCV, MoviePy) now return PTS-backed timestamps from `VideoStream.position`