@oh-story/dsh 0.1.10 → 0.1.12

package/lib/video-recap/skills/video-assemble/scripts/subtitles/track.py

@@ -0,0 +1,324 @@
+"""Strict loader for versioned, output-clock subtitle tracks.
+
+This module intentionally uses only the Python standard library so it can be
+loaded by the independently distributed ``video-assemble`` skill.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+from collections.abc import Mapping
+from decimal import Decimal
+from fractions import Fraction
+from pathlib import Path
+
+
+SCHEMA_VERSION = 1
+
+# Digest keys older tracks declared; they are ignored, never a reason to fail.
+_LEGACY_BINDING_KEYS = frozenset({"sha256", "edit_sha256"})
+_EVIDENCE_KINDS = frozenset(
+    {
+        "human_verified",
+        "word_timestamps",
+        "asr_boundary_calibrated",
+        "legacy_estimate",
+    }
+)
+_CALIBRATION_KINDS = frozenset({"none", "asr_energy", "human_boundary"})
+_WORD_ALIGNMENT_KINDS = frozenset({"none", "asr_words", "human_words"})
+
+
+class SubtitleTrackError(ValueError):
+    """The subtitle track is malformed, stale, or incompatible with its caller."""
+
+
+def _fail(path, message):
+    raise SubtitleTrackError(f"{path}: {message}")
+
+
+def _mapping(value, path):
+    if not isinstance(value, Mapping):
+        _fail(path, "must be an object")
+    return value
+
+
+def _strict_fields(value, *, required, optional=(), path):
+    value = _mapping(value, path)
+    keys = set(value)
+    missing = set(required) - keys
+    unknown = keys - set(required) - set(optional)
+    if missing:
+        _fail(path, f"missing field(s): {', '.join(sorted(missing))}")
+    if unknown:
+        _fail(path, f"unknown field(s): {', '.join(sorted(unknown))}")
+    return value
+
+
+def _integer(value, path, *, minimum=None):
+    if isinstance(value, bool) or not isinstance(value, int):
+        _fail(path, "must be an integer")
+    if minimum is not None and value < minimum:
+        _fail(path, f"must be >= {minimum}")
+    return value
+
+
+def _nonempty_string(value, path):
+    if not isinstance(value, str) or not value.strip():
+        _fail(path, "must be a nonempty string")
+    return value
+
+
+def _local_path(value, path):
+    return str(Path(_nonempty_string(value, path)).resolve())
+
+
+def _seconds_fraction(value, path):
+    if isinstance(value, bool):
+        _fail(path, "duration must be finite and numeric")
+    if isinstance(value, Fraction):
+        result = value
+    elif isinstance(value, Decimal):
+        if not value.is_finite():
+            _fail(path, "duration must be finite")
+        result = Fraction(value)
+    elif isinstance(value, int):
+        result = Fraction(value)
+    elif isinstance(value, float):
+        if not math.isfinite(value):
+            _fail(path, "duration must be finite")
+        result = Fraction(str(value))
+    else:
+        _fail(path, "duration must be an int, float, Decimal, or Fraction")
+    if result < 0:
+        _fail(path, "duration must be nonnegative")
+    return result
+
+
+def _load_document(path_or_mapping):
+    if isinstance(path_or_mapping, Mapping):
+        return path_or_mapping
+    try:
+        path = Path(path_or_mapping)
+    except TypeError as exc:
+        raise SubtitleTrackError("track must be a mapping or filesystem path") from exc
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        raise SubtitleTrackError(f"cannot read subtitle track {path}: {exc}") from exc
+    return _mapping(value, "track")
+
+
+def _validate_picture_binding(binding, expected):
+    binding = _strict_fields(
+        binding, required={"path"}, optional={"edit_plan"} | _LEGACY_BINDING_KEYS,
+        path="bindings.picture",
+    )
+    expected = _mapping(expected, "expected_picture_identity")
+    picture_path = _local_path(binding["path"], "bindings.picture.path")
+    expected_path = _local_path(expected.get("path"), "expected_picture_identity.path")
+    if picture_path != expected_path:
+        _fail("bindings.picture.path", "picture path does not match current picture")
+
+    edit_plan = binding.get("edit_plan")
+    if edit_plan is not None:
+        edit_plan = _local_path(edit_plan, "bindings.picture.edit_plan")
+        if "edit_plan" not in expected:
+            _fail("expected_picture_identity.edit_plan", "edit plan is required by track")
+        expected_edit = _local_path(expected["edit_plan"], "expected_picture_identity.edit_plan")
+        if edit_plan != expected_edit:
+            _fail("bindings.picture.edit_plan", "edit plan does not match current edit")
+    return {"path": picture_path, **({"edit_plan": edit_plan} if edit_plan else {})}
+
+
+_AUDIO_BINDING_FACTS = ("selected_stream", "sample_rate", "packet_count")
+
+
+def _validate_audio_binding(binding, expected):
+    binding = _strict_fields(
+        binding, required=set(_AUDIO_BINDING_FACTS), optional=_LEGACY_BINDING_KEYS,
+        path="bindings.audio",
+    )
+    expected = _mapping(expected, "expected_audio_identity")
+    result = {}
+    for key in _AUDIO_BINDING_FACTS:
+        declared = _integer(binding[key], f"bindings.audio.{key}", minimum=0)
+        actual = _integer(expected.get(key), f"expected_audio_identity.{key}", minimum=0)
+        if declared != actual:
+            _fail(f"bindings.audio.{key}", f"{key} does not match adopted audio")
+        result[key] = declared
+    return result
+
+
+def _validate_evidence(value, cue_path):
+    path = f"{cue_path}.timing_evidence"
+    value = _strict_fields(
+        value,
+        required={"kind", "evidence_refs", "calibration", "word_alignment"},
+        path=path,
+    )
+    kind = _nonempty_string(value["kind"], f"{path}.kind")
+    calibration = _nonempty_string(value["calibration"], f"{path}.calibration")
+    word_alignment = _nonempty_string(
+        value["word_alignment"], f"{path}.word_alignment"
+    )
+    if kind not in _EVIDENCE_KINDS:
+        _fail(path, f"timing_evidence kind is not supported: {kind!r}")
+    if calibration not in _CALIBRATION_KINDS:
+        _fail(path, f"timing_evidence calibration is not supported: {calibration!r}")
+    if word_alignment not in _WORD_ALIGNMENT_KINDS:
+        _fail(path, f"timing_evidence word_alignment is not supported: {word_alignment!r}")
+    refs = value["evidence_refs"]
+    if not isinstance(refs, list):
+        _fail(path, "timing_evidence evidence_refs must be a list")
+    refs = [_nonempty_string(ref, f"{path}.evidence_refs[{index}]") for index, ref in enumerate(refs)]
+
+    valid_shape = {
+        "legacy_estimate": calibration == "none" and word_alignment == "none",
+        "asr_boundary_calibrated": calibration == "asr_energy" and word_alignment == "none",
+        "word_timestamps": calibration in {"none", "asr_energy"} and word_alignment == "asr_words",
+        "human_verified": calibration == "human_boundary" and word_alignment in {"none", "human_words"},
+    }[kind]
+    if not valid_shape:
+        _fail(path, f"timing_evidence fields are inconsistent with kind {kind!r}")
+    if kind != "legacy_estimate" and not refs:
+        _fail(path, f"timing_evidence kind {kind!r} requires evidence_refs")
+    return {
+        "kind": kind,
+        "evidence_refs": refs,
+        "calibration": calibration,
+        "word_alignment": word_alignment,
+    }
+
+
+def load_subtitle_track(
+    path_or_mapping,
+    *,
+    expected_picture_identity,
+    expected_audio_identity,
+    expected_duration_seconds,
+    reject_legacy_estimate=False,
+):
+    """Validate schema v1 and return metadata plus second-based render entries.
+
+    Identity arguments are current facts (paths, stream index, sample rate,
+    packet count) supplied independently by the caller; declarations inside the
+    track are compared against them, never accepted on their own. Cue boundaries
+    and text are validated, not split or corrected.
+    """
+
+    if not isinstance(reject_legacy_estimate, bool):
+        _fail("reject_legacy_estimate", "must be a boolean")
+    track = _strict_fields(
+        _load_document(path_or_mapping),
+        required={"schema_version", "clock", "overlap_policy", "bindings", "cues"},
+        path="track",
+    )
+    if type(track["schema_version"]) is not int or track["schema_version"] != SCHEMA_VERSION:
+        _fail(
+            "schema_version",
+            f"only schema_version {SCHEMA_VERSION} is supported; got {track['schema_version']!r}",
+        )
+    if track["overlap_policy"] != "forbid":
+        _fail("overlap_policy", "schema v1 requires fail-closed value 'forbid'")
+
+    clock = _strict_fields(
+        track["clock"],
+        required={"kind", "timebase", "duration_ticks"},
+        path="clock",
+    )
+    if clock["kind"] != "output":
+        _fail("clock.kind", "schema v1 supports output clock only")
+    timebase = _strict_fields(
+        clock["timebase"], required={"numerator", "denominator"}, path="clock.timebase"
+    )
+    numerator = _integer(timebase["numerator"], "clock.timebase.numerator", minimum=1)
+    denominator = _integer(timebase["denominator"], "clock.timebase.denominator", minimum=1)
+    duration_ticks = _integer(clock["duration_ticks"], "clock.duration_ticks", minimum=0)
+    tick_seconds = Fraction(numerator, denominator)
+    duration = duration_ticks * tick_seconds
+    expected_duration = _seconds_fraction(expected_duration_seconds, "expected_duration_seconds")
+    if duration != expected_duration:
+        _fail(
+            "clock.duration_ticks",
+            f"duration {duration} does not match independently supplied duration {expected_duration}",
+        )
+    try:
+        duration_seconds = float(duration)
+    except OverflowError:
+        _fail("clock.duration_ticks", "duration must be representable as finite renderer seconds")
+    if not math.isfinite(duration_seconds):
+        _fail("clock.duration_ticks", "duration must be representable as finite renderer seconds")
+
+    bindings = _strict_fields(
+        track["bindings"], required={"picture", "audio"}, path="bindings"
+    )
+    picture = _validate_picture_binding(bindings["picture"], expected_picture_identity)
+    audio = _validate_audio_binding(bindings["audio"], expected_audio_identity)
+
+    cues = track["cues"]
+    if not isinstance(cues, list):
+        _fail("cues", "must be a list")
+    entries = []
+    kinds = set()
+    previous_end = 0
+    for index, raw_cue in enumerate(cues):
+        cue_path = f"cues[{index}]"
+        cue = _strict_fields(
+            raw_cue,
+            required={"start_tick", "end_tick", "text", "attribution", "timing_evidence"},
+            path=cue_path,
+        )
+        start_tick = _integer(cue["start_tick"], f"{cue_path}.start_tick", minimum=0)
+        end_tick = _integer(cue["end_tick"], f"{cue_path}.end_tick", minimum=0)
+        if end_tick <= start_tick:
+            _fail(cue_path, "half-open cue requires end_tick > start_tick")
+        if end_tick > duration_ticks:
+            _fail(cue_path, "cue end_tick exceeds output duration")
+        if start_tick < previous_end:
+            _fail(cue_path, "cue is out of order or overlaps the previous cue")
+        previous_end = end_tick
+        text = _nonempty_string(cue["text"], f"{cue_path}.text")
+
+        attribution = _strict_fields(
+            cue["attribution"], required={"kind", "ref"}, path=f"{cue_path}.attribution"
+        )
+        source = _nonempty_string(attribution["kind"], f"{cue_path}.attribution.kind")
+        if source not in {"source", "narration"}:
+            _fail(f"{cue_path}.attribution.kind", "must be 'source' or 'narration'")
+        source_ref = _nonempty_string(attribution["ref"], f"{cue_path}.attribution.ref")
+        evidence = _validate_evidence(cue["timing_evidence"], cue_path)
+        if reject_legacy_estimate and evidence["kind"] == "legacy_estimate":
+            _fail(cue_path, "legacy_estimate is rejected by strict caller policy")
+        start_seconds = float(start_tick * tick_seconds)
+        end_seconds = float(end_tick * tick_seconds)
+        if not (math.isfinite(start_seconds) and math.isfinite(end_seconds)):
+            _fail(cue_path, "cue float projection must be finite")
+        if end_seconds <= start_seconds:
+            _fail(cue_path, "distinct cue ticks collapse in renderer float projection")
+        kinds.add(evidence["kind"])
+        entries.append(
+            {
+                "start": start_seconds,
+                "end": end_seconds,
+                "text": text,
+                "source": source,
+                "source_ref": source_ref,
+                "timing_evidence": evidence,
+            }
+        )
+
+    metadata = {
+        "schema_version": SCHEMA_VERSION,
+        "clock": {
+            "kind": "output",
+            "timebase": {"numerator": numerator, "denominator": denominator},
+            "duration_ticks": duration_ticks,
+            "duration_seconds": duration_seconds,
+        },
+        "overlap_policy": "forbid",
+        "bindings": {"picture": picture, "audio": audio},
+        "timing_evidence_kinds": sorted(kinds),
+    }
+    return {"metadata": metadata, "entries": entries}

package/lib/video-recap/skills/video-assemble/scripts/subtitles/track_binding.py

@@ -0,0 +1,200 @@
+"""Bind an explicit output-clock subtitle track to media before any consumer uses it.
+
+The first render integration deliberately supports adopted AAC only. A future
+newly mixed narration track needs its own final-mix identity, not this input's
+soundtrack. Bound cue timing is a declared decision, not proof of speech onset.
+"""
+
+import bisect
+import json
+from fractions import Fraction
+from pathlib import Path
+
+from artifacts import file_identity
+from adoption.frozen_audio import probe_audio_packets
+from lib import run_cmd
+from subtitles.track import load_subtitle_track
+
+TRACK = 'subtitle_track.json'
+VALIDATION = 'subtitle_track_validation.json'
+VALIDATION_SCHEMA = 1
+PROJECTOR_VERSION = 1
+
+
+def current_bindings(video, selected_audio_stream=0, *, edit_plan_path=None):
+    """Compute the binding facts independently of the supplied subtitle track.
+
+    The picture binding is the resolved media path (plus the edit plan path when one
+    exists); the audio binding is the selected stream ordinal with its sample rate and
+    packet count.
+    """
+    packets = probe_audio_packets(video, selected_audio_stream)
+    picture = {'path': str(Path(video).resolve())}
+    if edit_plan_path is not None:
+        picture['edit_plan'] = str(Path(edit_plan_path).resolve())
+    return {'picture': picture,
+            'audio': {'selected_stream': selected_audio_stream,
+                      'sample_rate': packets['sample_rate'],
+                      'packet_count': packets['packet_count']}}
+
+
+def _picture_clock(video):
+    result = run_cmd([
+        'ffprobe', '-v', 'error', '-select_streams', 'v:0', '-show_streams', '-show_frames',
+        '-show_entries', 'stream=time_base,start_pts,duration_ts:frame=pts', '-of', 'json', str(video),
+    ])
+    if result.returncode:
+        raise ValueError(f'Cannot verify subtitle picture clock: {result.stderr}')
+    data = json.loads(result.stdout)
+    stream = data['streams'][0]
+    timebase = Fraction(stream['time_base'])
+    if int(stream['start_pts']) != 0:
+        raise ValueError('Bound subtitle render requires an output-clock video starting at zero')
+    duration = int(stream['duration_ts']) * timebase
+    pts = [int(frame['pts']) * timebase for frame in data['frames']]
+    if not pts or pts[0] != 0 or any(b <= a for a, b in zip(pts, pts[1:])) or pts[-1] >= duration:
+        raise ValueError('Cannot verify picture frame clock: expected strictly increasing PTS within duration')
+    return pts, duration
+
+
+def _project_boundary(target, frame_pts, duration):
+    """Choose an ASS centisecond that changes on the first frame at/after a cue.
+
+    ASS's 10ms clock is coarser than most frame clocks and can otherwise round a cue
+    forward by one frame. Do not silently degrade if two relevant frames cannot be
+    separated in that clock.
+    libass receives presentation time in integer milliseconds from ffmpeg.
+    """
+    index = bisect.bisect_left(frame_pts, target)
+    chosen = frame_pts[index] if index < len(frame_pts) else duration
+    centiseconds = chosen * 100 // 1
+    threshold_ms = int(centiseconds) * 10
+    previous_ms = int(frame_pts[index - 1] * 1000) if index else -1
+    if threshold_ms <= previous_ms:
+        raise ValueError('ASS 10ms clock cannot represent this cue boundary; use a frame-capable renderer')
+    ass_time = f'{centiseconds // 360000}:{centiseconds // 6000 % 60:02d}:{centiseconds // 100 % 60:02d}.{centiseconds % 100:02d}'
+    return {'requested_time': str(target), 'frame_index': index, 'pts': str(chosen),
+            'delta': str(chosen - target), 'ass_time': ass_time}
+
+
+def prepare_subtitle_track(input_video, work_dir, video_duration, *, audio_mode,
+                           selected_audio_stream=0, edit_plan_path=None,
+                           reject_legacy_estimate=False):
+    """Validate and project an explicit track before SRT/ASS/timeline/QC consumers.
+
+    No track preserves legacy behavior. A present but invalid track fails instead
+    of falling back to proportional timing. The persisted record is not approval.
+    """
+    work = Path(work_dir)
+    path = work / TRACK
+    validation = work / VALIDATION
+    validation.unlink(missing_ok=True)
+    if not path.exists():
+        return None
+    if audio_mode != 'adopted-packet-copy':
+        raise ValueError('Explicit subtitle_track currently requires adopted-packet-copy; new mix is not bound')
+    document = json.loads(path.read_bytes())
+    bindings = current_bindings(input_video, selected_audio_stream, edit_plan_path=edit_plan_path)
+    frame_pts, duration = _picture_clock(input_video)
+    if abs(float(duration) - float(video_duration)) > 0.05:
+        raise ValueError('Picture duration differs from assembly duration')
+    loaded = load_subtitle_track(
+        document, expected_picture_identity=bindings['picture'], expected_audio_identity=bindings['audio'],
+        expected_duration_seconds=duration, reject_legacy_estimate=reject_legacy_estimate,
+    )
+    clock = document['clock']['timebase']
+    tick = Fraction(clock['numerator'], clock['denominator'])
+    for entry, cue in zip(loaded['entries'], document['cues']):
+        start = _project_boundary(cue['start_tick'] * tick, frame_pts, duration)
+        end = _project_boundary(cue['end_tick'] * tick, frame_pts, duration)
+        if end['frame_index'] <= start['frame_index']:
+            raise ValueError('Subtitle cue has no visible frame in the actual picture clock')
+        entry.update(_bound_track=True, ass_start=start['ass_time'], ass_end=end['ass_time'],
+                     start=float(Fraction(start['pts'])), end=float(Fraction(end['pts'])))
+        entry['frame_projection'] = {'requested_ticks': [cue['start_tick'], cue['end_tick']],
+                                     'start': start, 'end': end}
+    loaded['validation_schema'] = VALIDATION_SCHEMA
+    loaded['projector_version'] = PROJECTOR_VERSION
+    loaded['binding'] = {
+        'input_video': str(Path(input_video).resolve()), 'identities': bindings,
+        'inputs': {'track': file_identity(path), 'video': file_identity(input_video),
+                   'edit_plan': file_identity(edit_plan_path) if edit_plan_path is not None else None},
+        'duration': str(duration), 'frame_count': len(frame_pts),
+        'edit_plan': str(Path(edit_plan_path).resolve()) if edit_plan_path is not None else None,
+        'verification': 'media_binding_and_declared_frame_projection_only',
+        'direct_listening': 'NOT_CHECKED', 'acoustic_alignment': 'NOT_CHECKED',
+    }
+    validation.write_text(json.dumps(loaded, ensure_ascii=False, indent=2) + '\n', encoding='utf-8')
+    return loaded
+
+
+def _load_validation(work):
+    path = Path(work) / VALIDATION
+    if not path.exists():
+        raise ValueError('Explicit subtitle track must be prepared against current media before use')
+    loaded = json.loads(path.read_text(encoding='utf-8'))
+    if (type(loaded.get('validation_schema')) is not int or loaded['validation_schema'] != VALIDATION_SCHEMA
+            or type(loaded.get('projector_version')) is not int or loaded['projector_version'] != PROJECTOR_VERSION):
+        raise ValueError('Subtitle validation/projector version changed; prepare again')
+    return loaded
+
+
+def bound_subtitle_entries(work_dir, video_duration):
+    """Return prepared exact entries, or None only when no explicit track exists."""
+    if work_dir is None:
+        return None
+    work = Path(work_dir)
+    if not (work / TRACK).exists():
+        return None
+    loaded = _load_validation(work)
+    record = loaded['binding']
+    inputs = record['inputs']
+    if file_identity(work / TRACK) != inputs['track']:
+        raise ValueError('stale subtitle track: author file changed after prepare')
+    video = Path(record['input_video'])
+    if not video.is_file() or file_identity(video) != inputs['video']:
+        raise ValueError('stale subtitle track: adopted media changed after prepare')
+    if record['edit_plan'] and (not Path(record['edit_plan']).is_file()
+                                or file_identity(record['edit_plan']) != inputs['edit_plan']):
+        raise ValueError('stale subtitle track: edit plan changed after prepare')
+    if abs(float(Fraction(record['duration'])) - float(video_duration)) > 0.05:
+        raise ValueError('stale subtitle track: consumer duration changed after prepare')
+    return loaded['entries']
+
+
+def verify_rendered_picture(work_dir, output_path):
+    """Check the actual rendered frame clock, not just pre-render declarations."""
+    work = Path(work_dir)
+    if not (work / TRACK).exists():
+        return None
+    path = work / VALIDATION
+    loaded = json.loads(path.read_text(encoding='utf-8'))
+    bound_subtitle_entries(work, float(Fraction(loaded['binding']['duration'])))
+    loaded['rendered_picture'] = {'output': str(Path(output_path).resolve()),
+                                  'frame_clock_verified': False}
+    path.write_text(json.dumps(loaded, ensure_ascii=False, indent=2) + '\n', encoding='utf-8')
+    if _picture_clock(output_path) != _picture_clock(loaded['binding']['input_video']):
+        raise ValueError('Rendered frame clock changed; subtitle frame projection is no longer valid')
+    loaded['rendered_picture'].update(frame_clock_verified=True,
+                                      frame_count=loaded['binding']['frame_count'],
+                                      identity=file_identity(output_path))
+    path.write_text(json.dumps(loaded, ensure_ascii=False, indent=2) + '\n', encoding='utf-8')
+    return loaded['rendered_picture']
+
+
+def manifest_subtitle_evidence(work_dir, input_video, output_path):
+    """Only expose evidence for the actual input and verified output of this render."""
+    work = Path(work_dir)
+    if not (work / TRACK).exists():
+        return None
+    loaded = _load_validation(work)
+    bound_subtitle_entries(work, float(Fraction(loaded['binding']['duration'])))
+    rendered = loaded.get('rendered_picture', {})
+    if rendered.get('frame_clock_verified') is not True:
+        raise ValueError('Subtitle output frame clock has not been verified')
+    if str(Path(input_video).resolve()) != loaded['binding']['input_video']:
+        raise ValueError('stale subtitle manifest: input media differs')
+    if not Path(output_path).is_file() or file_identity(output_path) != rendered.get('identity'):
+        raise ValueError('stale subtitle manifest: actual output differs from verified render')
+    return {'validation_path': str((work / VALIDATION).resolve()),
+            'binding': loaded['binding'], 'metadata': loaded['metadata'], 'rendered_picture': rendered}

package/lib/video-recap/skills/video-assemble/scripts/timeline.py

@@ -36,6 +36,12 @@ def _ceil_time(value, digits=4):
     return math.ceil((float(value) * scale) - 1e-9) / scale
 
 
+def _floor_time(value, digits=4):
+    """Round an interval start outward so serialization cannot clip source samples."""
+    scale = 10 ** digits
+    return math.floor((float(value) * scale) + 1e-9) / scale
+
+
 def build_timeline(canvas, duration_s, video_clips, narration_segments,
                    bgm=None, ducking=None, subtitle_segments=None,
                    image_segments=(), resource_packages=None,
@@ -48,15 +54,17 @@ def build_timeline(canvas, duration_s, video_clips, narration_segments,
                  "timeline_start", "timeline_end"}] (cut mode: one per clip;
                  full mode: a single clip spanning the whole video).
     narration_segments: placed beats [{"source_path", "timeline_start",
-                 "timeline_end", "text", "overlaps_speech", "gain"?}]; a zero-width
+                 "timeline_end", "text", "overlaps_speech", "gain"}]; a zero-width
                  beat (an unplaced segment) is skipped.
     subtitle_segments: optional display-ready text cues [{"text", "timeline_start",
                  "timeline_end"}]. When present, this is authoritative for the
                  subtitle/text track; narration segment text remains raw editor metadata.
-    bgm: optional {"source_path", "volume", "ducking_volume"}.
-    ducking: {"idle", "speech", "quiet", "fade", "bridge"?} for the original-audio
+    bgm: optional {"source_path", "volume", "ducking_volume", "fade"}.
+    ducking: {"idle", "speech", "quiet", "fade", "bridge"} for the original-audio
              automation; None disables original ducking (flat original). `bridge` holds
-             the duck across inter-beat gaps shorter than it (defaults to 2*fade).
+             the duck across inter-beat gaps shorter than it.
+    image_segments: optional v2 local image overlays [{"source_path", "timeline_start",
+                 "timeline_end", ...authoring extensions}], passed through as authored.
     """
     placed = [
         s for s in narration_segments
@@ -71,7 +79,7 @@ def build_timeline(canvas, duration_s, video_clips, narration_segments,
             restore_at = max(
                 hold_end, float(s.get("source_restore_at", hold_end + float(ducking["fade"])))
             )
-            level = float(ducking["speech" if s.get("overlaps_speech", True) else "quiet"])
+            level = float(ducking["speech" if s["overlaps_speech"] else "quiet"])
             duck_windows.append((float(s["timeline_start"]), hold_end, level, restore_at))
 
     # --- video track: each clip carries its original audio + ducking automation
@@ -82,7 +90,7 @@ def build_timeline(canvas, duration_s, video_clips, narration_segments,
         if ducking is not None:
             audio["volume_keyframes"] = release_ducking_keyframes(
                 duck_windows, ducking["idle"], ducking["fade"], ts, te,
-                bridge=ducking.get("bridge"))
+                bridge=ducking["bridge"])
             audio["base_gain"] = round(float(ducking["idle"]), 4)
         else:
             audio["base_gain"] = 1.0
@@ -110,11 +118,11 @@ def build_timeline(canvas, duration_s, video_clips, narration_segments,
     for s in placed:
         narration = {
             "source_path": s["source_path"],
-            "timeline_start": round(float(s["timeline_start"]), 4),
+            "timeline_start": _floor_time(s["timeline_start"], 4),
             "timeline_end": _ceil_time(s["timeline_end"], 4),
-            "gain": round(float(s.get("gain", 1.0)), 4),
-            "text": s.get("text", ""),
-            "overlaps_speech": bool(s.get("overlaps_speech", True)),
+            "gain": round(float(s["gain"]), 4),
+            "text": s["text"],
+            "overlaps_speech": bool(s["overlaps_speech"]),
         }
         for key in ("source_duck_end", "source_restore_at", "source_handoff_status", "source_entry_status"):
             if key in s:
@@ -127,12 +135,12 @@ def build_timeline(canvas, duration_s, video_clips, narration_segments,
                        "segments": narr_segs})
 
     # --- bgm track (optional, looped, ducked under narration)
-    if bgm and bgm.get("source_path"):
-        base = float(bgm.get("volume", 0.18))
-        duck = float(bgm.get("ducking_volume", 0.10))
-        fade = float(bgm.get("fade", (ducking or {}).get("fade", 0.25)))
+    if bgm:
+        base = float(bgm["volume"])
+        duck = float(bgm["ducking_volume"])
+        fade = float(bgm["fade"])
         kfs = ducking_keyframes(windows, base, duck, fade, 0.0, duration_s,
-                                bridge=(ducking or {}).get("bridge"))
+                                bridge=ducking["bridge"] if ducking else None)
         tracks.append({
             "kind": "audio", "name": "bgm", "role": "bgm", "loop": True,
             "segments": [{
@@ -165,41 +173,17 @@ def build_timeline(canvas, duration_s, video_clips, narration_segments,
     if text_segs:
         tracks.append({"kind": "text", "name": "subtitle", "segments": text_segs})
 
-    # --- local image overlays (optional, timeline schema v2)
+    # --- local image overlays (optional, timeline schema v2). Transform fields are
+    # optional authoring extensions; the JianYing exporter validates and defaults them.
     images = []
     for segment in image_segments:
-        if not isinstance(segment, dict) or not segment.get("source_path"):
-            continue
-        try:
-            ts = max(0.0, float(segment["timeline_start"]))
-            te = min(float(duration_s), float(segment["timeline_end"]))
-        except (KeyError, TypeError, ValueError):
-            continue
-        if not math.isfinite(ts) or not math.isfinite(te) or te <= ts:
-            continue
-        scale = segment.get("scale") if isinstance(segment.get("scale"), dict) else {}
-        position = segment.get("position") if isinstance(segment.get("position"), dict) else {}
-        flip = segment.get("flip") if isinstance(segment.get("flip"), dict) else {}
         image = {
-            "source_path": str(segment["source_path"]),
-            "timeline_start": round(ts, 4),
-            "timeline_end": round(te, 4),
-            "opacity": round(max(0.0, min(1.0, float(segment.get("opacity", 1.0)))), 4),
-            "rotation_degrees": round(float(segment.get("rotation_degrees", 0.0)), 4),
-            "scale": {
-                "x": round(float(scale.get("x", 1.0)), 4),
-                "y": round(float(scale.get("y", 1.0)), 4),
-            },
-            "position": {
-                "x": round(float(position.get("x", 0.0)), 4),
-                "y": round(float(position.get("y", 0.0)), 4),
-            },
-            "flip": {
-                "horizontal": bool(flip.get("horizontal", False)),
-                "vertical": bool(flip.get("vertical", False)),
-            },
+            "source_path": segment["source_path"],
+            "timeline_start": round(float(segment["timeline_start"]), 4),
+            "timeline_end": round(float(segment["timeline_end"]), 4),
         }
-        for key in ("lut", "mask", "speed", "transition"):
+        for key in ("flip", "lut", "mask", "opacity", "position", "rotation_degrees",
+                    "scale", "speed", "transition"):
             if key in segment:
                 image[key] = deepcopy(segment[key])
         images.append(image)