ffmpeg-skill 3.1.5 → 3.1.7

package/scripts/_common/fonts.py

@@ -61,6 +61,13 @@ def resolve_font(font_name: str) -> "Dict[str, object]":
         # common CJK system fonts when the request looks CJK (so Japanese text does not render as
         # boxes in Arial), and Arial only as the last resort.
         wanted = _family_key(font_name)
+        # The family's own file first, from the table of what Windows installs under which file
+        # name (#414): "Malgun Gothic" is malgun.ttf and "Times New Roman" times.ttf, which no
+        # file-name prefix finds -- the prefix rule resolved them to YuGothM.ttc and arial.ttf and
+        # reported a font that is installed as substituted.
+        for name in windows_family_files(wanted):
+            if (fonts / name).is_file():
+                return {"file": str(fonts / name), "family": font_name, "substituted": False, "via": "windows_fonts"}
         try:
             files = sorted(fonts.iterdir()) if fonts.is_dir() else []
         except OSError:
@@ -199,6 +206,25 @@ WINDOWS_FONTS = {
 }
 
 
+# Latin families Windows installs that WINDOWS_FONTS (a per-script table) does not name, by the
+# file each one is installed as: a file name that does not start with the family's name
+WINDOWS_LATIN_FONTS = [("arial.ttf", "Arial"), ("times.ttf", "Times New Roman"), ("cour.ttf", "Courier New"),
+                       ("segoeui.ttf", "Segoe UI"), ("tahoma.ttf", "Tahoma"), ("verdana.ttf", "Verdana"),
+                       ("georgia.ttf", "Georgia"), ("calibri.ttf", "Calibri"), ("cambria.ttc", "Cambria"),
+                       ("consola.ttf", "Consolas"), ("trebuc.ttf", "Trebuchet MS"), ("comic.ttf", "Comic Sans MS"),
+                       ("impact.ttf", "Impact"), ("seguiemj.ttf", "Segoe UI Emoji")]
+
+
+def windows_family_files(wanted_key: str) -> "List[str]":
+    """The Windows Fonts file names of the family whose _family_key() is `wanted_key`, best first,
+    from WINDOWS_FONTS and WINDOWS_LATIN_FONTS ([] for a family neither names)."""
+    out: "List[str]" = []
+    for name, family in [e for entries in WINDOWS_FONTS.values() for e in entries] + WINDOWS_LATIN_FONTS:
+        if wanted_key and _family_key(family) == wanted_key and name not in out:
+            out.append(name)
+    return out
+
+
 _SCRIPT_RANGES = (
     ("ko", ((0x1100, 0x11FF), (0x3130, 0x318F), (0xA960, 0xA97F), (0xAC00, 0xD7FF))),   # Hangul syllables + Jamo
     ("kana", ((0x3040, 0x309F), (0x30A0, 0x30FF), (0x31F0, 0x31FF), (0xFF66, 0xFF9F))),  # hiragana/katakana

package/scripts/_common/probe.py

@@ -38,7 +38,8 @@ def decode_pcm_mono(path: str, sample_rate: int, seconds: Optional[float] = None
                     *, check: bool = True) -> List[float]:
     """Decode (part of) a file's audio to mono float samples in [-1, 1) at `sample_rate` via a
     single ffmpeg pass under --timeout. Shared by scenes.py (audio envelope for cut scoring) and
-    sync.py (cross-correlation); an undecodable input is kind ffmpeg when check=True, else []."""
+    sync.py (cross-correlation); an undecodable input is kind ffmpeg when check=True, else [].
+    The samples are on the file's clock: a sound that starts late is padded at its head."""
     ffmpeg = require_tool("ffmpeg")
     cmd = [ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin"]
     if start:
@@ -46,7 +47,10 @@ def decode_pcm_mono(path: str, sample_rate: int, seconds: Optional[float] = None
     cmd += ["-i", path]
     if seconds is not None:
         cmd += ["-t", f"{seconds:.3f}"]
-    cmd += ["-vn", "-ac", "1", "-ar", str(sample_rate), "-f", "s16le", "-"]
+    # first_pts=0 pads a sound that starts after the file's start (or after `start`) with silence,
+    # so sample i is at start + i / sample_rate on the file's clock: sync.py measured a track that
+    # starts 0.3 s late 0.279 s off, and --replace-audio placed it that far late (#409)
+    cmd += ["-vn", "-af", "aresample=async=1:first_pts=0", "-ac", "1", "-ar", str(sample_rate), "-f", "s16le", "-"]
     proc = run_analysis(cmd, check=False, text=False)
     if proc.returncode != 0 or not proc.stdout:
         if check:
@@ -142,23 +146,40 @@ def _tag(entry: Dict[str, Any], key: str) -> Optional[str]:
     return next((v for k, v in (entry.get("tags") or {}).items() if k.lower() == key), None)
 
 
+def _nominal_fps(video: Optional[Dict[str, Any]]) -> Optional[int]:
+    """The integer timecode rate of the picture (30 for 29.97), from avg_frame_rate, else
+    r_frame_rate: the order probe()'s `fps` uses, which the timeline export validates against."""
+    for key in ("avg_frame_rate", "r_frame_rate"):
+        try:
+            num, _, den = str((video or {}).get(key) or "").partition("/")
+            rate = float(num) / float(den or 1)
+        except (ValueError, ZeroDivisionError):
+            continue
+        if 0 < rate <= 240:
+            return int(round(rate))
+    return None
+
+
 def start_timecode(streams: List[Dict[str, Any]], fmt: Dict[str, Any],
                    video: Optional[Dict[str, Any]]) -> Dict[str, Any]:
     """The first well-formed `timecode` tag, from the video stream, then a `tmcd` data stream,
     then the container: {value, drop_frame, source}. `drop_frame` is the `;` (or `.`) separator
     before the frames field; `source` is `stream:<ffprobe index>` or `format`. None when no
-    source carries one (all three null). A tag that is not HH:MM:SS[:;.]FF is skipped, not
-    repaired."""
+    source carries one (all three null). A tag that is not HH:MM:SS[:;.]FF, or whose frames field
+    the picture's rate cannot reach, is skipped, not repaired."""
     candidates = []
     if video is not None:
         candidates.append((video, f"stream:{video.get('index')}"))
     candidates += [(s, f"stream:{s.get('index')}") for s in streams
                    if s.get("codec_type") == "data" and str(s.get("codec_tag_string", "")).lower() == "tmcd"]
     candidates.append((fmt, "format"))
+    nominal = _nominal_fps(video)
     for entry, source in candidates:
         value = _tag(entry, "timecode")
         m = _TIMECODE.match(value.strip()) if isinstance(value, str) else None
-        if m:
+        # a frames field the picture's rate cannot reach (frame 29 at 25 fps) is no timecode
+        # either: the next candidate (a tmcd track's own tag) may still hold a real one (#427)
+        if m and not (nominal and int(m.group(5)) >= nominal):
             return {"value": value.strip(), "drop_frame": m.group(4) in ";.", "source": source}
     return {"value": None, "drop_frame": None, "source": None}
 
@@ -284,6 +305,12 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
                 rotation = int(video["tags"]["rotate"])
             except ValueError:
                 pass
+        if not rotation and _is_still(fmt, video):
+            # an EXIF Orientation reaches ffmpeg as the decoded frame's display matrix, not as
+            # stream side data, so -show_streams has no rotation for a phone's portrait JPEG;
+            # ffmpeg still turns the picture upright on decode, and every tool that sizes the
+            # frame has to know it did (#411)
+            rotation = _still_rotation(path)
         pix = video.get("pix_fmt") or ""
         trc = video.get("color_transfer") or ""
         prim = video.get("color_primaries") or ""
@@ -301,6 +328,10 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
             "width": w,
             "height": h,
             "display_aspect": video.get("display_aspect_ratio") or _aspect_string(w, h),
+            # the stored pixel's shape (DV, HDV 1440x1080, DVD and XDCAM store non-square pixels);
+            # every tool that sizes or draws on the picture works on square pixels at the display
+            # aspect (square_pixels() / display_size() below)
+            "sample_aspect_ratio": _sar_string(video.get("sample_aspect_ratio")),
             "fps": round(fps, 3) if fps else None,
             "r_frame_rate": video.get("r_frame_rate"),
             "avg_frame_rate": video.get("avg_frame_rate"),
@@ -369,6 +400,8 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
     if role == "input" and getattr(STATE, "first_input", None) is None:
         STATE.first_input = (path, len(out.get("audio_streams") or []),
                              (out.get("video") or {}).get("hdr10_static"))
+    if role == "input" and out["timecode"].get("value") and getattr(STATE, "source_timecode", None) is None:
+        STATE.source_timecode = (out["timecode"]["value"], duration)
     return out
 
 
@@ -658,6 +691,83 @@ def _fraction(v: Optional[str]) -> Optional[Fraction]:
         return None
 
 
+def _sar_string(v: Optional[str]) -> str:
+    """ffprobe's sample_aspect_ratio as "N:D", "1:1" when unset (0:1, N/A, missing)."""
+    f = _fraction((v or "").replace(":", "/"))
+    return f"{f.numerator}:{f.denominator}" if f else "1:1"
+
+
+def pixel_aspect(video: Optional[Dict[str, Any]]) -> Fraction:
+    """The stored pixel's width over its height (the SAR); 1 when the stream does not say."""
+    return _fraction(str((video or {}).get("sample_aspect_ratio") or "").replace(":", "/")) or Fraction(1)
+
+
+def _square_size(video: Optional[Dict[str, Any]]) -> "Tuple[int, int, Fraction]":
+    """(width, height, SAR) of the frame the filter graph receives: rotation applied (ffmpeg
+    autorotates on decode, and its transpose turns the SAR over too), pixels not yet squared."""
+    video = video or {}
+    w, h = int(video.get("width") or 0), int(video.get("height") or 0)
+    sar = pixel_aspect(video)
+    if video.get("rotation") in (90, -90, 270, -270):
+        w, h, sar = h, w, 1 / sar
+    return w, h, sar
+
+
+def display_size(video: Optional[Dict[str, Any]]) -> "Tuple[int, int]":
+    """The displayed frame in square pixels: rotation applied, and a non-square-pixel picture
+    widened or narrowed to its display aspect at its own height (1440x1080 at 4:3 is 1920x1080,
+    720x480 at 8:9 is 640x480). It is the frame square_pixels() hands the rest of a graph, so a
+    tool sizes, places and draws in it. 0x0 when unknown (a dry run's pending input)."""
+    w, h, sar = _square_size(video)
+    if w and h and sar != 1:
+        w = max(2, int(round(w * sar / 2)) * 2)
+    return w, h
+
+
+def square_pixels(video: Optional[Dict[str, Any]]) -> str:
+    """The filter that makes a non-square-pixel picture square at its display aspect
+    ("scale=640:360,setsar=1"), or "" when the pixels are square already. A tool that scales,
+    crops, places or draws starts its video chain with it, so every such tool agrees on one
+    frame (display_size()) and nothing is squashed or drawn stretched (#411). Tools that only
+    re-encode keep the stored size and its SAR, which the encoder writes through."""
+    w, h, sar = _square_size(video)
+    if not (w and h) or sar == 1:
+        return ""
+    dw, dh = display_size(video)
+    return f"scale={dw}:{dh},setsar=1"
+
+
+def square_pixels_note(video: Optional[Dict[str, Any]], what: str = "the input") -> Optional[str]:
+    """The notes line for a square_pixels() scale, or None when there is none."""
+    if not square_pixels(video):
+        return None
+    w, h, _ = _square_size(video)
+    dw, dh = display_size(video)
+    return (f"{what} stores non-square pixels (SAR {(video or {}).get('sample_aspect_ratio')}): "
+            f"its {w}x{h} picture was scaled to {dw}x{dh} square pixels, its display aspect")
+
+
+def _is_still(fmt: Dict[str, Any], video: Dict[str, Any]) -> bool:
+    """A single picture read by an image demuxer (image2, jpeg_pipe, png_pipe, ...)."""
+    name = fmt.get("format_name") or ""
+    return name == "image2" or name.endswith("_pipe")
+
+
+def _still_rotation(path: str) -> int:
+    """The display rotation of a still's first decoded frame (an EXIF Orientation), 0 if none."""
+    proc = run([require_tool("ffprobe"), "-v", "error", *still_input_args(path), "-select_streams", "v:0",
+                "-read_intervals", "%+#1", "-show_entries", "frame_side_data=rotation", "-of", "json", path],
+               quiet=True, check=False)
+    try:
+        frames = json.loads(proc.stdout or "{}").get("frames") or []
+        for sd in (frames[0].get("side_data_list") or []) if frames else []:
+            if "rotation" in sd:
+                return int(round(float(sd["rotation"])))
+    except (ValueError, TypeError, AttributeError):
+        pass
+    return 0
+
+
 def _aspect_string(w: Optional[int], h: Optional[int]) -> Optional[str]:
     if not w or not h:
         return None

package/scripts/_common/runner.py

@@ -324,7 +324,8 @@ class Context:
 
     __slots__ = ("dry_run", "json", "json_brief", "progress", "fast", "duration_hint", "commands", "timeout", "overwrite", "written", "preexisting", "plan", "plan_written", "plan_inputs", "codec",
                  "hw", "hw_source", "hw_notes", "hw_swaps", "hw_fallback", "hw_env_ignored", "hw_stages", "hw_auto",
-                 "notes", "warnings", "fallbacks", "skipped", "audit_log", "stage_verification", "first_input", "audio_inputs", "video_inputs")
+                 "notes", "warnings", "fallbacks", "skipped", "audit_log", "stage_verification", "first_input", "audio_inputs", "video_inputs",
+                 "source_timecode", "smpte_hint")
 
     def __init__(self) -> None:
         self.reset()
@@ -334,6 +335,8 @@ class Context:
         self.json = False         # emit() prints a JSON document instead of the output path
         self.first_input = None   # (path, audio track count) of the first input probed: emit() reports tracks the output left out
         self.video_inputs = set()  # real paths of the inputs probed that have a picture: with two or more, which one the output shows is the tool's choice (sync --trim-second, a join)
+        self.source_timecode = None  # (start timecode, duration) of the first input probed that carries one (time_arg's SMPTE hint)
+        self.smpte_hint = None    # what die() says when an hh:mm:ss:ff flag read past the end looks like a source timecode (#411)
         self.audio_inputs = set()  # real paths of the inputs probed that have sound: with two or more, whose tracks an output should keep is the tool's choice (grid --audio-from, a mix)
         self.json_brief = False   # --json-brief: the same document trimmed to the fields a caller acts on
         self.progress = False     # run() streams percent / ETA to stderr for ffmpeg
@@ -1483,6 +1486,40 @@ def _has_non_av_streams(cmd: Sequence[str]) -> bool:
     return not kinds or bool(kinds & {"subtitle", "data", "attachment"})
 
 
+# eia_608 (a QuickTime c608 caption track) decodes to text, so it converts like one (ffmpeg 6.1)
+TEXT_SUBTITLES = frozenset({"mov_text", "subrip", "srt", "ass", "ssa", "webvtt", "text", "eia_608"})
+MP4_FAMILY = frozenset({"mp4", "m4v", "mov"})
+
+
+def subtitle_codec_for(codec: str, out_ext: str) -> str:
+    """The -c:s for one source subtitle stream going into a container with extension `out_ext`
+    (no dot): copy when the container holds it as it is, else the container's own text format --
+    mov_text in MPEG-4, srt in Matroska for a mov_text track, webvtt in WebM. A bitmap track is
+    returned as copy; subtitle_container_holds() says whether that copy can work."""
+    out_ext = out_ext.lstrip(".").lower()
+    if out_ext == "mov" and codec == "eia_608":
+        return "copy"  # QuickTime holds a c608 track as it is; .mp4 has no tag for it
+    if out_ext in MP4_FAMILY and codec in TEXT_SUBTITLES and codec != "mov_text":
+        return "mov_text"
+    if out_ext == "mkv" and codec == "mov_text":
+        return "srt"
+    if out_ext == "webm" and codec in TEXT_SUBTITLES and codec != "webvtt":
+        return "webvtt"
+    return "copy"
+
+
+def subtitle_container_holds(codec: str, out_ext: str) -> bool:
+    """Whether a subtitle stream of `codec` can be written to an `out_ext` container at all,
+    converted by subtitle_codec_for() where it must be: Matroska takes any, MPEG-4 a text track or
+    DVD bitmaps, WebM only text (as WebVTT)."""
+    out_ext = out_ext.lstrip(".").lower()
+    if out_ext in MP4_FAMILY:
+        return codec in TEXT_SUBTITLES or codec == "dvd_subtitle"
+    if out_ext == "webm":
+        return codec in TEXT_SUBTITLES
+    return True
+
+
 def run_keeping_subtitles(cmd: List[str], output: str) -> bool:
     """Run an ffmpeg command that already maps its video/audio, trying first to also
     stream-copy any subtitle/data streams the source has (`-map 0:s?`/`0:d?` are no-ops when

package/scripts/_common/timeline.py

@@ -23,6 +23,7 @@ under `not_exported`, never silently dropped.
 import json
 import math
 import os
+import re
 from fractions import Fraction
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
@@ -30,6 +31,7 @@ from xml.sax.saxutils import escape as _xml_escape
 
 from _common.decision import MissingFpsError, aspect_ratio, frame_size, parse_time
 from _common.emit import warn
+from _common.probe import display_size
 
 FORMATS = {".edl": "edl", ".fcpxml": "fcpxml", ".otio": "otio"}
 # Common NTSC rates are stored as the exact ratio an editor expects, not as 29.97.
@@ -101,12 +103,54 @@ def _seconds(value: Any, what: str, fps: Optional[float]) -> float:
 
 
 def _picture(meta: Dict[str, Any]) -> Optional[Tuple[int, int]]:
-    """A source's displayed width x height (rotation metadata swaps them, as fit.py reads it)."""
-    video = meta.get("video") or {}
-    w, h = int(video.get("width") or 0), int(video.get("height") or 0)
+    """A source's displayed width x height, as fit.py reads it: rotation metadata swaps them, and
+    non-square pixels are squared at the display aspect (probe.display_size(), #411)."""
+    w, h = display_size(meta.get("video") or {})
     if not (w and h):
         return None
-    return (h, w) if video.get("rotation") in (90, -90, 270, -270) else (w, h)
+    return (w, h)
+
+
+_TC = re.compile(r"^(\d{2}):(\d{2}):(\d{2})[:;.](\d{2,3})$")
+
+
+def _drop_frame(drop: Optional[bool], rate: Fraction) -> bool:
+    """Drop-frame counting applies to the NTSC rates only (29.97 and 59.94)."""
+    return bool(drop) and rate.denominator == 1001 and round(float(rate)) in (30, 60)
+
+
+def start_tc_frames(tc: Dict[str, Any], rate: Fraction) -> int:
+    """A source's start timecode (probe()'s `timecode`: {value, drop_frame}) as a frame count at
+    its own `rate`, drop-frame counted where it is one; 0 when the source has none (#414). A
+    label that does not exist at that rate (frame 29 at 25 fps, or a frame drop-frame counting
+    skips) is read as none, as probe() skips a malformed tag, rather than as a shifted start."""
+    m = _TC.match(str((tc or {}).get("value") or "").strip())
+    if not m:
+        return 0
+    h, mi, se, fr = (int(g) for g in m.groups())
+    nominal = int(round(float(rate)))
+    if mi > 59 or se > 59 or fr >= nominal:
+        return 0
+    frames = ((h * 60 + mi) * 60 + se) * nominal + fr
+    if _drop_frame(tc.get("drop_frame"), rate):
+        if se == 0 and mi % 10 and fr < nominal // 15:
+            return 0
+        minutes = h * 60 + mi
+        frames -= (nominal // 15) * (minutes - minutes // 10)
+    return frames
+
+
+def _tc_label(frames: int, rate: Fraction, drop: bool) -> str:
+    """`frames` as hh:mm:ss:ff at the nominal integer rate; drop-frame (`;`) for an NTSC source
+    whose own timecode is drop-frame, so the label is the one the media itself shows."""
+    nominal = int(round(float(rate)))
+    if not _drop_frame(drop, rate):
+        return _tc(frames, nominal)
+    d = nominal // 15
+    per_10, per_min = nominal * 600 - d * 9, nominal * 60 - d
+    tens, rem = divmod(frames, per_10)
+    frames += d * 9 * tens + (d * ((rem - d) // per_min) if rem > d else 0)
+    return _tc(frames, nominal)[:-3] + ";" + _tc(frames, nominal)[-2:]
 
 
 def build(proj: Dict[str, Any], probes: Dict[str, Dict[str, Any]], rel) -> Dict[str, Any]:
@@ -171,6 +215,14 @@ def build(proj: Dict[str, Any], probes: Dict[str, Dict[str, Any]], rel) -> Dict[
         if start < 0:
             raise TimelineError(f"clips[{i}].in must not be negative, got {c['in']!r}")
         end = _seconds(c["out"], f"clips[{i}].out", clip_fps) if c.get("out") is not None else dur
+        # as cut.py reads them (#414): an in at or past the media's end is refused, an out past it
+        # is the media's end -- the render clamps it there, so the timeline does too, and says so
+        if dur > 0 and start >= dur:
+            raise TimelineError(f"clips[{i}].in ({start:g}s) is at or past the end of {os.path.basename(src)} ({dur:.3f}s)")
+        if dur > 0 and end > dur + 1e-6:
+            notes.append(f"clips[{i}].out ({end:g}s) is past the end of {os.path.basename(src)} ({dur:.3f}s): "
+                         "the clip ends at the media's end, as the render cuts it")
+            end = dur
         if end <= start:
             raise TimelineError(f"clip {i}: out ({end:g}) is not after in ({start:g})")
         speed = _number(c.get("speed") or 1.0, f"clips[{i}].speed")
@@ -181,8 +233,17 @@ def build(proj: Dict[str, Any], probes: Dict[str, Dict[str, Any]], rel) -> Dict[
         if reframe:
             reframed.append(os.path.basename(src))
         src_in, src_out = fr(start), fr(end)
+        # the source's own clock (#414): its frame rate, and its start timecode as a frame count at
+        # that rate. EDL source timecodes are counted at it (a 25 fps clip in a 29.97 sequence has
+        # no frame :29); FCPXML and OTIO start the media at it, so a conform finds the frames.
+        clip_rate = exact_rate(float(clip_fps)) if clip_fps else rate
+        tc = meta.get("timecode") or {}
+        tc_start = start_tc_frames(tc, clip_rate)
         clips.append({"index": i, "src": os.path.abspath(src), "name": os.path.basename(src),
                       "src_in": src_in, "src_out": src_out, "speed": speed,
+                      "in_seconds": Fraction(start).limit_denominator(1000000), "rate": clip_rate,
+                      "tc_start": tc_start, "tc_seconds": Fraction(tc_start) / clip_rate,
+                      "drop_frame": _drop_frame(tc.get("drop_frame"), clip_rate),
                       "length": int(round((src_out - src_in) / speed)),
                       "media_frames": fr(dur), "has_video": bool(meta.get("video")),
                       "has_audio": bool(meta.get("audio")),
@@ -218,12 +279,24 @@ def build(proj: Dict[str, Any], probes: Dict[str, Dict[str, Any]], rel) -> Dict[
     markers: List[Dict[str, Any]] = []
     chapters = proj.get("chapters")
     if isinstance(chapters, list):
+        total_seconds = Fraction(total) / rate
+        previous: Optional[float] = None
         for j, ch in enumerate(chapters):
             # read as render.py's chapters stage reads it (metadata.py): a chapter list carries
-            # no fps, so hh:mm:ss:ff needs its @fps there and here alike
-            at = fr(_seconds(ch.get("at", 0), f"chapters[{j}].at", None))
-            if 0 <= at < total:
-                markers.append({"at": at, "title": str(ch.get("title") or "")})
+            # no fps, so hh:mm:ss:ff needs its @fps there and here alike. What metadata.py refuses
+            # is refused here too, never dropped (#414): a chapter at or past the end, or one that
+            # does not come after the one before it.
+            at_s = _seconds(ch.get("at", 0), f"chapters[{j}].at", None)
+            if at_s < 0:
+                raise TimelineError(f"chapters[{j}].at must not be negative, got {ch.get('at')!r}")
+            if previous is not None and at_s <= previous:
+                raise TimelineError(f"chapters[{j}]: the chapter at {at_s:g}s does not come after the previous one "
+                                    f"at {previous:g}s (metadata.py refuses it too)")
+            if at_s >= total_seconds:
+                raise TimelineError(f"chapters[{j}]: the chapter at {at_s:g}s starts at or after the end of the "
+                                    f"timeline ({float(total_seconds):.3f}s); metadata.py refuses it too")
+            previous = at_s
+            markers.append({"at": min(fr(at_s), total - 1), "title": str(ch.get("title") or "")})
     elif chapters:
         notes.append("chapters given as a file are not exported as markers; write them inline as [{at, title}]")
 
@@ -282,27 +355,38 @@ def to_edl(tl: Dict[str, Any]) -> str:
     ends = starts[1:] + [tl["total"]]
     lines = [f"TITLE: {tl['name']}", "FCM: NON-DROP FRAME", ""]
     n = 0
-    prev_src_end = 0
+    prev_src_end = ""
+    rate = tl["rate"]
+
+    def src_tc(c: Dict[str, Any], seq_frames: int) -> str:
+        """The source timecode `seq_frames` (sequence frames of source media) after the clip's in
+        point: counted at the clip's own rate from its own start timecode (#414)."""
+        own = c.get("rate") or rate
+        seconds = c.get("in_seconds", Fraction(c["src_in"]) / rate) + Fraction(seq_frames) / rate
+        return _tc_label(int(round(seconds * own)) + c.get("tc_start", 0), own, c.get("drop_frame", False))
+
     for i, c in enumerate(clips):
         n += 1
         chan = "B" if c["has_audio"] and c["has_video"] else ("V" if c["has_video"] else "A")
         rec_in, rec_out = hour + starts[i], hour + ends[i]
-        s_in = c["src_in"]
-        s_out = s_in + int(round((ends[i] - starts[i]) * c["speed"]))
+        s_in = src_tc(c, 0)
+        s_out = src_tc(c, int(round((ends[i] - starts[i]) * c["speed"])))
         if i > 0 and d:
-            lines.append(f"{n:03d}  AX       {chan:<5} C        {_tc(prev_src_end, fps_int)} {_tc(prev_src_end, fps_int)} "
+            lines.append(f"{n:03d}  AX       {chan:<5} C        {prev_src_end} {prev_src_end} "
                          f"{_tc(rec_in, fps_int)} {_tc(rec_in, fps_int)}")
-            lines.append(f"{n:03d}  AX       {chan:<5} D    {d:03d} {_tc(s_in, fps_int)} {_tc(s_out, fps_int)} "
+            lines.append(f"{n:03d}  AX       {chan:<5} D    {d:03d} {s_in} {s_out} "
                          f"{_tc(rec_in, fps_int)} {_tc(rec_out, fps_int)}")
             lines.append(f"* FROM CLIP NAME: {clips[i - 1]['name']}")
             lines.append(f"* TO CLIP NAME: {c['name']}")
         else:
-            lines.append(f"{n:03d}  AX       {chan:<5} C        {_tc(s_in, fps_int)} {_tc(s_out, fps_int)} "
+            lines.append(f"{n:03d}  AX       {chan:<5} C        {s_in} {s_out} "
                          f"{_tc(rec_in, fps_int)} {_tc(rec_out, fps_int)}")
             lines.append(f"* FROM CLIP NAME: {c['name']}")
         lines.append(f"* SOURCE FILE: {c['src']}")
         if abs(c["speed"] - 1.0) > 1e-6:
-            lines.append(f"M2   AX       {fps_int * c['speed']:05.1f}                {_tc(s_in, fps_int)}")
+            # the speed in source frames per second, at the rate the source labels are counted in
+            own_fps = int(round(float(c.get("rate") or rate)))
+            lines.append(f"M2   AX       {own_fps * c['speed']:05.1f}                {s_in}")
         lines.append("")
         prev_src_end = s_out
     if tl["music"]:
@@ -325,6 +409,11 @@ def _t(frames: int, rate: Fraction) -> str:
     return f"{value.numerator}s" if value.denominator == 1 else f"{value.numerator}/{value.denominator}s"
 
 
+def _ts(value: Fraction) -> str:
+    """A rational FCPXML time from seconds."""
+    return f"{value.numerator}s" if value.denominator == 1 else f"{value.numerator}/{value.denominator}s"
+
+
 def _url(path: str) -> str:
     # pathlib builds the percent-encoded file:// URL itself (and the drive-letter form on
     # Windows): no network-library import in scripts/, not even for quoting (see the no-fetch test)
@@ -360,12 +449,14 @@ def to_fcpxml(tl: Dict[str, Any]) -> str:
             return seq_fmt
         return fmt(c["picture"][0], c["picture"][1], _t(1, exact_rate(float(c["fps"]))) if c["fps"] else fd)
 
-    def asset(path: str, name: str, frames: int, has_video: bool, has_audio: bool, format_id: str = "") -> str:
+    def asset(path: str, name: str, frames: int, has_video: bool, has_audio: bool, format_id: str = "",
+              start: Fraction = Fraction(0)) -> str:
         if path in ids:
             return ids[path]
         rid = f"r{len(ids) + 1}"
         ids[path] = rid
-        res.append(f'    <asset id="{rid}" name="{q(name)}" start="0s" duration="{_t(frames, rate)}" '
+        # the media starts at its own start timecode (#414): a clip's start is counted from there
+        res.append(f'    <asset id="{rid}" name="{q(name)}" start="{_ts(start)}" duration="{_t(frames, rate)}" '
                    f'hasVideo="{int(has_video)}" hasAudio="{int(has_audio)}"'
                    + (f' format="{format_id}"' if has_video else "") + ' audioSources="1" audioChannels="2">\n'
                    f'      <media-rep kind="original-media" src="{q(_url(path))}"/>\n    </asset>')
@@ -376,7 +467,8 @@ def to_fcpxml(tl: Dict[str, Any]) -> str:
     markers = list(tl["markers"])
     for i, c in enumerate(tl["clips"]):
         cid = clip_fmt(c)
-        rid = asset(c["src"], c["name"], c["media_frames"], c["has_video"], c["has_audio"], cid)
+        base = c.get("tc_seconds", Fraction(0))
+        rid = asset(c["src"], c["name"], c["media_frames"], c["has_video"], c["has_audio"], cid, base)
         if i > 0 and d:
             spine.append(f'        <transition name="Cross Dissolve" offset="{_t(c["record_in"] - c["trim_head"], rate)}" '
                          f'duration="{_t(d, rate)}"/>')
@@ -385,14 +477,15 @@ def to_fcpxml(tl: Dict[str, Any]) -> str:
         if abs(c["speed"] - 1.0) > 1e-6:
             # timeMap maps clip-local time to source time; two linear points give a constant speed
             inner.append("          <timeMap>")
-            inner.append(f'            <timept time="0s" value="{_t(src_start, rate)}" interp="linear"/>')
+            inner.append(f'            <timept time="0s" value="{_ts(base + Fraction(src_start) / rate)}" interp="linear"/>')
             inner.append(f'            <timept time="{_t(c["visible"], rate)}" '
-                         f'value="{_t(src_start + int(round(c["visible"] * c["speed"])), rate)}" interp="linear"/>')
+                         f'value="{_ts(base + Fraction(src_start + int(round(c["visible"] * c["speed"]))) / rate)}" interp="linear"/>')
             inner.append("          </timeMap>")
             start_attr = "0s"
         else:
-            start_attr = _t(src_start, rate)
-        local0 = src_start if abs(c["speed"] - 1.0) <= 1e-6 else 0
+            start_attr = _ts(base + Fraction(src_start) / rate)
+        # the clip's local time: the source's (from its start timecode), or 0 under a timeMap
+        local0 = base + Fraction(src_start) / rate if abs(c["speed"] - 1.0) <= 1e-6 else Fraction(0)
         # the FCPXML 1.10 DTD's order inside an asset-clip: timeMap, then the adjust-* elements
         # (adjust-conform), then anchored items (the music bed), then markers. Anything out of
         # that order does not validate, and Final Cut validates what it imports against that DTD.
@@ -403,13 +496,14 @@ def to_fcpxml(tl: Dict[str, Any]) -> str:
         if i == 0 and tl["music"]:
             m = tl["music"]
             mid = asset(m["src"], m["name"], m["media_frames"], False, True)
-            inner.append(f'          <asset-clip ref="{mid}" lane="-1" offset="{_t(local0, rate)}" name="{q(m["name"])}" '
+            inner.append(f'          <asset-clip ref="{mid}" lane="-1" offset="{_ts(local0)}" name="{q(m["name"])}" '
                          f'start="0s" duration="{_t(m["length"], rate)}" audioRole="music"/>')
         for mk in [m for m in markers if c["record_in"] <= m["at"] < c["record_in"] + c["visible"]]:
-            inner.append(f'          <chapter-marker start="{_t(local0 + mk["at"] - c["record_in"], rate)}" '
+            inner.append(f'          <chapter-marker start="{_ts(local0 + Fraction(mk["at"] - c["record_in"]) / rate)}" '
                          f'duration="{fd}" value="{q(mk["title"])}"/>')
         head = (f'        <asset-clip ref="{rid}" offset="{_t(c["record_in"], rate)}" name="{q(c["name"])}" '
-                f'start="{start_attr}" duration="{_t(c["visible"], rate)}" format="{cid}" tcFormat="NDF"')
+                f'start="{start_attr}" duration="{_t(c["visible"], rate)}" format="{cid}" '
+                f'tcFormat="{"DF" if c.get("drop_frame") else "NDF"}"')
         spine.append(head + (">\n" + "\n".join(inner) + "\n        </asset-clip>" if inner else "/>"))
     out = ['<?xml version="1.0" encoding="UTF-8"?>', "<!DOCTYPE fcpxml>", '<fcpxml version="1.10">',
            "  <resources>", *res, "  </resources>", "  <library>", f'    <event name="{q(tl["name"])}">',
@@ -443,15 +537,17 @@ def to_otio(tl: Dict[str, Any]) -> str:
                           # OTIO: in_offset is the part before the cut, out_offset the part after
                           "in_offset": _rt(c["trim_head"], rate), "out_offset": _rt(tl["clips"][i - 1]["trim_tail"], rate)})
         src_start = c["src_in"] + int(round(c["trim_head"] * c["speed"]))
+        # the media's range starts at its start timecode (#414), in timeline frames
+        base = c.get("tc_seconds", Fraction(0)) * rate
         clip = {"OTIO_SCHEMA": "Clip.2", "name": c["name"], "metadata": {}, "enabled": True,
                 # OTIO's own convention: source_range starts at the media's in point and lasts the
                 # clip's length on the timeline; a LinearTimeWarp says how fast the media runs
                 # through it (core OTIO does not rescale durations by effects).
-                "source_range": _range(src_start, c["visible"], rate),
+                "source_range": _range(base + src_start, c["visible"], rate),
                 "effects": [], "markers": [],
                 "media_references": {"DEFAULT_MEDIA": {
                     "OTIO_SCHEMA": "ExternalReference.1", "name": c["name"], "metadata": {},
-                    "target_url": _url(c["src"]), "available_range": _range(0, c["media_frames"], rate),
+                    "target_url": _url(c["src"]), "available_range": _range(base, c["media_frames"], rate),
                     "available_image_bounds": None}},
                 "active_media_reference_key": "DEFAULT_MEDIA"}
         if abs(c["speed"] - 1.0) > 1e-6: