From 340944738468486dc7d2f1efad776346771137db Mon Sep 17 00:00:00 2001
From: Ark Deliev <ard@tvrain.tv>
Date: Mon, 13 Jul 2026 17:58:05 +0000
Subject: [PATCH 1/5] fix: make write_smil strictly additive, add broken-SMIL
 scanner

Incident 2026-07-13: when a video's SMIL manifest was missing or failed
XML parsing, write_smil created/regenerated it from scratch with a single
<video> node (the one variant we transcribed) and bare codec params. Wowza
then served a one-stream playlist with malformed CODECS="avc1,mp4a",
breaking adaptive playback on production videos.

write_smil now only adds <textstream> entries to an existing, valid,
transcoder-generated SMIL:
- never creates a SMIL when none exists
- never regenerates on parse error
- never adds or modifies <video> nodes
- refuses to proceed if the backup copy fails
- writes atomically (tmp + rename)
- returns bool so callers can tell the update was skipped

scripts/find_broken_smils.py (stdlib-only, run on a host with storage
access) scans the archive and classifies every video:
- BROKEN_HAS_BACKUP: restore from oldest valid .bak (--restore-bak --apply)
- BROKEN_TRANSCRIBER_CREATED / MISSING_SMIL / UNPARSEABLE: written to a
  regen list for the transcoder-side SMIL generator
Tests rewritten to encode the additive-only contract.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GPhtp4PREZcRfm2WXL5NF7
---
 scripts/find_broken_smils.py            | 207 +++++++++++++++++++++
 src/python/tools/archive_transcriber.py | 115 +++++-------
 tests/test_smil_generation.py           | 227 +++++++++++-------------
 3 files changed, 363 insertions(+), 186 deletions(-)
 create mode 100644 scripts/find_broken_smils.py

diff --git a/scripts/find_broken_smils.py b/scripts/find_broken_smils.py
new file mode 100644
index 0000000..2f3f783
--- /dev/null
+++ b/scripts/find_broken_smils.py
@@ -0,0 +1,207 @@
+#!/usr/bin/env python3
+"""Find (and optionally repair) SMIL manifests damaged by the archive transcriber.
+
+Incident 2026-07-13: older versions of archive_transcriber.py created a SMIL
+from scratch when the original was missing, or regenerated it after an XML
+parse error. Such SMILs reference only ONE video variant (the best rendition,
+usually _1080p) instead of all transcoder renditions, carry no NAME, and
+inject malformed CODECS ("avc1,mp4a") into the Wowza playlist — breaking
+adaptive playback.
+
+Fingerprint of a transcriber-created SMIL:
+  - exactly one <video> node in <switch>
+  - that node has <param name="videoCodecId"/audioCodecId"> children
+    (the transcoder's own generator does not write these params)
+
+This script needs only the Python 3 standard library. Run it on a host with
+access to the storage (e.g. prod12):
+
+    # 1. Scan only (writes report + list of SMILs to regenerate; touches nothing)
+    python3 find_broken_smils.py /mnt/vod/srv/storage/transcoded --report smil_report.jsonl
+
+    # 2. Restore originals from the oldest .bak where one exists (dry-run first)
+    python3 find_broken_smils.py /mnt/vod/srv/storage/transcoded --restore-bak
+    python3 find_broken_smils.py /mnt/vod/srv/storage/transcoded --restore-bak --apply
+
+SMILs that are broken and have NO .bak never had an original (the transcoder
+pipeline never wrote one) — they are listed in --regen-list output and must be
+regenerated by the transcoder-side SMIL generator, not by this script.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import subprocess
+import sys
+import xml.etree.ElementTree as ET
+from pathlib import Path
+from typing import Iterator, Optional
+
+
+def iter_paths(root: Path, patterns: list[str]) -> Iterator[Path]:
+    """Yield files under root matching any of the glob patterns (uses find when available)."""
+    try:
+        find_args = ["find", str(root), "-type", "f", "("]
+        for i, pat in enumerate(patterns):
+            if i:
+                find_args.append("-o")
+            find_args += ["-name", pat]
+        find_args.append(")")
+        proc = subprocess.Popen(find_args, stdout=subprocess.PIPE, text=True)
+        assert proc.stdout is not None
+        for line in proc.stdout:
+            yield Path(line.rstrip("\n"))
+        proc.wait()
+    except FileNotFoundError:
+        for pat in patterns:
+            yield from root.rglob(pat)
+
+
+def iter_targets(root: Path) -> Iterator[tuple[str, Path]]:
+    """Yield ("smil", path) for primary SMILs and ("missing", expected_smil_path)
+    for videos that have a 1080p variant but no SMIL at all (e.g. the generator
+    had no write permission when the video was transcoded)."""
+    for p in iter_paths(root, ["*.smil", "*_1080p.mp4"]):
+        if p.name.endswith("_audio.smil"):
+            continue
+        if p.name.endswith(".smil"):
+            yield "smil", p
+        else:
+            expected = p.with_name(p.name.replace("_1080p.mp4", ".smil"))
+            if not expected.exists():
+                yield "missing", expected
+
+
+def classify(smil_path: Path) -> dict:
+    """Classify a single SMIL file. Returns a report record."""
+    record: dict = {"smil": str(smil_path), "verdict": None}
+
+    baks = sorted(smil_path.parent.glob(smil_path.name + ".bak.*"))
+    record["baks"] = [str(b) for b in baks]
+
+    try:
+        tree = ET.parse(smil_path)
+    except ET.ParseError as exc:
+        record["verdict"] = "UNPARSEABLE"
+        record["error"] = str(exc)
+        return record
+
+    switch = tree.getroot().find("body/switch")
+    if switch is None:
+        record["verdict"] = "NO_SWITCH"
+        return record
+
+    videos = switch.findall("video")
+    textstreams = switch.findall("textstream")
+    record["n_videos"] = len(videos)
+    record["n_textstreams"] = len(textstreams)
+    record["textstream_srcs"] = [ts.get("src", "") for ts in textstreams]
+
+    has_codec_params = any(
+        param.get("name") in ("videoCodecId", "audioCodecId") for v in videos for param in v.findall("param")
+    )
+    record["has_codec_params"] = has_codec_params
+
+    missing_subs = [src for src in record["textstream_srcs"] if src and not (smil_path.parent / src).exists()]
+    if missing_subs:
+        record["missing_subtitle_files"] = missing_subs
+
+    if len(videos) == 1 and has_codec_params:
+        record["verdict"] = "BROKEN_TRANSCRIBER_CREATED" if not baks else "BROKEN_HAS_BACKUP"
+    elif len(videos) >= 2:
+        record["verdict"] = "OK_WITH_SUBS" if textstreams else "OK_UNTOUCHED"
+    else:
+        # single video without our fingerprint: possibly a legit single-rendition
+        # asset — flag for manual review rather than auto-repair
+        record["verdict"] = "SINGLE_VIDEO_REVIEW"
+
+    return record
+
+
+def oldest_valid_bak(baks: list[str]) -> Optional[Path]:
+    """Return the oldest backup that parses and contains >=1 video node without our fingerprint."""
+    for bak in sorted(baks):
+        p = Path(bak)
+        try:
+            tree = ET.parse(p)
+        except (ET.ParseError, OSError):
+            continue
+        switch = tree.getroot().find("body/switch")
+        if switch is None:
+            continue
+        videos = switch.findall("video")
+        fingerprint = any(
+            param.get("name") in ("videoCodecId", "audioCodecId") for v in videos for param in v.findall("param")
+        )
+        if videos and not fingerprint:
+            return p
+    return None
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("root", type=Path, help="Archive root, e.g. /mnt/vod/srv/storage/transcoded")
+    parser.add_argument("--report", type=Path, default=Path("smil_report.jsonl"), help="JSONL report output")
+    parser.add_argument(
+        "--regen-list",
+        type=Path,
+        default=Path("smils_to_regenerate.txt"),
+        help="Output list of broken SMILs with no usable backup (regenerate with the transcoder-side generator)",
+    )
+    parser.add_argument("--restore-bak", action="store_true", help="Restore broken SMILs from their oldest valid .bak")
+    parser.add_argument("--apply", action="store_true", help="Actually write changes (default is dry-run)")
+    args = parser.parse_args()
+
+    counts: dict = {}
+    broken_with_bak: list[dict] = []
+    regen_needed: list[str] = []
+    scanned = 0
+
+    with open(args.report, "w", encoding="utf-8") as report:
+        for kind, smil_path in iter_targets(args.root):
+            if kind == "missing":
+                rec = {"smil": str(smil_path), "verdict": "MISSING_SMIL", "baks": []}
+            else:
+                rec = classify(smil_path)
+            scanned += 1
+            counts[rec["verdict"]] = counts.get(rec["verdict"], 0) + 1
+            if rec["verdict"] != "OK_UNTOUCHED":
+                report.write(json.dumps(rec, ensure_ascii=False) + "\n")
+            if rec["verdict"] == "BROKEN_HAS_BACKUP":
+                broken_with_bak.append(rec)
+            elif rec["verdict"] in ("BROKEN_TRANSCRIBER_CREATED", "UNPARSEABLE", "NO_SWITCH", "MISSING_SMIL"):
+                regen_needed.append(rec["smil"])
+            if scanned % 10000 == 0:
+                print(f"scanned {scanned}...", file=sys.stderr)
+
+    args.regen_list.write_text("\n".join(regen_needed) + ("\n" if regen_needed else ""))
+
+    print(f"\nScanned {scanned} SMIL files. Verdicts:")
+    for verdict, n in sorted(counts.items()):
+        print(f"  {n:8d}  {verdict}")
+    print(f"\nReport: {args.report}")
+    print(f"Regeneration list ({len(regen_needed)} files, no usable backup): {args.regen_list}")
+
+    if args.restore_bak:
+        restored = skipped = 0
+        for rec in broken_with_bak:
+            bak = oldest_valid_bak(rec["baks"])
+            if bak is None:
+                regen_needed.append(rec["smil"])
+                skipped += 1
+                continue
+            if args.apply:
+                shutil.copy2(bak, rec["smil"])
+            print(f"{'RESTORED' if args.apply else 'WOULD RESTORE'} {rec['smil']} <- {bak.name}")
+            restored += 1
+        mode = "" if args.apply else " (dry-run, use --apply)"
+        print(f"\nRestore{mode}: {restored} restored, {skipped} had no valid backup (added to regen list)")
+        args.regen_list.write_text("\n".join(regen_needed) + ("\n" if regen_needed else ""))
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/src/python/tools/archive_transcriber.py b/src/python/tools/archive_transcriber.py
index bb9dd95..4f1f167 100644
--- a/src/python/tools/archive_transcriber.py
+++ b/src/python/tools/archive_transcriber.py
@@ -637,95 +637,72 @@ def _get_float(value: Any) -> Optional[float]:
     )
 
 
-def write_smil(job: VideoJob, metadata: VideoMetadata, args: argparse.Namespace) -> None:
+def write_smil(job: VideoJob, metadata: VideoMetadata, args: argparse.Namespace) -> bool:
     """
