ffmpeg-skill 3.6.0 → 3.6.2

package/scripts/_common/emoji.py

@@ -18,9 +18,9 @@ from _common.runner import safe_which as _safe_which
 # separately from detect_script() so a cue's font resolution is still decided by its letters.
 EMOJI_RANGES = (
     (0x1F300, 0x1FAFF),   # symbols & pictographs, supplemental, extended-A
-    (0x1F000, 0x1F0FF),   # mahjong/domino/playing cards
-    (0x2600, 0x27BF),     # misc symbols + dingbats
-    (0x2B00, 0x2BFF),     # misc symbols and arrows
+    (0x1F000, 0x1F0FF),   # mahjong/domino/playing cards (only 🀄 and 🃏 are emoji)
+    (0x2600, 0x27BF),     # misc symbols + dingbats (Emoji_Presentation only: _is_emoji_char)
+    (0x2B00, 0x2BFF),     # misc symbols and arrows (likewise)
     (0xFE0F, 0xFE0F),     # VS16 (emoji presentation selector)
     (0x1F1E6, 0x1F1FF),   # regional indicators (flags)
     (0x20E3, 0x20E3),     # combining enclosing keycap
@@ -52,19 +52,80 @@ _KEYCAP = 0x20E3
 _KEYCAP_BASES = frozenset("0123456789#*")
 
 
+def _cps(*spans) -> "frozenset":
+    out = set()
+    for span in spans:
+        lo, hi = span if isinstance(span, tuple) else (span, span)
+        out.update(range(lo, hi + 1))
+    return frozenset(out)
+
+
+# The text-symbol blocks in EMOJI_RANGES (U+2600-27BF, U+2B00-2BFF, U+1F000-1F0FF) are mostly
+# *text*: ♪ U+266A, ✓ U+2713 and ★ U+2605 are not emoji at all in Unicode's emoji-data.txt, and
+# ♥ U+2665, ✔ U+2714, ☺ U+263A are emoji only when VS16 asks for the picture -- their default
+# presentation is the character, which the caption font draws. Counting the whole block made
+# SDH music notes and check marks "emoji", and `--emoji none` (what macOS and a Linux box
+# without a colour face get under auto) cut them out of the burned text. In those blocks only
+# Emoji_Presentation=Yes characters start a cluster on their own; an Emoji=Yes one does when
+# VS16 or a skin-tone modifier follows it. Pinned from emoji-data.txt (Unicode 15.1); the
+# pictograph planes keep their block rule.
+_EMOJI_PRESENTATION_SYMBOLS = _cps(
+    (0x2614, 0x2615), (0x2648, 0x2653), 0x267F, 0x2693, 0x26A1, (0x26AA, 0x26AB),
+    (0x26BD, 0x26BE), (0x26C4, 0x26C5), 0x26CE, 0x26D4, 0x26EA, (0x26F2, 0x26F3), 0x26F5,
+    0x26FA, 0x26FD, 0x2705, (0x270A, 0x270B), 0x2728, 0x274C, 0x274E, (0x2753, 0x2755), 0x2757,
+    (0x2795, 0x2797), 0x27B0, 0x27BF, (0x2B1B, 0x2B1C), 0x2B50, 0x2B55, 0x1F004, 0x1F0CF)
+_EMOJI_TEXT_DEFAULT_SYMBOLS = _cps(
+    (0x2600, 0x2604), 0x260E, 0x2611, 0x2618, 0x261D, 0x2620, (0x2622, 0x2623), 0x2626, 0x262A,
+    (0x262E, 0x262F), (0x2638, 0x263A), 0x2640, 0x2642, (0x265F, 0x2660), 0x2663,
+    (0x2665, 0x2666), 0x2668, 0x267B, 0x267E, (0x2692, 0x2697), 0x2699, (0x269B, 0x269C),
+    0x26A0, 0x26A7, (0x26B0, 0x26B1), 0x26C8, 0x26CF, 0x26D1, 0x26D3, 0x26E9, (0x26F0, 0x26F1),
+    0x26F4, (0x26F7, 0x26F9), 0x2702, (0x2708, 0x2709), (0x270C, 0x270D), 0x270F, 0x2712, 0x2714,
+    0x2716, 0x271D, 0x2721, (0x2733, 0x2734), 0x2744, 0x2747, (0x2763, 0x2764), 0x27A1,
+    (0x2B05, 0x2B07))
+_SYMBOL_BLOCKS = ((0x2600, 0x27BF), (0x2B00, 0x2BFF), (0x1F000, 0x1F0FF))
+
+
+def _in_symbol_block(cp: int) -> bool:
+    return any(lo <= cp <= hi for lo, hi in _SYMBOL_BLOCKS)
+
+
 def _is_emoji_char(ch: str) -> bool:
+    """Is this character drawn as an emoji with nothing after it? In the text-symbol blocks only
+    the Emoji_Presentation characters are; ♪ ✓ ★ ♥ are text (see _EMOJI_PRESENTATION_SYMBOLS)."""
     cp = ord(ch)
+    if _in_symbol_block(cp):
+        return cp in _EMOJI_PRESENTATION_SYMBOLS
     return any(lo <= cp <= hi for lo, hi in EMOJI_RANGES)
 
 
+def _can_be_emoji(ch: str) -> bool:
+    """Emoji=Yes: an emoji by default, or a text-default symbol VS16 can turn into one (♥ ✔)."""
+    return _is_emoji_char(ch) or ord(ch) in _EMOJI_TEXT_DEFAULT_SYMBOLS
+
+
 def _is_emoji_base(ch: str) -> bool:
     """Can this character START an emoji cluster? Pictographs and regional indicators can;
     the joiners and modifiers (ZWJ, VS16, keycap, skin tone) never can -- they only bind to an
     emoji base that already stands before them. Without this, a ZWJ or a VS16 sitting after an
-    ordinary letter turned that letter into "an emoji" and the PNG route replaced it with a gap."""
+    ordinary letter turned that letter into "an emoji" and the PNG route replaced it with a gap.
+    A text-default symbol (♥ ✔ ☝) is a base only with the VS16 or modifier that follows it:
+    emoji_clusters() checks that, this function answers for the character alone."""
     return ord(ch) not in _EMOJI_TAIL and _is_emoji_char(ch)
 
 
+def _starts_emoji(text: str, i: int) -> bool:
+    """Does an emoji cluster start at text[i]? A default-emoji base does; a text-default symbol
+    does only when VS16 or a skin-tone modifier follows it (♥️, ☝🏽), the sequences Unicode
+    defines as emoji; ♥ alone, and ♪ ✓ ★ always, are characters the font draws."""
+    ch = text[i]
+    if _is_emoji_base(ch):
+        return True
+    if ord(ch) in _EMOJI_TEXT_DEFAULT_SYMBOLS and i + 1 < len(text):
+        nxt = ord(text[i + 1])
+        return nxt == _VS16 or 0x1F3FB <= nxt <= 0x1F3FF
+    return False
+
+
 def emoji_clusters(text: str) -> "List[Tuple[int, str]]":
     """(index in `text`, cluster) for every emoji in it, ZWJ sequences, VS16, keycaps, flag pairs
     and skin-tone modifiers kept together -- 👩‍💻 is one cluster, not three, and 1️⃣ starts at the
@@ -74,7 +135,9 @@ def emoji_clusters(text: str) -> "List[Tuple[int, str]]":
     base (`0-9 # *`) that is actually followed by U+20E3. A ZWJ is glue *inside* a cluster, never
     a starter and never a tail on its own: `क्‍ष` (Hindi ka + virama + ZWJ + ssa) and `abc‍def`
     contain no emoji. A base explicitly marked with U+FE0E (VS15, text presentation) is likewise
-    not an emoji -- the author asked for the character, not the picture.
+    not an emoji -- the author asked for the character, not the picture. A text-default symbol
+    (♥ ✔ ☝) starts one only with the VS16 or skin-tone modifier after it, and a symbol that is
+    not emoji at all (♪ ✓ ★) never does: the caption font draws those.
     """
     out: "List[Tuple[int, str]]" = []
     i = 0
@@ -82,7 +145,7 @@ def emoji_clusters(text: str) -> "List[Tuple[int, str]]":
     while i < n:
         ch = text[i]
         start = i
-        if _is_emoji_base(ch):
+        if _starts_emoji(text, i):
             j = i + 1
             if j < n and ord(text[j]) == _VS15:      # text presentation requested: not an emoji
                 i = j + 1
@@ -104,7 +167,9 @@ def emoji_clusters(text: str) -> "List[Tuple[int, str]]":
             if cp in (_VS16, _KEYCAP) or 0x1F3FB <= cp <= 0x1F3FF:
                 j += 1
                 continue
-            if cp == _ZWJ and j + 1 < n and _is_emoji_base(text[j + 1]):
+            if cp == _ZWJ and j + 1 < n and ord(text[j + 1]) not in _EMOJI_TAIL \
+                    and _can_be_emoji(text[j + 1]):
+                # inside a ZWJ sequence a text-default symbol is emoji glue too: 🏃‍♀ ends in ♀
                 j += 2
                 continue
             if (j == start + 1 and ord(ch) in _EMOJI_REGIONAL and cp in _EMOJI_REGIONAL):
@@ -345,7 +410,7 @@ def resolve_emoji_assets(flag: "Optional[str]" = None, project: "Optional[str]"
 
 
 
-def emoji_filter_chain(plan, base_label, out_label, first_input=1, to_yuv="", base_chain=""):
+def emoji_filter_chain(plan, base_label, out_label, first_input=1, to_yuv="", base_chain="", overlay_opts=""):
     """(chains, inputs) that composite the planned PNGs on top of `base_label`.
 
     `inputs` is a list of argv fragments, each ending in the asset path, to be appended to the
@@ -355,6 +420,8 @@ def emoji_filter_chain(plan, base_label, out_label, first_input=1, to_yuv="", ba
     converted to the BT.709 the output is tagged with instead of by overlay's BT.601 default;
     `base_chain` (label_chain(meta, meta): an untagged source's BT.709 label) goes in front of
     the first overlay, so 7.1+ does not convert the two pictures to one another.
+    `overlay_opts` ends each overlay's options: the caller's overlay_format(meta), so a 10-bit
+    picture is not composited at overlay's 8-bit default.
     """
     overlays = plan.get("overlays") or []
     if not overlays:
@@ -413,6 +480,6 @@ def emoji_filter_chain(plan, base_label, out_label, first_input=1, to_yuv="", ba
         # exactly what shipped first). eof_action=repeat (the default) holds the still for the
         # whole timeline; enable= is what confines it to the cue's window.
         chains.append(f"[{cur}][{label}]overlay=x={x}:y={o['y']}:"
-                      f"enable='between(t,{o['start']:.3f},{o['end']:.3f})'[{nxt}]")
+                      f"enable='between(t,{o['start']:.3f},{o['end']:.3f})'{overlay_opts}[{nxt}]")
         cur = nxt
     return chains, inputs

package/scripts/_common/probe.py

@@ -412,6 +412,7 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
         "creation_time": 1 if any(k.lower() == "creation_time" for k in (fmt.get("tags") or {})) else 0,
         "audio_language": 1 if lang and lang.lower() != "und" else 0,
         "timecode": 1 if out["timecode"].get("value") else 0,
+        "timecode_value": out["timecode"].get("value"),
         "audio_channels": (_to_int(audio.get("channels")) or 0) if audio else 0,
         "has_video": bool(video), "has_audio": bool(audio),
     }
@@ -1281,7 +1282,7 @@ def signatures_match(sigs: list, ext: str) -> bool:
                     return False
             else:
                 codec = str(a.get("codec_name") or "")
-                if not (codec.startswith("pcm_") or codec in IN_BAND_CONFIG or ext in TS_EXTS):
+                if not (codec.startswith("pcm_") or codec in IN_BAND_CONFIG or ext.lower() in TS_EXTS):
                     return False
     return True
 

package/scripts/_common/runner.py

@@ -332,7 +332,7 @@ class Context:
     __slots__ = ("dry_run", "json", "json_brief", "progress", "fast", "duration_hint", "commands", "timeout", "overwrite", "written", "preexisting", "plan", "plan_written", "plan_inputs", "codec", "alpha_line",
                  "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",
-                 "source_timecode", "smpte_hint", "delivered")
+                 "source_timecode", "smpte_hint", "delivered", "expected_timecode")
 
     def __init__(self) -> None:
         self.reset()
@@ -343,6 +343,7 @@ class Context:
         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.expected_timecode = None  # the start timecode a tool that moved the picture's start wrote (timeline.output_timecode_args; "" for none): source_carry compares it
         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.delivered: List[str] = []  # deliverables written before a later step (export --normalize, render's chapters/check): a stop then keeps them (#415)
         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)
@@ -481,6 +482,14 @@ def apply_common(args: "argparse.Namespace") -> None:
     STATE.progress = bool(getattr(args, "progress", False))
     STATE.fast = bool(getattr(args, "fast", False))
     STATE.overwrite = bool(getattr(args, "overwrite", False))
+    if STATE.plan and os.environ.get("FFMPEG_SKILL_READ_ONLY", "") not in ("", "0"):
+        # mcp/server.py runs the tools it annotates readOnlyHint (probe, check, cropdetect) with
+        # this set: a plan is the one file they could write, so it is refused here, after argparse,
+        # whatever spelling of --plan a raw argv used. Refused before the exit hook can write it.
+        plan_path, STATE.plan = STATE.plan, None
+        refuse("input", "read_only_plan_refused",
+               f"--plan {plan_path!r}: this tool runs read-only here (FFMPEG_SKILL_READ_ONLY) and writes no file; "
+               "run it from the command line to write a plan", plan=plan_path)
     if STATE.plan:
         # the plan is a file this run writes itself: the side-file guards apply (#408), so it
         # never replaces an input, the output or an existing file without --overwrite
@@ -775,21 +784,69 @@ _URL_SCHEME = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]+:")
 _URL_SCHEME_POSIX = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*:")
 
 
+def _is_subfile_url(value: str) -> bool:
+    """ffmpeg's url_find_protocol() also opens `subfile,<options>:<url>` through the subfile
+    protocol: the scheme stops at the comma, so the regexes above never see it."""
+    return value.startswith("subfile,") and ":" in value[len("subfile,"):]
+
+
 def looks_like_url(value: str) -> bool:
     """True for a value ffmpeg would open through a protocol rather than as a local file."""
+    if _is_subfile_url(value):
+        return True
     scheme = _URL_SCHEME if os.name == "nt" else _URL_SCHEME_POSIX
     return bool(scheme.match(value)) and not value.startswith("pipe:")
 
 
-_PLAYLIST_SUFFIXES = (".m3u8", ".m3u", ".ffconcat")
+def url_scheme(value: str) -> str:
+    """The protocol name ffmpeg would open `value` through (for a looks_like_url() value)."""
+    return "subfile" if _is_subfile_url(value) else value.split(":", 1)[0].lower()
+
+
+_PLAYLIST_SUFFIXES = (".m3u8", ".m3u", ".ffconcat", ".mpd")
 _PLAYLIST_MAGIC = (b"#EXTM3U", b"ffconcat")
+# ffmpeg probes a text format over the whole probe buffer (up to -probesize, 5,000,000 bytes), not
+# over a fixed prefix, and reads that buffer as a C string, so the scan below stops at the first
+# NUL byte: a real media file has one within its first few bytes, a manifest has none.
+_MANIFEST_SCAN_LIMIT = 5_000_000
+
+
+def _manifest_kind(path: str) -> Optional[str]:
+    """"DASH" or "IMF" when ffmpeg's own probe would read `path` as that manifest, whatever its
+    name: dash_probe() looks for `<MPD` and `dash:profile` or `3GPP:PSS:profile:DASH1`
+    (case-insensitively), imf_probe() for
+    `<CompositionPlaylist` and `ContentTitle>`. Either one names other files, local or remote, that
+    ffmpeg then opens (a DASH BaseURL is followed over HTTP even under -protocol_whitelist file)."""
+    buf = bytearray()
+    try:
+        with open(path, "rb") as fh:
+            while len(buf) < _MANIFEST_SCAN_LIMIT:
+                chunk = fh.read(65536)
+                if not chunk:
+                    break
+                nul = chunk.find(b"\0")
+                if nul >= 0:
+                    buf += chunk[:nul]
+                    break
+                buf += chunk
+    except OSError:
+        return None
+    text = bytes(buf[:_MANIFEST_SCAN_LIMIT])
+    low = text.lower()
+    if b"<mpd" in low and (b"dash:profile" in low or b"3gpp:pss:profile:dash1" in low):
+        return "DASH"
+    if b"<CompositionPlaylist" in text and b"ContentTitle>" in text:
+        return "IMF"
+    return None
 
 
 def _refuse_playlist(value: str) -> None:
-    """Refuse an input that ffmpeg would read as a playlist (HLS .m3u8, an ffconcat list) rather
-    than as media. A playlist names other files by path, so a media file handed to the skill could
-    pull in any file the user can read. The skill's own concat lists pass `-f concat` and are not
-    checked here."""
+    """Refuse an input that ffmpeg would read as a playlist (HLS .m3u8, a DASH .mpd, an IMF
+    composition playlist, an ffconcat list) rather than as media. A playlist names other files by
+    path or URL, so a media file handed to the skill could pull in any file the user can read, or
+    make ffmpeg fetch a URL. HLS and ffconcat are told by name or by their first bytes; DASH and IMF
+    by name or by the content ffmpeg's own probe looks for, anywhere before the first NUL byte. The
+    skill's own concat lists pass `-f concat` and are not checked here."""
     if os.path.exists(value) and not os.path.isfile(value) and not os.path.isdir(value):
         # a FIFO or a device: ffmpeg would block on it or read whatever it streams
         refuse("input", "media_path_not_a_file",
@@ -801,9 +858,14 @@ def _refuse_playlist(value: str) -> None:
                 head = fh.read(16).lstrip(b"\xef\xbb\xbf \t\r\n")
     except OSError:
         pass
+    kind = None
     if value.lower().endswith(_PLAYLIST_SUFFIXES) or head.startswith(_PLAYLIST_MAGIC):
+        kind = "HLS, DASH or ffconcat"
+    elif os.path.isfile(value):
+        kind = _manifest_kind(value)
+    if kind:
         refuse("input", "media_path_is_playlist",
-               f"{value!r} is a playlist (HLS or ffconcat), which ffmpeg would follow to the files it names; "
+               f"{value!r} is a playlist ({kind}), which ffmpeg would follow to the files or URLs it names; "
                "this skill takes media files only. Pass the media file itself", path=value)
 
 
@@ -836,9 +898,9 @@ def _refuse_url_media(cmd: Sequence[str]) -> None:
     for value in values:
         if looks_like_url(value):
             refuse("input", "media_path_is_url",
-                   f"{value!r} would be opened by ffmpeg as a URL ({value.split(':', 1)[0]}:), not as a local file; "
+                   f"{value!r} would be opened by ffmpeg as a URL ({url_scheme(value)}:), not as a local file; "
                    "this skill reads and writes local files only. Pass a plain path (a local name containing "
-                   "a colon works as ./name)", path=value, scheme=value.split(":", 1)[0].lower())
+                   "a colon works as ./name)", path=value, scheme=url_scheme(value))
 
 
 def _check_no_overwrite_input(cmd: Sequence[str]) -> None:
@@ -1176,7 +1238,13 @@ def refuse_existing_outputs(paths: Sequence[str]) -> None:
         if output not in existing:
             existing.append(output)
             facts.append({"path": output, "resolved": real, "size": size, "mtime_ns": mtime_ns})
+    # a file batch.py delivered on an earlier --watch pass, still exactly as it left it, is that
+    # run's own: replaced without --overwrite, per path (anything else existing is still refused)
+    if existing and not STATE.overwrite:
+        keep = [i for i, p in enumerate(existing) if not owned_replaceable(p)]
+        existing, facts = [existing[i] for i in keep], [facts[i] for i in keep]
     if not existing or STATE.overwrite:
+        report_owned_targets(paths)
         return
     hint = "pass --overwrite, or choose another -o path"
     if len(existing) == 1:
@@ -1195,6 +1263,111 @@ def _remember_output(cmd: Sequence[str]) -> None:
         STATE.written.add(os.path.realpath(output))
     except OSError:
         pass
+    report_committed(output)
+
+
+# set only by batch.py for the steps it runs: the path of a JSON file {"replaceable": {real path:
+# owned_identity()}, "report": directory}. "replaceable" is every file that batch process
+# delivered (a --watch loop's earlier passes) as it left it; a step replaces one of those without
+# --overwrite while it is still that file, and nothing else. Each process that passes the output
+# check writes <report>/<pid>.json: {"targets": the paths it was allowed to write, "committed":
+# {real path: owned_identity()} taken when each of them was written (report_committed), so batch
+# learns the side files (an .srt beside the video) it delivered as they were when written, not as
+# they are when the item ends -- an edit made while a later step ran is not adopted.
+OWNED_ENV = "_FFMPEG_SKILL_OWNED"
+_OWNED_CACHE: Dict[str, Dict[str, Any]] = {}
+_OWNED_TARGETS: Dict[str, List[str]] = {}
+_OWNED_COMMITTED: Dict[str, Dict[str, Dict[str, int]]] = {}
+
+
+def owned_identity(path: str) -> "Optional[Dict[str, int]]":
+    """{size, mtime_ns, ino, dev} of a regular file: what tells the file batch.py delivered from
+    one put at the same path since (a replacement with the same size and mtime is a new inode).
+    None when the path is not a regular file."""
+    try:
+        st = os.stat(path)
+    except OSError:
+        return None
+    if not os.path.isfile(path):
+        return None
+    return {"size": st.st_size, "mtime_ns": st.st_mtime_ns, "ino": st.st_ino, "dev": st.st_dev}
+
+
+def _owned_config(config: Optional[str] = None) -> Dict[str, Any]:
+    config = config if config is not None else os.environ.get(OWNED_ENV, "")
+    if not config:
+        return {}
+    if config not in _OWNED_CACHE:
+        try:
+            with open(config, encoding="utf-8") as fh:
+                doc = json.load(fh)
+        except (OSError, ValueError):
+            doc = {}
+        _OWNED_CACHE[config] = doc if isinstance(doc, dict) else {}
+    return _OWNED_CACHE[config]
+
+
+def owned_replaceable(path: str, config: Optional[str] = None) -> bool:
+    """Whether `path` is a file the batch.py process running this step delivered, still with the
+    identity it had then (checked now, at the output check, not when the step was planned)."""
+    replaceable = _owned_config(config).get("replaceable")
+    if not isinstance(replaceable, dict):
+        return False
+    try:
+        real = os.path.realpath(path)
+    except OSError:
+        return False
+    expected = replaceable.get(real)
+    return isinstance(expected, dict) and owned_identity(real) == expected
+
+
+def report_owned_targets(paths: Sequence[Optional[str]], config: Optional[str] = None) -> None:
+    """Under batch.py: record paths this process passed the output check for, in the report
+    directory its config names. Nothing outside batch.py; a report that cannot be written only
+    means the next pass refuses that file as someone else's."""
+    config = config if config is not None else os.environ.get(OWNED_ENV, "")
+    report = _owned_config(config).get("report")
+    if not isinstance(report, str) or not report:
+        return
+    targets = _OWNED_TARGETS.setdefault(config, [])
+    for p in paths:
+        if p:
+            try:
+                real = os.path.realpath(p)
+            except OSError:
+                continue
+            if real not in targets:
+                targets.append(real)
+    _write_owned_report(config, report)
+
+
+def _write_owned_report(config: str, report: str) -> None:
+    doc = {"targets": _OWNED_TARGETS.get(config, []), "committed": _OWNED_COMMITTED.get(config, {})}
+    try:
+        with open(os.path.join(report, f"{os.getpid()}.json"), "w", encoding="utf-8") as fh:
+            json.dump(doc, fh)
+    except OSError:
+        pass
+
+
+def report_committed(path: Optional[str], config: Optional[str] = None) -> None:
+    """Under batch.py: record the identity `path` has right now, just after this process wrote it,
+    if it passed this process's output check. What batch later lets a step replace is that file
+    as it was written; one edited afterwards no longer matches and is refused."""
+    config = config if config is not None else os.environ.get(OWNED_ENV, "")
+    report = _owned_config(config).get("report")
+    if not path or not isinstance(report, str) or not report:
+        return
+    try:
+        real = os.path.realpath(path)
+    except OSError:
+        return
+    if real not in _OWNED_TARGETS.get(config, []):
+        return
+    ident = owned_identity(real)
+    if ident:
+        _OWNED_COMMITTED.setdefault(config, {})[real] = ident
+        _write_owned_report(config, report)
 
 
 def remember_written(*paths: Optional[str]) -> None:
@@ -1207,6 +1380,7 @@ def remember_written(*paths: Optional[str]) -> None:
                 STATE.written.add(os.path.realpath(path))
             except OSError:
                 pass
+            report_committed(path)
 
 
 def _timed_out(cmd: Sequence[str], seconds: float) -> "None":
@@ -1243,10 +1417,73 @@ def _stage_existing_output(cmd: Sequence[str]) -> Tuple[List[str], Optional[str]
         return list(cmd), None, None
     d, base = os.path.split(output)
     stem, ext = os.path.splitext(base)
-    tmp = os.path.join(d, f".{stem}.ffskill-{os.getpid()}{ext}")
+    tmp = reserve_sibling(d, stem, ext)
     return list(cmd[:-1]) + [tmp], output, tmp
 
 
+def _reserve(d: str, stem: str, ext: str, tag: str) -> "Tuple[str, Optional[int]]":
+    """(path, open descriptor) of a hidden sibling created exclusively; (path, None) when the
+    directory refuses the create (the write that follows then fails there)."""
+    flags = os.O_CREAT | os.O_EXCL | os.O_WRONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_BINARY", 0)
+    n = 1
+    while True:
+        path = os.path.join(d, f".{stem}.ffskill-" + (f"{tag}-" if tag else "") + f"{os.getpid()}"
+                            + (f"-{n}" if n > 1 else "") + ext)
+        try:
+            return path, os.open(path, flags, 0o666)
+        except FileExistsError:
+            n += 1
+        except OSError:
+            return path, None
+
+
+def reserve_sibling(d: str, stem: str, ext: str, tag: str = "") -> str:
+    """Create the hidden sibling `.<stem>.ffskill-<pid><ext>` (or `...-<pid>-<n><ext>` when that
+    name is taken) exclusively, and return its path, for ffmpeg to write with -y. O_EXCL never
+    opens an existing entry, a symlink included, so a name planted in the output directory
+    beforehand is never written through. What it cannot stop is someone who may delete files in
+    that directory replacing this one between the create and ffmpeg's open: not possible in a
+    sticky shared directory (/tmp), nor in one only the caller can write. A copy this process makes
+    itself goes through copy_to_sibling(), which writes the descriptor it created."""
+    path, fd = _reserve(d, stem, ext, tag)
+    if fd is None:
+        # fail closed: a name that was not created exclusively is never handed to ffmpeg
+        refuse("input", "output_dir_not_writable", f"cannot create a temporary file in {d or '.'!r}",
+               output=os.path.join(d, stem + ext), directory=d or ".")
+    os.close(fd)
+    return path
+
+
+def copy_to_sibling(src: str, dst: str) -> str:
+    """Copy `src` into a hidden sibling of `dst` created exclusively, through the descriptor that
+    created it (never by reopening the name), and return the sibling's path for os.replace()."""
+    import shutil
+    d, base = os.path.split(dst)
+    stem, ext = os.path.splitext(base)
+    path, fd = _reserve(d, stem, ext, "")
+    if fd is None:
+        raise OSError(f"cannot create a temporary file beside {dst}")
+    try:
+        fout = os.fdopen(fd, "wb")
+    except BaseException:
+        os.close(fd)
+        try:
+            os.remove(path)
+        except OSError:
+            pass
+        raise
+    try:
+        with fout, open(src, "rb") as fin:
+            shutil.copyfileobj(fin, fout, 1 << 20)
+    except BaseException:
+        try:
+            os.remove(path)
+        except OSError:
+            pass
+        raise
+    return path
+
+
 HW_ENV = "FFMPEG_SKILL_HW"
 # set only by render.py/batch.py --hw/--no-hw for the stages they run: "the outer command chose
 # explicitly", so a child resolves $FFMPEG_SKILL_HW as a flag (export.py included), not a default
@@ -1533,13 +1770,14 @@ def child_limit(per_call: Optional[float] = None) -> Optional[float]:
     return (limit * 4 + 60) if limit else None
 
 
-def run_tool(argv: Sequence[str], *, per_call: Optional[float] = None) -> subprocess.CompletedProcess:
+def run_tool(argv: Sequence[str], *, per_call: Optional[float] = None,
+             env: Optional[Dict[str, str]] = None) -> subprocess.CompletedProcess:
     """Run a sibling script (`argv[0]` is the script path) under child_limit(). On overrun the
     child is killed and a CompletedProcess is returned whose stdout is this skill's own failure
     document (kind timeout, exit 124), so callers that parse the child's --json see a timeout
-    exactly as they would from the child itself."""
+    exactly as they would from the child itself. `env` replaces the inherited environment."""
     limit = child_limit(per_call)
-    child = subprocess.Popen([sys.executable] + list(argv), stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, encoding="utf-8", errors="replace")
+    child = subprocess.Popen([sys.executable] + list(argv), stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, encoding="utf-8", errors="replace", env=env)
     _watch(child, [])  # a sibling script removes its own partial output; there is none of ours to clean
     try:
         out, err = child.communicate(timeout=limit)
@@ -1558,6 +1796,20 @@ def run_tool(argv: Sequence[str], *, per_call: Optional[float] = None) -> subpro
         return subprocess.CompletedProcess(list(argv), 124, json.dumps(doc), partial + f"\nerror: {msg}\n")
 
 
+def option_args(flag: str, value: Any) -> List[str]:
+    """One option and its value for a sibling tool's argparse, as [flag, value] -- or as the single
+    token `flag=value` when the value starts with '-'. argparse reads a separate token that starts
+    with '-' (and is not a negative number) as the next option, so overlay text "-50%" was refused
+    as "expected one argument" and a value like "--plan=x" became an option of its own. The joined
+    form is read as the value whatever it holds. `flag` must be a long option: `-o=x` is not."""
+    text = str(value)
+    if text.startswith("-"):
+        if not flag.startswith("--"):
+            raise ValueError(f"option_args: {flag!r} is not a long option")
+        return [f"{flag}={text}"]
+    return [flag, text]
+
+
 def child_args() -> List[str]:
     """The shared flags a tool that runs sibling scripts (render.py, batch.py) forwards to them,
     so one `--timeout`/`--overwrite`/`--fast`/`--dry-run` on the outer command governs every
@@ -1633,7 +1885,7 @@ def subtitle_container_holds(codec: str, out_ext: str) -> bool:
     return True
 
 
-def run_keeping_subtitles(cmd: List[str], output: str) -> bool:
+def run_keeping_subtitles(cmd: List[str], output: str, relabel_timecode: bool = False) -> 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
     there are none). A source whose subtitle codec cannot be copied into the target container
@@ -1645,8 +1897,13 @@ def run_keeping_subtitles(cmd: List[str], output: str) -> bool:
     The retry is recorded with the first attempt's error (`diagnostics.fallbacks`,
     `non_av_streams_dropped`): the caller's `dropped_non_av_streams` says that streams went, the
     record says why, which is the only way to tell a container that cannot hold them from a first
-    attempt that failed for another reason and happened to succeed the second time."""
-    first = run(cmd + ["-map", "0:s?", "-map", "0:d?", "-c:s", "copy", "-c:d", "copy", output], check=False)
+    attempt that failed for another reason and happened to succeed the second time.
+
+    `relabel_timecode`: the command writes its own start timecode (timeline.output_timecode_args),
+    so a source's tmcd data track is not copied -- its label, at the source's rate, would win over
+    the new one; the MOV/MP4 muxer builds the track again from the label."""
+    skip_tmcd = ["-map", "-0:d:m:timecode"] if relabel_timecode else []
+    first = run(cmd + ["-map", "0:s?", "-map", "0:d?"] + skip_tmcd + ["-c:s", "copy", "-c:d", "copy", output], check=False)
     if first.returncode == 0:
         return False
     if classify_ffmpeg_failure(first.stderr or "") or not _has_non_av_streams(cmd):
@@ -1846,7 +2103,6 @@ def place_output(src: str, dst: str, move: bool = False) -> None:
     _check_existing_output(cmd)
     d, base = os.path.split(dst)
     stem, ext = os.path.splitext(base)
-    tmp = os.path.join(d, f".{stem}.ffskill-{os.getpid()}{ext}")
     with _OutputLock(dst):
         if move:
             try:
@@ -1855,14 +2111,16 @@ def place_output(src: str, dst: str, move: bool = False) -> None:
                 return
             except OSError:
                 pass
+        tmp = None
         try:
-            shutil.copyfile(src, tmp)
+            tmp = copy_to_sibling(src, dst)
             os.replace(tmp, dst)
         except OSError as e:
-            try:
-                os.remove(tmp)
-            except OSError:
-                pass
+            if tmp:
+                try:
+                    os.remove(tmp)
+                except OSError:
+                    pass
             die(f"could not place {dst}: {e}", kind="output")
     _remember_output(cmd)
 

package/scripts/_common/timeline.py

@@ -153,6 +153,45 @@ def _tc_label(frames: int, rate: Fraction, drop: bool) -> str:
     return _tc(frames, nominal)[:-3] + ";" + _tc(frames, nominal)[-2:]
 
 
+def output_timecode_args(meta: Dict[str, Any], first_frame: Optional[float], rate: Optional[float] = None) -> List[str]:
+    """The arguments that give an output the start timecode of the source frame it starts on:
+    `first_frame` seconds after the source picture's first frame (negative: a head the tool
+    added), or None to write no start timecode at all (a join, whose later frames no single start
+    label describes). A tool that moves the start of the picture used to write the source's own
+    start timecode unchanged: FFmpeg copies the video stream's `timecode` tag, and the MOV/MP4
+    muxer rebuilds a tmcd track from it, so a cut from 1 s was stamped 01:00:00:00 for frame 30.
+    Both the stream and the container tag are set (Matroska keeps a stale stream tag otherwise;
+    MXF reads the container's). Nothing for a source without a start timecode. The label also
+    goes on STATE.expected_timecode, which source_carry compares the written file with: an
+    MXF, which always writes one, reads 00:00:00:00 when none is wanted and is listed as dropped.
+    `rate` is the frame rate the output is delivered at when the tool changes it (fit --fps, a
+    VFR source conformed to a constant rate), None for the source's own: the source's label is
+    read at the source's rate and the output's is counted at the output's, so 01:00:00:12 at 25
+    fps (0.48 s past the hour) is 01:00:00:24 at 50."""
+    from _common.runner import STATE
+    tc = (meta or {}).get("timecode") or {}
+    fps = ((meta or {}).get("video") or {}).get("fps")
+    if not tc.get("value") or not fps:
+        return []
+    label = ""
+    if first_frame is not None:
+        src_rate = exact_rate(float(fps))
+        out_rate = exact_rate(float(rate)) if rate else src_rate
+        drop = _drop_frame(tc.get("drop_frame"), out_rate)
+        nominal = round(float(out_rate))
+        if nominal >= 1:
+            day = (nominal * 600 - (nominal // 15) * 9) * 144 if drop else nominal * 86400
+            # the source label and the offset to the first frame, both in output frames, rounded
+            # once: 00:00:00:02 at 25 fps plus 0.08 s is 4.8 frames at 30, so frame 5, not 2 + 2
+            pos = (Fraction(start_tc_frames(tc, src_rate)) / src_rate
+                   + Fraction(first_frame).limit_denominator(1000000)) * out_rate
+            label = _tc_label(round(pos) % day, out_rate, drop)
+        # below 1 fps no frame count can name a frame: the label is removed, as when the first
+        # frame is unknown, rather than divide by a zero-length day
+    STATE.expected_timecode = label
+    return ["-metadata:s:v:0", f"timecode={label}", "-metadata", f"timecode={label}"]
+
+
 def build(proj: Dict[str, Any], probes: Dict[str, Dict[str, Any]], rel) -> Dict[str, Any]:
     """The editor-neutral timeline: every time in frames at `rate`.