-    Write or update the SMIL manifest for a video job, ensuring a video element and appropriate textstream entries.
-
-    Creates the SMIL parent directory if needed, makes a one-time backup of an
-    existing SMIL file, parses an existing SMIL (or creates a minimal one),
-    ensures a single <video> element with available metadata attributes, removes
-    previously managed caption <textstream> nodes, and adds new <textstream>
-    entries for subtitles. By default adds a bilingual TTML textstream (if
-    present); if args.vtt_in_smil is true, adds individual Russian and English
-    VTT textstreams instead. When comparing or deduplicating textstream sources
-    the comparison strips an optional "mp4:" prefix; textstream entries are not
-    added if the referenced subtitle file is missing (a warning is emitted). The
-    final SMIL XML is optionally indented and written with an XML declaration.
+    Update an existing SMIL manifest with subtitle textstream entries.
+
+    This function is strictly additive: it NEVER creates a SMIL from scratch
+    and NEVER touches <video> nodes. The multi-bitrate SMIL manifests are
+    owned by the transcoding pipeline; a transcriber-created SMIL would only
+    reference the single variant we transcribed and would break adaptive
+    playback (see incident of 2026-07-13). If the SMIL is missing or does not
+    parse, the update is skipped and False is returned so the operator can
+    fix the source manifest first.
+
+    Makes a timestamped backup of the existing SMIL before modifying it,
+    removes previously managed caption <textstream> nodes, and adds new
+    <textstream> entries for subtitles. By default adds a bilingual TTML
+    textstream (if present); if args.vtt_in_smil is true, adds individual
+    Russian and English VTT textstreams instead. Textstream entries are not
+    added if the referenced subtitle file is missing (a warning is emitted).
 
     Parameters:
         job (VideoJob): Job record containing source video path and target
             artifact paths (smil, ttml, ru_vtt, en_vtt).
-        metadata (VideoMetadata): Probed video metadata used to populate video
-            attributes (bitrate, width, height, codec ids).
+        metadata (VideoMetadata): Probed video metadata (currently unused;
+            kept for call-site compatibility).
         args (argparse.Namespace): Parsed CLI arguments; used flags are at least `vtt_in_smil` and `smil_only`.
-    """
-    job.smil.parent.mkdir(parents=True, exist_ok=True)
 
-    tree: ET.ElementTree[ET.Element] = ET.ElementTree()
-    root: Optional[ET.Element] = None
+    Returns:
+        bool: True if the SMIL was updated, False if the update was skipped.
+    """
+    if not job.smil.exists():
+        LOGGER.warning(
+            "SMIL %s does not exist; skipping subtitle association (the transcoder pipeline owns SMIL creation)",
+            job.smil,
+        )
+        return False
 
     timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
     backup_path = job.smil.with_suffix(job.smil.suffix + f".bak.{timestamp}")
-    if job.smil.exists() and not backup_path.exists():
+    if not backup_path.exists():
         try:
             shutil.copy2(job.smil, backup_path)
             LOGGER.debug("Backed up SMIL %s to %s", job.smil, backup_path)
         except OSError as exc:
             LOGGER.warning("Failed to back up %s to %s: %s", job.smil, backup_path, exc)
+            return False
 
-    if job.smil.exists():
-        try:
-            tree = ET.parse(job.smil)
-            root = tree.getroot()
-        except ET.ParseError as exc:
-            LOGGER.warning("SMIL parse error for %s (%s); regenerating", job.smil, exc)
-
-    if root is None:
-        root = ET.Element("smil")
-        ET.SubElement(root, "head")
-        tree = ET.ElementTree(root)
+    try:
+        tree: ET.ElementTree[ET.Element] = ET.parse(job.smil)
+        root = tree.getroot()
+    except ET.ParseError as exc:
+        LOGGER.error("SMIL parse error for %s (%s); skipping subtitle association", job.smil, exc)
+        return False
 
     body = root.find("body")
     if body is None:
-        body = ET.SubElement(root, "body")
+        LOGGER.error("SMIL %s has no <body>; skipping subtitle association", job.smil)
+        return False
 
     switch = body.find("switch")
     if switch is None:
-        switch = ET.SubElement(body, "switch")
-
-    def ensure_video_node() -> None:
-        if any(child.tag == "video" for child in switch):
-            return
-        video_attrs = {"src": f"mp4:{job.video_path.name}"}
-        if metadata.bitrate:
-            video_attrs["system-bitrate"] = str(metadata.bitrate)
-        if metadata.width:
-            video_attrs["width"] = str(metadata.width)
-        if metadata.height:
-            video_attrs["height"] = str(metadata.height)
-        video_elem = ET.SubElement(switch, "video", video_attrs)
-        if metadata.video_codec_id:
-            ET.SubElement(
-                video_elem,
-                "param",
-                {
-                    "name": "videoCodecId",
-                    "value": metadata.video_codec_id,
-                    "valuetype": "data",
-                },
-            )
-        if metadata.audio_codec_id:
-            ET.SubElement(
-                video_elem,
-                "param",
-                {
-                    "name": "audioCodecId",
-                    "value": metadata.audio_codec_id,
-                    "valuetype": "data",
-                },
-            )
+        LOGGER.error("SMIL %s has no <switch>; skipping subtitle association", job.smil)
+        return False
 
-    ensure_video_node()
+    if not any(child.tag == "video" for child in switch):
+        LOGGER.error("SMIL %s has no <video> entries; skipping subtitle association", job.smil)
+        return False
 
     def ensure_textstream(src: str, language: str) -> None:
         # Textstream sources should NOT have mp4: prefix (unlike video sources)
@@ -807,7 +784,11 @@ def _normalize(value: Optional[str]) -> str:
     if hasattr(ET, "indent"):
         ET.indent(tree, space="  ")  # type: ignore[arg-type]
 
-    tree.write(job.smil, encoding="utf-8", xml_declaration=True)
+    # Write atomically so a crash mid-write can never leave a truncated SMIL
+    tmp_path = job.smil.with_suffix(job.smil.suffix + ".tmp")
+    tree.write(tmp_path, encoding="utf-8", xml_declaration=True)
+    tmp_path.replace(job.smil)
+    return True
 
 
 def discover_video_jobs(
diff --git a/tests/test_smil_generation.py b/tests/test_smil_generation.py
index 4c54cf7..06e1b4c 100644
--- a/tests/test_smil_generation.py
+++ b/tests/test_smil_generation.py
@@ -1,5 +1,11 @@
 #!/usr/bin/env python3
-"""Unit tests for SMIL manifest generation."""
+"""Unit tests for SMIL manifest subtitle association.
+
+write_smil is strictly additive: it only adds <textstream> entries to an
+existing, valid, transcoder-generated SMIL. It must never create a SMIL from
+scratch and never touch <video> nodes (incident of 2026-07-13: transcriber-
+created single-variant SMILs broke adaptive playback in production).
+"""
 
 from __future__ import annotations
 
@@ -22,6 +28,22 @@
     write_smil,
 )
 
+# A realistic transcoder-generated multi-bitrate SMIL (5 renditions)
+TRANSCODER_SMIL = """<?xml version="1.0" encoding="UTF-8"?>
+<smil>
+ <head/>
+ <body>
+  <switch>
+   <video src="mp4:video_1080p.mp4" system-bitrate="4692000" width="1920" height="1080"/>
+   <video src="mp4:video_720p.mp4" system-bitrate="2692000" width="1280" height="720"/>
+   <video src="mp4:video_480p.mp4" system-bitrate="1378000" width="704" height="480"/>
+   <video src="mp4:video_360p.mp4" system-bitrate="584000" width="640" height="360"/>
+   <video src="mp4:video_180p.mp4" system-bitrate="264000" width="320" height="180"/>
+  </switch>
+ </body>
+</smil>
+"""
+
 
 class MockArgs(argparse.Namespace):
     """Mock command-line arguments."""
@@ -42,14 +64,15 @@ def __init__(
 def tmpdir_with_vtts(tmp_path: Path) -> Path:
     (tmp_path / "video.ru.vtt").write_text("WEBVTT\n")
     (tmp_path / "video.en.vtt").write_text("WEBVTT\n")
+    (tmp_path / "video.smil").write_text(TRANSCODER_SMIL)
     return tmp_path
 
 
 @pytest.fixture
 def video_job(tmpdir_with_vtts: Path) -> VideoJob:
     return VideoJob(
-        video_path=tmpdir_with_vtts / "video.ts",
-        normalized_name="video.ts",
+        video_path=tmpdir_with_vtts / "video_1080p.mp4",
+        normalized_name="video.mp4",
         ru_vtt=tmpdir_with_vtts / "video.ru.vtt",
         en_vtt=tmpdir_with_vtts / "video.en.vtt",
         ttml=tmpdir_with_vtts / "video.ttml",
@@ -74,75 +97,84 @@ def args() -> MockArgs:
     return MockArgs(vtt_in_smil=True)
 
 
-@pytest.fixture
-def video_job_missing_vtts(tmp_path: Path) -> VideoJob:
-    return VideoJob(
-        video_path=tmp_path / "video.ts",
-        normalized_name="video.ts",
-        ru_vtt=tmp_path / "video.ru.vtt",
-        en_vtt=tmp_path / "video.en.vtt",
-        ttml=tmp_path / "video.ttml",
-        smil=tmp_path / "video.smil",
-    )
+class TestSMILSubtitleAssociation:
+    """Tests for adding subtitle textstreams to existing SMIL manifests."""
 
+    def test_smil_missing_is_never_created(
+        self, tmp_path: Path, metadata: VideoMetadata, args: MockArgs, caplog: LogCaptureFixture
+    ) -> None:
+        """write_smil must never create a SMIL when none exists."""
+        job = VideoJob(
+            video_path=tmp_path / "video_1080p.mp4",
+            normalized_name="video.mp4",
+            ru_vtt=tmp_path / "video.ru.vtt",
+            en_vtt=tmp_path / "video.en.vtt",
+            ttml=tmp_path / "video.ttml",
+            smil=tmp_path / "video.smil",
+        )
+        (tmp_path / "video.ru.vtt").write_text("WEBVTT\n")
+        (tmp_path / "video.en.vtt").write_text("WEBVTT\n")
 
-class TestSMILGeneration:
-    """Tests for SMIL manifest generation."""
+        with caplog.at_level(logging.WARNING):
+            result = write_smil(job, metadata, args)
 
-    def test_smil_basic_structure(self, video_job: VideoJob, metadata: VideoMetadata, args: MockArgs) -> None:
-        """Test basic SMIL structure generation."""
-        write_smil(video_job, metadata, args)
+        assert result is False
+        assert not job.smil.exists()
+        assert any("does not exist" in r.message for r in caplog.records)
+
+    def test_corrupt_smil_is_never_regenerated(
+        self, video_job: VideoJob, metadata: VideoMetadata, args: MockArgs, caplog: LogCaptureFixture
+    ) -> None:
+        """A SMIL that fails XML parsing must be left untouched."""
+        video_job.smil.write_text("<smil><body><switch>")  # malformed
 
-        # Verify SMIL was created
-        assert video_job.smil.exists()
+        with caplog.at_level(logging.ERROR):
+            result = write_smil(video_job, metadata, args)
 
-        # Parse and validate structure
-        tree = ET.parse(video_job.smil)
-        root = tree.getroot()
+        assert result is False
+        assert video_job.smil.read_text() == "<smil><body><switch>"
 
-        assert root.tag == "smil"
-        assert root.find("head") is not None
-        assert root.find("body") is not None
-        assert root.find("body/switch") is not None
+    def test_smil_without_video_nodes_is_skipped(
+        self, video_job: VideoJob, metadata: VideoMetadata, args: MockArgs
+    ) -> None:
+        """A SMIL with no <video> entries must not be modified."""
+        video_job.smil.write_text("<?xml version='1.0'?><smil><head/><body><switch/></body></smil>")
+        before = video_job.smil.read_text()
 
-    def test_smil_video_element(self, video_job: VideoJob, metadata: VideoMetadata, args: MockArgs) -> None:
-        """Test that SMIL includes video element with metadata."""
-        write_smil(video_job, metadata, args)
+        result = write_smil(video_job, metadata, args)
+
+        assert result is False
+        assert video_job.smil.read_text() == before
+
+    def test_all_video_variants_preserved(self, video_job: VideoJob, metadata: VideoMetadata, args: MockArgs) -> None:
+        """All 5 transcoder renditions must survive the subtitle update, unmodified."""
+        result = write_smil(video_job, metadata, args)
+        assert result is True
 
         tree = ET.parse(video_job.smil)
-        root = tree.getroot()
-        switch = root.find("body/switch")
+        switch = tree.getroot().find("body/switch")
         assert switch is not None
-        video = switch.find("video")
+        videos = switch.findall("video")
 
-        assert video is not None
-        assert video.get("src") == "mp4:video.ts"
-        assert video.get("system-bitrate") == "5000000"
-        assert video.get("width") == "1920"
-        assert video.get("height") == "1080"
+        assert len(videos) == 5
+        srcs = [v.get("src") for v in videos]
+        assert "mp4:video_1080p.mp4" in srcs
+        assert "mp4:video_180p.mp4" in srcs
+        # video nodes must not gain codec params or any children
+        for v in videos:
+            assert len(list(v)) == 0
 
     def test_smil_textstream_elements(self, video_job: VideoJob, metadata: VideoMetadata, args: MockArgs) -> None:
-        """
-        Verify the SMIL contains two subtitle textstream elements
-        (Russian and English) with correct src and language attributes.
-
-        Asserts that exactly two textstream elements appear under body/switch,
-        one with system-language "rus" and one with "eng", and that their src
-        attributes are "video.ru.vtt" and "video.en.vtt" respectively (no
-        "mp4:" prefix).
-        """
+        """Russian and English VTT textstreams are added with correct attributes."""
         write_smil(video_job, metadata, args)
 
         tree = ET.parse(video_job.smil)
-        root = tree.getroot()
-        switch = root.find("body/switch")
+        switch = tree.getroot().find("body/switch")
         assert switch is not None
         textstreams = switch.findall("textstream")
 
-        # Should have two textstreams (Russian and English)
         assert len(textstreams) == 2
 
-        # Check for Russian textstream
         ru_stream = None
         en_stream = None
         for ts in textstreams:
@@ -157,109 +189,66 @@ def test_smil_textstream_elements(self, video_job: VideoJob, metadata: VideoMeta
         assert ru_stream.get("src") == "video.ru.vtt"
         assert en_stream.get("src") == "video.en.vtt"
 
-    def test_smil_update_preserves_structure(
-        self, video_job: VideoJob, metadata: VideoMetadata, args: MockArgs
-    ) -> None:
-        """Test that updating SMIL preserves existing structure."""
-        # Generate SMIL first time
+    def test_smil_update_is_idempotent(self, video_job: VideoJob, metadata: VideoMetadata, args: MockArgs) -> None:
+        """Running write_smil twice must not duplicate any nodes."""
         write_smil(video_job, metadata, args)
         first_content = video_job.smil.read_text()
 
-        # Generate SMIL second time (should update, not duplicate)
         write_smil(video_job, metadata, args)
         second_content = video_job.smil.read_text()
         assert first_content == second_content
 
-        # Parse and count elements
         tree = ET.parse(video_job.smil)
-        root = tree.getroot()
-        switch = root.find("body/switch")
+        switch = tree.getroot().find("body/switch")
         assert switch is not None
-        videos = switch.findall("video")
-        textstreams = switch.findall("textstream")
+        assert len(switch.findall("video")) == 5
+        assert len(switch.findall("textstream")) == 2
 
-        # Should have exactly one video element
-        assert len(videos) == 1
+    def test_backup_created_before_modification(
+        self, video_job: VideoJob, metadata: VideoMetadata, args: MockArgs
+    ) -> None:
+        """A .bak copy of the original SMIL must exist after an update."""
+        original = video_job.smil.read_text()
+        write_smil(video_job, metadata, args)
 
-        # Should have exactly two textstreams (not duplicated)
-        assert len(textstreams) == 2
+        backups = list(video_job.smil.parent.glob("video.smil.bak.*"))
+        assert len(backups) == 1
+        assert backups[0].read_text() == original
 
     def test_smil_missing_vtt_warning(
         self,
-        video_job_missing_vtts: VideoJob,
+        video_job: VideoJob,
         metadata: VideoMetadata,
         args: MockArgs,
         caplog: LogCaptureFixture,
     ) -> None:
-        """Test that SMIL generation handles missing VTT files."""
-        # Should not crash, just skip missing textstreams and emit warnings
+        """Missing subtitle files are skipped with a warning, videos untouched."""
+        video_job.ru_vtt.unlink()
+        video_job.en_vtt.unlink()
+
         with caplog.at_level(logging.WARNING):
-            write_smil(video_job_missing_vtts, metadata, args)
+            write_smil(video_job, metadata, args)
 
-        # Should have emitted a warning about missing VTT
         assert any("vtt" in r.message.lower() for r in caplog.records)
 
-        # SMIL should still be created with video element
-        assert video_job_missing_vtts.smil.exists()
-
-        tree = ET.parse(video_job_missing_vtts.smil)
-        root = tree.getroot()
-        switch = root.find("body/switch")
-        assert switch is not None
-        video = switch.find("video")
-
-        # Video element should exist
-        assert video is not None
-
-        # Textstreams should not exist (files missing)
-        textstreams = switch.findall("textstream")
-
-        # No textstreams should be added for missing files
-        assert len(textstreams) == 0
-
-    def test_smil_codec_params(self, video_job: VideoJob, metadata: VideoMetadata, args: MockArgs) -> None:
-        """Test that video codec parameters are included."""
-        write_smil(video_job, metadata, args)
-
         tree = ET.parse(video_job.smil)
-        root = tree.getroot()
-        switch = root.find("body/switch")
+        switch = tree.getroot().find("body/switch")
         assert switch is not None
-        video = switch.find("video")
-        assert video is not None
-        params = video.findall("param")
-
-        video_codec_param = None
-        audio_codec_param = None
-
-        for param in params:
-            if param.get("name") == "videoCodecId":
-                video_codec_param = param
-            elif param.get("name") == "audioCodecId":
-                audio_codec_param = param
-
-        assert video_codec_param is not None
-        assert video_codec_param.get("value") == "h264"
-
-        assert audio_codec_param is not None
-        assert audio_codec_param.get("value") == "aac"
+        assert len(switch.findall("textstream")) == 0
+        assert len(switch.findall("video")) == 5
 
     def test_smil_ttml_bilingual_language(self, video_job: VideoJob, metadata: VideoMetadata) -> None:
-        """Test that TTML textstream includes both languages in system-language."""
-        # Create TTML file
+        """TTML textstream carries both languages in system-language."""
         video_job.ttml.write_text("<?xml version='1.0' encoding='UTF-8'?><tt></tt>")
 
-        # Use default args (TTML in SMIL, not VTT)
         args = MockArgs(vtt_in_smil=False)
         write_smil(video_job, metadata, args)
 
         tree = ET.parse(video_job.smil)
-        root = tree.getroot()
-        switch = root.find("body/switch")
+        switch = tree.getroot().find("body/switch")
         assert switch is not None
         textstreams = switch.findall("textstream")
 
-        # Find TTML textstream
         ttml_stream = None
         for ts in textstreams:
             if "video.ttml" in ts.get("src", ""):

From 29e60f670b58e24753fa0be458ac033a35852d39 Mon Sep 17 00:00:00 2001
From: Ark Deliev <ard@tvrain.tv>
Date: Mon, 13 Jul 2026 18:40:43 +0000
Subject: [PATCH 2/5] fix: scanner also considers legacy static .smil.bak
 backups

Early versions of write_smil (before timestamped backups) wrote a static
"<name>.smil.bak". The scanner now lists it as the oldest backup so
--restore-bak recovers the pristine original for videos processed by
those runs.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GPhtp4PREZcRfm2WXL5NF7
---
 scripts/find_broken_smils.py | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/scripts/find_broken_smils.py b/scripts/find_broken_smils.py
index 2f3f783..97078d3 100644
--- a/scripts/find_broken_smils.py
+++ b/scripts/find_broken_smils.py
@@ -78,7 +78,10 @@ def classify(smil_path: Path) -> dict:
     """Classify a single SMIL file. Returns a report record."""
     record: dict = {"smil": str(smil_path), "verdict": None}
 
-    baks = sorted(smil_path.parent.glob(smil_path.name + ".bak.*"))
+    # Legacy runs (pre-timestamp) wrote a static "<name>.smil.bak"; it is the
+    # oldest backup where present, so list it first.
+    legacy_bak = smil_path.parent / (smil_path.name + ".bak")
+    baks = ([legacy_bak] if legacy_bak.exists() else []) + sorted(smil_path.parent.glob(smil_path.name + ".bak.*"))
     record["baks"] = [str(b) for b in baks]
 
     try:
@@ -121,8 +124,11 @@ def classify(smil_path: Path) -> dict:
 
 
 def oldest_valid_bak(baks: list[str]) -> Optional[Path]:
-    """Return the oldest backup that parses and contains >=1 video node without our fingerprint."""
-    for bak in sorted(baks):
+    """Return the oldest backup that parses and contains >=1 video node without our fingerprint.
+
+    `baks` is already ordered oldest-first (legacy static .bak, then timestamped).
+    """
+    for bak in baks:
         p = Path(bak)
         try:
             tree = ET.parse(p)

From 985bc095f7f8929ff32641e9ab4b9668e5dccfbb Mon Sep 17 00:00:00 2001
From: Ark Deliev <ard@tvrain.tv>
Date: Tue, 14 Jul 2026 17:23:48 +0000
Subject: [PATCH 3/5] feat: skip videos with missing/invalid SMIL before
 transcription

Pre-flight check requested by the transcoder team: if a video's SMIL is
missing, unparseable, or has no <video> entries, skip the video entirely
(no GPU time spent) and append a manifest record with status="skipped",
error_type="invalid_smil" and the reason. This flags generator failures
while the trail is fresh instead of papering over them, and the video is
retried automatically once a valid SMIL appears.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GPhtp4PREZcRfm2WXL5NF7
---
 src/python/tools/archive_transcriber.py | 66 +++++++++++++++++++++++++
 tests/test_smil_generation.py           | 29 +++++++++++
 2 files changed, 95 insertions(+)

diff --git a/src/python/tools/archive_transcriber.py b/src/python/tools/archive_transcriber.py
index 4f1f167..3b54bad 100644
--- a/src/python/tools/archive_transcriber.py
+++ b/src/python/tools/archive_transcriber.py
@@ -637,6 +637,56 @@ def _get_float(value: Any) -> Optional[float]:
     )
 
 
+def smil_precheck(job: VideoJob) -> Optional[str]:
+    """
+    Validate that the transcoder-generated SMIL exists and is usable BEFORE
+    spending GPU time on a video.
+
+    Videos failing this check are skipped entirely and flagged in the manifest
+    so the missing/corrupt source manifest can be investigated while the trail
+    is fresh (the transcoder pipeline occasionally fails to write the main
+    SMIL; see incident of 2026-07-13).
+
+    Returns:
+        None if the SMIL is valid, otherwise a short reason string.
+    """
+    if not job.smil.exists():
+        return "smil_missing"
+    try:
+        tree = ET.parse(job.smil)
+    except ET.ParseError as exc:
+        return f"smil_unparseable: {exc}"
+    switch = tree.getroot().find("body/switch")
+    if switch is None:
+        return "smil_no_switch"
+    if not switch.findall("video"):
+        return "smil_no_video_nodes"
+    return None
+
+
+def skip_record_for_invalid_smil(job: VideoJob, reason: str, phase: Optional[str] = None) -> ManifestRecord:
+    """Build a manifest record for a video skipped due to a missing/invalid SMIL."""
+    LOGGER.error(
+        "SKIPPING %s: %s — video left untouched; investigate why the transcoder did not produce a valid SMIL",
+        job.video_path,
+        reason,
+    )
+    record: ManifestRecord = {
+        "video_path": str(job.video_path),
+        "ru_vtt": str(job.ru_vtt),
+        "en_vtt": str(job.en_vtt),
+        "ttml": str(job.ttml),
+        "smil": str(job.smil),
+        "status": "skipped",
+        "error": reason,
+        "error_type": "invalid_smil",
+        "processed_at": human_time(),
+    }
+    if phase:
+        record["phase"] = phase
+    return record
+
+
 def write_smil(job: VideoJob, metadata: VideoMetadata, args: argparse.Namespace) -> bool:
     """
     Update an existing SMIL manifest with subtitle textstream entries.
@@ -1242,6 +1292,12 @@ def process_job(job: VideoJob, args: argparse.Namespace, manifest: Manifest) ->
     start_time = time.time()
     LOGGER.info("Processing %s", job.video_path)
 
+    precheck_reason = smil_precheck(job)
+    if precheck_reason:
+        record = skip_record_for_invalid_smil(job, precheck_reason)
+        manifest.append(record)
+        return record
+
     # Load filter words (cached after first call)
     filter_words: List[str] = load_filter_words()
 
@@ -1425,6 +1481,10 @@ def process_transcription_only(job: VideoJob, args: argparse.Namespace, quiet: b
     if not quiet or args.verbose:
         LOGGER.info("[Transcription] Processing %s", job.video_path)
 
+    precheck_reason = smil_precheck(job)
+    if precheck_reason:
+        return skip_record_for_invalid_smil(job, precheck_reason, phase="transcription")
+
     filter_words: List[str] = load_filter_words()
     audio_path: Optional[Path] = None
 
@@ -1501,6 +1561,12 @@ def process_translation_only(
     if not quiet or args.verbose:
         LOGGER.info("[Translation] Processing %s", job.video_path)
 
+    precheck_reason = smil_precheck(job)
+    if precheck_reason:
+        record = skip_record_for_invalid_smil(job, precheck_reason, phase="translation")
+        manifest.append(record)
+        return record
+
     filter_words: List[str] = load_filter_words()
     metadata = probe_video_metadata(job.video_path)
     audio_path: Optional[Path] = None
diff --git a/tests/test_smil_generation.py b/tests/test_smil_generation.py
index 06e1b4c..e722e5f 100644
--- a/tests/test_smil_generation.py
+++ b/tests/test_smil_generation.py
@@ -25,6 +25,8 @@
 from src.python.tools.archive_transcriber import (  # noqa: E402
     VideoJob,
     VideoMetadata,
+    skip_record_for_invalid_smil,
+    smil_precheck,
     write_smil,
 )
 
@@ -237,6 +239,33 @@ def test_smil_missing_vtt_warning(
         assert len(switch.findall("textstream")) == 0
         assert len(switch.findall("video")) == 5
 
+    def test_precheck_passes_on_valid_smil(self, video_job: VideoJob) -> None:
+        """A valid transcoder SMIL passes the pre-flight check."""
+        assert smil_precheck(video_job) is None
+
+    def test_precheck_rejects_missing_smil(self, video_job: VideoJob) -> None:
+        """A missing SMIL fails the pre-flight check so the video is never processed."""
+        video_job.smil.unlink()
+        assert smil_precheck(video_job) == "smil_missing"
+
+    def test_precheck_rejects_unparseable_smil(self, video_job: VideoJob) -> None:
+        video_job.smil.write_text("<smil><body>")
+        reason = smil_precheck(video_job)
+        assert reason is not None and reason.startswith("smil_unparseable")
+
+    def test_precheck_rejects_smil_without_videos(self, video_job: VideoJob) -> None:
+        video_job.smil.write_text("<?xml version='1.0'?><smil><head/><body><switch/></body></smil>")
+        assert smil_precheck(video_job) == "smil_no_video_nodes"
+
+    def test_skip_record_shape(self, video_job: VideoJob) -> None:
+        """The skip record is queryable by status and error_type in the manifest."""
+        record = skip_record_for_invalid_smil(video_job, "smil_missing", phase="transcription")
+        assert record["status"] == "skipped"
+        assert record["error_type"] == "invalid_smil"
+        assert record["error"] == "smil_missing"
+        assert record["phase"] == "transcription"
+        assert record["video_path"] == str(video_job.video_path)
+
     def test_smil_ttml_bilingual_language(self, video_job: VideoJob, metadata: VideoMetadata) -> None:
         """TTML textstream carries both languages in system-language."""
         video_job.ttml.write_text("<?xml version='1.0' encoding='UTF-8'?><tt></tt>")

From 78059a0a7edd014a65d1680f940a7835b0691f3a Mon Sep 17 00:00:00 2001
From: Ark Deliev <ard@tvrain.tv>
Date: Tue, 14 Jul 2026 17:26:03 +0000
Subject: [PATCH 4/5] fix: rename precheck skip variable to satisfy mypy
 no-redef

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GPhtp4PREZcRfm2WXL5NF7
---
 src/python/tools/archive_transcriber.py | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/src/python/tools/archive_transcriber.py b/src/python/tools/archive_transcriber.py
index 3b54bad..7a23ef6 100644
--- a/src/python/tools/archive_transcriber.py
+++ b/src/python/tools/archive_transcriber.py
@@ -1294,9 +1294,9 @@ def process_job(job: VideoJob, args: argparse.Namespace, manifest: Manifest) ->
 
     precheck_reason = smil_precheck(job)
     if precheck_reason:
-        record = skip_record_for_invalid_smil(job, precheck_reason)
-        manifest.append(record)
-        return record
+        skipped = skip_record_for_invalid_smil(job, precheck_reason)
+        manifest.append(skipped)
+        return skipped
 
     # Load filter words (cached after first call)
     filter_words: List[str] = load_filter_words()
@@ -1563,9 +1563,9 @@ def process_translation_only(
 
     precheck_reason = smil_precheck(job)
     if precheck_reason:
-        record = skip_record_for_invalid_smil(job, precheck_reason, phase="translation")
-        manifest.append(record)
-        return record
+        skipped = skip_record_for_invalid_smil(job, precheck_reason, phase="translation")
+        manifest.append(skipped)
+        return skipped
 
     filter_words: List[str] = load_filter_words()
     metadata = probe_video_metadata(job.video_path)

From 800fbc443c096cf06b5b782dc797a5cb6a1d250f Mon Sep 17 00:00:00 2001
From: Ark Deliev <ard@tvrain.tv>
Date: Tue, 14 Jul 2026 21:33:23 +0000
Subject: [PATCH 5/5] fix: address review findings on SMIL handling robustness

- catch OSError alongside ET.ParseError when parsing SMILs (precheck,
  write_smil, scanner classify) so an unreadable file can't crash a run
- write_smil returns False and leaves the SMIL (and no backup) untouched
  when no textstream was actually added
- preserve the original SMIL's permission bits across the atomic replace
- scanner: extract shared has_transcriber_fingerprint helper, survive
  copy2 failures in the restore loop (counted and reported)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GPhtp4PREZcRfm2WXL5NF7
---
 scripts/find_broken_smils.py            | 33 ++++++++++------
 src/python/tools/archive_transcriber.py | 50 ++++++++++++++-----------
 tests/test_smil_generation.py           | 15 ++++----
 3 files changed, 57 insertions(+), 41 deletions(-)

diff --git a/scripts/find_broken_smils.py b/scripts/find_broken_smils.py
index 97078d3..186989e 100644
--- a/scripts/find_broken_smils.py
+++ b/scripts/find_broken_smils.py
@@ -74,6 +74,13 @@ def iter_targets(root: Path) -> Iterator[tuple[str, Path]]:
                 yield "missing", expected
 
 
+def has_transcriber_fingerprint(videos: list[ET.Element]) -> bool:
+    """True if any <video> node carries the codec <param> children only our transcriber wrote."""
+    return any(
+        param.get("name") in ("videoCodecId", "audioCodecId") for v in videos for param in v.findall("param")
+    )
+
+
 def classify(smil_path: Path) -> dict:
     """Classify a single SMIL file. Returns a report record."""
     record: dict = {"smil": str(smil_path), "verdict": None}
@@ -86,7 +93,7 @@ def classify(smil_path: Path) -> dict:
 
     try:
         tree = ET.parse(smil_path)
-    except ET.ParseError as exc:
+    except (ET.ParseError, OSError) as exc:
         record["verdict"] = "UNPARSEABLE"
         record["error"] = str(exc)
         return record
@@ -102,9 +109,7 @@ def classify(smil_path: Path) -> dict:
     record["n_textstreams"] = len(textstreams)
     record["textstream_srcs"] = [ts.get("src", "") for ts in textstreams]
 
-    has_codec_params = any(
-        param.get("name") in ("videoCodecId", "audioCodecId") for v in videos for param in v.findall("param")
-    )
+    has_codec_params = has_transcriber_fingerprint(videos)
     record["has_codec_params"] = has_codec_params
 
     missing_subs = [src for src in record["textstream_srcs"] if src and not (smil_path.parent / src).exists()]
@@ -138,10 +143,7 @@ def oldest_valid_bak(baks: list[str]) -> Optional[Path]:
         if switch is None:
             continue
         videos = switch.findall("video")
-        fingerprint = any(
-            param.get("name") in ("videoCodecId", "audioCodecId") for v in videos for param in v.findall("param")
-        )
-        if videos and not fingerprint:
+        if videos and not has_transcriber_fingerprint(videos):
             return p
     return None
 
@@ -167,6 +169,7 @@ def main() -> int:
 
     with open(args.report, "w", encoding="utf-8") as report:
         for kind, smil_path in iter_targets(args.root):
+            rec: dict
             if kind == "missing":
                 rec = {"smil": str(smil_path), "verdict": "MISSING_SMIL", "baks": []}
             else:
@@ -191,7 +194,7 @@ def main() -> int:
     print(f"Regeneration list ({len(regen_needed)} files, no usable backup): {args.regen_list}")
 
     if args.restore_bak:
-        restored = skipped = 0
+        restored = skipped = failed = 0
         for rec in broken_with_bak:
             bak = oldest_valid_bak(rec["baks"])
             if bak is None:
@@ -199,11 +202,19 @@ def main() -> int:
                 skipped += 1
                 continue
             if args.apply:
-                shutil.copy2(bak, rec["smil"])
+                try:
+                    shutil.copy2(bak, rec["smil"])
+                except OSError as exc:
+                    print(f"FAILED to restore {rec['smil']} <- {bak.name}: {exc}", file=sys.stderr)
+                    failed += 1
+                    continue
             print(f"{'RESTORED' if args.apply else 'WOULD RESTORE'} {rec['smil']} <- {bak.name}")
             restored += 1
         mode = "" if args.apply else " (dry-run, use --apply)"
-        print(f"\nRestore{mode}: {restored} restored, {skipped} had no valid backup (added to regen list)")
+        print(
+            f"\nRestore{mode}: {restored} restored, {failed} failed, "
+            f"{skipped} had no valid backup (added to regen list)"
+        )
         args.regen_list.write_text("\n".join(regen_needed) + ("\n" if regen_needed else ""))
 
     return 0
diff --git a/src/python/tools/archive_transcriber.py b/src/python/tools/archive_transcriber.py
index 7a23ef6..4f06ecb 100644
--- a/src/python/tools/archive_transcriber.py
+++ b/src/python/tools/archive_transcriber.py
@@ -654,7 +654,7 @@ def smil_precheck(job: VideoJob) -> Optional[str]:
         return "smil_missing"
     try:
         tree = ET.parse(job.smil)
-    except ET.ParseError as exc:
+    except (ET.ParseError, OSError) as exc:
         return f"smil_unparseable: {exc}"
     switch = tree.getroot().find("body/switch")
     if switch is None:
@@ -723,20 +723,10 @@ def write_smil(job: VideoJob, metadata: VideoMetadata, args: argparse.Namespace)
         )
         return False
 
-    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
-    backup_path = job.smil.with_suffix(job.smil.suffix + f".bak.{timestamp}")
-    if not backup_path.exists():
-        try:
-            shutil.copy2(job.smil, backup_path)
-            LOGGER.debug("Backed up SMIL %s to %s", job.smil, backup_path)
-        except OSError as exc:
-            LOGGER.warning("Failed to back up %s to %s: %s", job.smil, backup_path, exc)
-            return False
-
     try:
         tree: ET.ElementTree[ET.Element] = ET.parse(job.smil)
         root = tree.getroot()
-    except ET.ParseError as exc:
+    except (ET.ParseError, OSError) as exc:
         LOGGER.error("SMIL parse error for %s (%s); skipping subtitle association", job.smil, exc)
         return False
 
@@ -754,7 +744,7 @@ def write_smil(job: VideoJob, metadata: VideoMetadata, args: argparse.Namespace)
         LOGGER.error("SMIL %s has no <video> entries; skipping subtitle association", job.smil)
         return False
 
-    def ensure_textstream(src: str, language: str) -> None:
+    def ensure_textstream(src: str, language: str) -> bool:
         # Textstream sources should NOT have mp4: prefix (unlike video sources)
         """
         Ensure a textstream entry for a subtitle file exists in the SMIL switch element.
@@ -769,10 +759,8 @@ def ensure_textstream(src: str, language: str) -> None:
                 src (str): Subtitle file path as used in the SMIL `src` attribute.
                 language (str): Language code to set on the `system-language` attribute.
 
-        Notes:
-            This function mutates the surrounding SMIL `switch` element and
-            reads the job's SMIL directory to check for file existence. It
-            does not return a value.
+        Returns:
+            bool: True if a textstream entry was added, False otherwise.
         """
         target_src = src
 
@@ -806,37 +794,55 @@ def _normalize(value: Optional[str]) -> str:
 
         if not Path(job.smil.parent, src).exists():
             LOGGER.warning("Expected subtitle file missing for %s when writing SMIL", src)
-            return
+            return False
         ET.SubElement(switch, "textstream", {"src": target_src, "system-language": language})
+        return True
 
     # By default, use TTML in SMIL (contains both languages)
     # Use --vtt-in-smil flag to include individual VTT files instead
+    added = False
     if args.vtt_in_smil:
         # Include individual VTT files in SMIL
         if job.ru_vtt.exists():
-            ensure_textstream(job.ru_vtt.name, "rus")
+            added |= ensure_textstream(job.ru_vtt.name, "rus")
         elif not args.smil_only:
             LOGGER.warning("Expected Russian VTT missing for %s when writing SMIL", job.ru_vtt)
 
         if job.en_vtt.exists():
-            ensure_textstream(job.en_vtt.name, "eng")
+            added |= ensure_textstream(job.en_vtt.name, "eng")
         elif not args.smil_only:
             LOGGER.warning("Expected English VTT missing for %s when writing SMIL", job.en_vtt)
     else:
         # Use TTML by default (bilingual subtitle file)
         if job.ttml.exists():
             # TTML is bilingual, so we include both languages in system-language
-            ensure_textstream(job.ttml.name, "rus,eng")
+            added |= ensure_textstream(job.ttml.name, "rus,eng")
             LOGGER.debug("Added TTML to SMIL: %s", job.ttml.name)
         elif not args.smil_only:
             LOGGER.warning("Expected TTML file missing for %s when writing SMIL", job.ttml)
 
+    if not added:
+        LOGGER.warning("No subtitle textstreams added for %s; leaving SMIL untouched", job.smil)
+        return False
+
     if hasattr(ET, "indent"):
         ET.indent(tree, space="  ")  # type: ignore[arg-type]
 
-    # Write atomically so a crash mid-write can never leave a truncated SMIL
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    backup_path = job.smil.with_suffix(job.smil.suffix + f".bak.{timestamp}")
+    if not backup_path.exists():
+        try:
+            shutil.copy2(job.smil, backup_path)
+            LOGGER.debug("Backed up SMIL %s to %s", job.smil, backup_path)
+        except OSError as exc:
+            LOGGER.warning("Failed to back up %s to %s: %s", job.smil, backup_path, exc)
+            return False
+
+    # Write atomically so a crash mid-write can never leave a truncated SMIL,
+    # preserving the original file's permission bits
     tmp_path = job.smil.with_suffix(job.smil.suffix + ".tmp")
     tree.write(tmp_path, encoding="utf-8", xml_declaration=True)
+    shutil.copymode(job.smil, tmp_path)
     tmp_path.replace(job.smil)
     return True
 
diff --git a/tests/test_smil_generation.py b/tests/test_smil_generation.py
index e722e5f..5d54b5e 100644
--- a/tests/test_smil_generation.py
+++ b/tests/test_smil_generation.py
@@ -224,20 +224,19 @@ def test_smil_missing_vtt_warning(
         args: MockArgs,
         caplog: LogCaptureFixture,
     ) -> None:
-        """Missing subtitle files are skipped with a warning, videos untouched."""
+        """Missing subtitle files are skipped with a warning; the SMIL is not touched at all."""
         video_job.ru_vtt.unlink()
         video_job.en_vtt.unlink()
+        before = video_job.smil.read_text()
 
         with caplog.at_level(logging.WARNING):
-            write_smil(video_job, metadata, args)
+            result = write_smil(video_job, metadata, args)
 
+        assert result is False
         assert any("vtt" in r.message.lower() for r in caplog.records)
-
-        tree = ET.parse(video_job.smil)
-        switch = tree.getroot().find("body/switch")
-        assert switch is not None
-        assert len(switch.findall("textstream")) == 0
-        assert len(switch.findall("video")) == 5
+        # nothing to add -> no write, no backup
+        assert video_job.smil.read_text() == before
+        assert list(video_job.smil.parent.glob("video.smil.bak*")) == []
 
     def test_precheck_passes_on_valid_smil(self, video_job: VideoJob) -> None:
         """A valid transcoder SMIL passes the pre-flight check."""