@oh-story/dsh 0.1.10 → 0.1.12

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

@@ -4,22 +4,20 @@ import json
 import os
 from pathlib import Path
 
-from artifacts import _explicit_source_video, _value_fingerprint
+from artifacts import _explicit_source_video
 from lib import log, run_cmd
 
 def _load_cut_timeline_plan(work_dir):
-    """The cut plan, preferring clip_plan_validated.json when it matches the raw plan; None in full mode."""
+    """The cut plan, preferring clip_plan_validated.json unless the raw plan is newer; None in full mode."""
     raw_plan_path = Path(work_dir) / "clip_plan.json"
     validated_plan_path = Path(work_dir) / "clip_plan_validated.json"
     if not validated_plan_path.exists():
         return json.loads(raw_plan_path.read_text(encoding="utf-8")) if raw_plan_path.exists() else None
     if not raw_plan_path.exists():
         return json.loads(validated_plan_path.read_text(encoding="utf-8"))
-    raw_plan = json.loads(raw_plan_path.read_text(encoding="utf-8"))
-    validated_plan = json.loads(validated_plan_path.read_text(encoding="utf-8"))
-    if validated_plan.get("raw_plan_fingerprint") == _value_fingerprint(raw_plan):
-        return validated_plan
-    return raw_plan
+    if validated_plan_path.stat().st_mtime_ns >= raw_plan_path.stat().st_mtime_ns:
+        return json.loads(validated_plan_path.read_text(encoding="utf-8"))
+    return json.loads(raw_plan_path.read_text(encoding="utf-8"))
 
 
 def _plan_clip_spans(work_dir):
@@ -120,13 +118,13 @@ def _canvas_from_stream(stream):
     }
 
 
-def _probe_canvas(video_path, *, command_runner=run_cmd):
+def _probe_canvas(video_path):
     """Return rotation/SAR/DAR-aware canvas facts for a video.
 
     ``width``/``height`` are the display canvas used by subtitle/overlay geometry.
     For legacy square-pixel landscape sources, these remain the raw storage dimensions.
     """
-    res = command_runner([
+    res = run_cmd([
         "ffprobe", "-v", "error", "-select_streams", "v:0",
         "-show_entries",
         "stream=width,height,r_frame_rate,avg_frame_rate,sample_aspect_ratio,display_aspect_ratio:stream_tags=rotate:stream_side_data=rotation",
@@ -140,23 +138,16 @@ def _probe_canvas(video_path, *, command_runner=run_cmd):
     return _canvas_from_stream(streams[0])
 
 
-def _has_audio_stream(video_path, *, command_runner=run_cmd):
+def _has_audio_stream(video_path):
     """Return True when the input has an audio stream usable as [0:a]."""
-    result = command_runner([
+    result = run_cmd([
         "ffprobe", "-v", "error", "-select_streams", "a:0",
         "-show_entries", "stream=index", "-of", "csv=p=0", str(video_path),
     ])
     return result.returncode == 0 and bool(result.stdout.strip())
 
 
-def _build_video_clips(
-    input_video,
-    work_dir,
-    duration_s,
-    *,
-    logger=log,
-    source_video_getter=_explicit_source_video,
-):
+def _build_video_clips(input_video, work_dir, duration_s):
     """Video-track clips for the timeline.
 
     In cut mode each plan entry becomes a clip referencing the ORIGINAL source
@@ -164,7 +155,7 @@ def _build_video_clips(
     require an explicit ambient --source-video. Without any declared source (full
     mode, or cut mode rendered without --source-video) the rendered input is one clip.
     """
-    explicit_source_video = source_video_getter()
+    explicit_source_video = _explicit_source_video()
     spans = _plan_clip_spans(work_dir)
     multi_source = spans is not None and any(span["entry"].get("source_path") for span in spans)
     if spans is None or not (explicit_source_video or multi_source):
@@ -180,7 +171,7 @@ def _build_video_clips(
             # Degrade ONLY this clip — point it at the rendered cut for its own output
             # window — and keep real provenance for every present source, instead of
             # collapsing the whole multi-source timeline.
-            logger(f"  时间线: source_path 不存在，该片段降级为剪后成片片段: {source_path or '(unset)'}")
+            log(f"  时间线: source_path 不存在，该片段降级为剪后成片片段: {source_path or '(unset)'}")
             clips.append({"source_id": entry.get("source_id"),
                           "source_path": str(input_video),
                           "source_start": timeline_start,

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

@@ -10,9 +10,7 @@ def _apply_narration_speed(
     tts_segments,
     work_dir,
     *,
-    command_runner=run_cmd,
-    duration_probe=get_video_duration,
-    logger=log,
+    tempo_policy=None,
 ):
     """Globally speed up narration audio via atempo (CONFIG['narration_speed']).
 
@@ -20,7 +18,7 @@ def _apply_narration_speed(
     snappier without the chipmunk effect. Rewrites each segment's audio_path/duration
     to the sped copy so the rest of assembly is unchanged. No-op at speed 1.0.
     """
-    speed = CONFIG["narration_speed"]
+    speed = tempo_policy["global_atempo"] if tempo_policy else CONFIG["narration_speed"]
     if abs(speed - 1.0) <= 1e-3:
         return
     done = 0
@@ -29,14 +27,15 @@ def _apply_narration_speed(
         if not os.path.exists(src):
             continue  # reported as a skipped segment during placement
         out = str(Path(work_dir) / f"_spd_{seg['index']}.wav")
-        res = command_runner(["ffmpeg", "-y", "-i", src, "-filter:a", f"atempo={speed:.3f}",
+        res = run_cmd(["ffmpeg", "-y", "-i", src, "-filter:a", f"atempo={speed:.3f}",
                               "-ar", "44100", "-ac", "1", "-acodec", "pcm_s16le", out])
         if res.returncode != 0:
             raise RuntimeError(f"解说提速失败 {src}: {res.stderr}")
         seg["audio_path"] = out
-        seg["audio_duration"] = duration_probe(out)
+        seg["narration_conversion_path"] = out
+        seg["audio_duration"] = get_video_duration(out)
         done += 1
-    logger(f"解说整体提速: atempo={speed:.2f} ({done} 段)")
+    log(f"解说整体提速: atempo={speed:.2f} ({done} 段)")
 
 
 def _adjust_tts_speed(
@@ -44,9 +43,7 @@ def _adjust_tts_speed(
     target_duration,
     tts_rate_offset=0.0,
     *,
-    command_runner=run_cmd,
-    duration_probe=get_video_duration,
-    logger=log,
+    tempo_policy=None,
 ):
     """Fit overlong TTS with bounded atempo; never time-trim speech in assemble.
 
@@ -55,8 +52,16 @@ def _adjust_tts_speed(
     untouched for QC to block instead of guessing a spoken_text truncation.
     """
     audio_path = Path(audio_path)
-    current_dur = duration_probe(audio_path)
+    current_dur = get_video_duration(audio_path)
     budget = narration_tempo_budget(tts_rate_offset)
+    if tempo_policy:
+        budget.update({
+            "global_narration_speed": tempo_policy["global_atempo"],
+            "tts_rate_factor": 1.0,
+            "segment_tempo_max": tempo_policy["segment_tempo_max"],
+            "cumulative_tempo_max": tempo_policy["cumulative_tempo_max"],
+            "cumulative_tempo_hard_max": tempo_policy["cumulative_tempo_hard_max"],
+        })
     meta = {
         "fit_status": "fits",
         "blocking": False,
@@ -75,6 +80,14 @@ def _adjust_tts_speed(
     if current_dur <= target_duration:
         return (str(audio_path), current_dur, meta)
 
+    if tempo_policy and not tempo_policy["bounded_segment_fit"]:
+        meta.update({
+            "fit_status": "no_safe_fit", "blocking": True,
+            "truncate_reason": "no_safe_boundary", "placed_audio_duration": 0.0,
+            "needed_tempo_factor": current_dur / target_duration,
+        })
+        return (str(audio_path), current_dur, meta)
+
     ratio = current_dur / target_duration
     effective_max = budget["segment_tempo_max"]
     if ratio > effective_max:
@@ -85,7 +98,7 @@ def _adjust_tts_speed(
             "placed_audio_duration": 0.0,
             "needed_tempo_factor": ratio,
         })
-        logger(
+        log(
             f"  TTS 无安全放置: {current_dur:.1f}s 需 x{ratio:.2f}，"
             f"超过段内预算 x{effective_max:.2f}（assemble 不按时间硬切）"
         )
@@ -98,10 +111,10 @@ def _adjust_tts_speed(
     cmd = ["ffmpeg", "-y", "-i", str(audio_path),
            "-filter:a", f"atempo={tempo:.6f}",
            "-ar", "44100", "-ac", "1", str(adjusted_path)]
-    result = command_runner(cmd)
+    result = run_cmd(cmd)
     if result.returncode != 0:
         raise RuntimeError(f"TTS 加速失败 {audio_path}: {result.stderr}")
-    new_dur = duration_probe(adjusted_path)
+    new_dur = get_video_duration(adjusted_path)
     if new_dur > target_duration + (1.0 / 44100.0):
         adjusted_path.unlink(missing_ok=True)
         meta.update({
@@ -111,7 +124,7 @@ def _adjust_tts_speed(
             "placed_audio_duration": 0.0,
             "needed_tempo_factor": new_dur / target_duration,
         })
-        logger(
+        log(
             f"  TTS 加速后仍超出安全窗口 {new_dur - target_duration:.3f}s；"
             "禁止裁尾，交由 Agent 缩短/移动文本"
         )
@@ -123,7 +136,7 @@ def _adjust_tts_speed(
         "placed_audio_duration": new_dur,
         "effective_tempo": budget["global_narration_speed"] * budget["tts_rate_factor"] * tempo,
     })
-    logger(f"  TTS 温和加速: {current_dur:.1f}s → {new_dur:.1f}s (x{tempo:.2f})")
+    log(f"  TTS 温和加速: {current_dur:.1f}s → {new_dur:.1f}s (x{tempo:.2f})")
     return (str(adjusted_path), new_dur, meta)
 
 
@@ -170,9 +183,7 @@ def _build_timed_narration(
     video_duration,
     work_dir,
     *,
-    adjust_speed=_adjust_tts_speed,
-    command_runner=run_cmd,
-    logger=log,
+    tempo_policy=None,
 ):
     """将 TTS 片段按时间轴放置到一条与视频等长的音轨上"""
     sample_rate = 44100
@@ -194,7 +205,7 @@ def _build_timed_narration(
 
     for seg in tts_segments:
         wav_path = seg["audio_path"]
-        pause_samples = int(seg.get("pause_after_ms", CONFIG["breath_ms"]) * sample_rate / 1000)
+        pause_samples = int(seg["pause_after_ms"] * sample_rate / 1000)
         # 段落收紧：同一段落内（与上一句作者留白 <= run_gap）把这一句紧贴上一句的实际收尾播放，
         # 句间间隔固定为 tight_pause，不受 slot 内居中延迟 / TTS 时长波动影响。段落之间（作者特意留
         # 的大留白，让精彩原声透出）才放回原声。这样句间间隔稳定、不会出现"一句解说一段空白"。
@@ -210,12 +221,17 @@ def _build_timed_narration(
             continue
 
         original_wav_path = wav_path
-        with wave.open(wav_path, "rb") as wf_check:
-            needs_resample = (
-                wf_check.getnchannels(), wf_check.getsampwidth(), wf_check.getframerate()
-            ) != (1, 2, sample_rate)
-
-        tts_rate_offset = seg.get("tts_rate_offset", 0.0)
+        try:
+            with wave.open(wav_path, "rb") as wf_check:
+                needs_resample = (
+                    wf_check.getnchannels(), wf_check.getsampwidth(), wf_check.getframerate()
+                ) != (1, 2, sample_rate)
+        except (wave.Error, EOFError):
+            # Valid post-processed WAV may use IEEE float, which Python's wave
+            # reader does not support. FFmpeg performs the explicit PCM conversion.
+            needs_resample = True
+
+        tts_rate_offset = seg["tts_rate_offset"]
         tts_dur = seg["audio_duration"]
 
         slot_duration = max(0.0, float(seg["end"]) - float(seg["start"]))
@@ -240,7 +256,15 @@ def _build_timed_narration(
         available_samples = end_boundary - actual_start
         available_duration = max(available_samples / sample_rate, 0)
         if tts_dur > available_duration > 0:
-            wav_path, _actual_dur, fit_meta = adjust_speed(wav_path, available_duration, tts_rate_offset)
+            if tempo_policy:
+                wav_path, _actual_dur, fit_meta = _adjust_tts_speed(
+                    wav_path, available_duration, tts_rate_offset,
+                    tempo_policy=tempo_policy,
+                )
+            else:
+                wav_path, _actual_dur, fit_meta = _adjust_tts_speed(
+                    wav_path, available_duration, tts_rate_offset
+                )
             seg.update({
                 "fit_status": fit_meta["fit_status"],
                 "segment_tempo_factor": fit_meta["segment_tempo_factor"],
@@ -257,6 +281,11 @@ def _build_timed_narration(
                 continue
         else:
             budget = narration_tempo_budget(tts_rate_offset)
+            if tempo_policy:
+                budget.update({
+                    "global_narration_speed": tempo_policy["global_atempo"],
+                    "tts_rate_factor": 1.0,
+                })
             seg.update({
                 "fit_status": "fits",
                 "segment_tempo_factor": 1.0,
@@ -270,16 +299,17 @@ def _build_timed_narration(
             needs_resample = False
         if needs_resample:
             tmp_path = str(Path(work_dir) / f"_rs_{seg['index']}.wav")
-            rs_result = command_runner(["ffmpeg", "-y", "-i", wav_path,
+            rs_result = run_cmd(["ffmpeg", "-y", "-i", wav_path,
                                         "-ar", str(sample_rate), "-ac", "1",
                                         "-acodec", "pcm_s16le", tmp_path])
             if rs_result.returncode != 0:
-                logger(f"  跳过: 重采样失败 {wav_path}: {rs_result.stderr}")
+                log(f"  跳过: 重采样失败 {wav_path}: {rs_result.stderr}")
                 _unplaced(seg, seg["start"], "skipped", "resample_failed")
                 prev_pause_samples = pause_samples
                 skipped_count += 1
                 continue
             wav_path = tmp_path
+            seg["narration_conversion_path"] = tmp_path
 
         with wave.open(wav_path, "rb") as wf:
             wf_data = bytearray(wf.readframes(wf.getnframes()))
@@ -290,7 +320,7 @@ def _build_timed_narration(
         write_samples = audio_samples
 
         if write_samples <= 0 or available <= 0:
-            logger(f"  跳过: {seg['start']:.1f}s-{seg['end']:.1f}s (无空间)")
+            log(f"  跳过: {seg['start']:.1f}s-{seg['end']:.1f}s (无空间)")
             _unplaced(seg, seg["start"], "no_safe_fit", "no_room", blocking=True)
             prev_pause_samples = pause_samples
             no_safe_fit_count += 1
@@ -301,7 +331,7 @@ def _build_timed_narration(
             # consonant/vowel release. _adjust_tts_speed must produce a complete file
             # that fits; otherwise block and ask the Agent to shorten/move the block.
             over = (audio_samples - available) / sample_rate
-            logger(f"  TTS 无安全放置: 段 {seg['index']} 超出可用窗口 {over:.3f}s；禁止裁尾，交由 QC 阻断")
+            log(f"  TTS 无安全放置: 段 {seg['index']} 超出可用窗口 {over:.3f}s；禁止裁尾，交由 QC 阻断")
             _unplaced(seg, actual_start / sample_rate, "no_safe_fit", "no_safe_boundary", blocking=True)
             prev_pause_samples = pause_samples
             skipped_count += 1
@@ -312,7 +342,7 @@ def _build_timed_narration(
         if actual_start < last_written_end:
             overlap_ms = (last_written_end - actual_start) * 1000 / sample_rate
             if last_written_end >= actual_start + write_samples:
-                logger(f"  跳过重叠段: {actual_start/sample_rate:.1f}s "
+                log(f"  跳过重叠段: {actual_start/sample_rate:.1f}s "
                        f"(与前段重叠 {overlap_ms:.0f}ms)")
                 _unplaced(seg, seg["start"], "no_safe_fit", "no_room", blocking=True)
                 prev_pause_samples = pause_samples
@@ -321,7 +351,7 @@ def _build_timed_narration(
             actual_start = last_written_end
             available = end_boundary - actual_start
             if write_samples > available:
-                logger(f"  重叠 {overlap_ms:.0f}ms 后无安全完整窗口，跳过")
+                log(f"  重叠 {overlap_ms:.0f}ms 后无安全完整窗口，跳过")
                 _unplaced(seg, actual_start / sample_rate, "no_safe_fit", "no_safe_boundary", blocking=True)
                 prev_pause_samples = pause_samples
                 skipped_count += 1
@@ -380,4 +410,4 @@ def _build_timed_narration(
             "已中止以避免生成无解说视频"
         )
 
-    logger(f"解说音轨: {video_duration:.1f}s, {len(tts_segments)} 段")
+    log(f"解说音轨: {video_duration:.1f}s, {len(tts_segments)} 段")

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

@@ -0,0 +1,122 @@
+"""Static packaging layers (frame / header / logo images) burned over the whole recap.
+
+The caller writes ``work_dir/packaging_layers.json`` (the orchestrator does so from a bound
+``packaging`` template). Each layer is a local image scaled into a rect on a declared
+canvas. ffmpeg reads the images with ``movie=`` sources, so the render stays a single-input
+video filter; ``timeline.json`` gets matching image segments for editable export.
+"""
+
+import json
+from pathlib import Path
+
+import lib
+from artifacts import file_identity
+from visual_render import _escape_subtitle_filter_path
+
+PACKAGING_LAYERS = "packaging_layers.json"
+_IMAGE_EXTS = {".png", ".jpg", ".jpeg", ".webp"}
+
+
+def load_packaging_layers(work_dir, canvas):
+    """Validated layers for this canvas, or [] when the work_dir declares none."""
+    path = Path(work_dir) / PACKAGING_LAYERS
+    if not path.exists():
+        return []
+    plan = json.loads(path.read_text(encoding="utf-8"))
+    declared = plan["canvas"]
+    if (declared["width"], declared["height"]) != (canvas["width"], canvas["height"]):
+        raise RuntimeError(
+            f"{PACKAGING_LAYERS} 按 {declared['width']}x{declared['height']} 设计，"
+            f"成片画布是 {canvas['width']}x{canvas['height']}"
+        )
+    layers = []
+    for layer in plan["layers"]:
+        image = Path(layer["path"]).expanduser().resolve()
+        rect = layer["rect"]
+        if not image.is_file() or image.suffix.lower() not in _IMAGE_EXTS:
+            raise RuntimeError(f"包装图层 {layer['name']} 的图片不可用: {image}")
+        if (min(rect["x"], rect["y"]) < 0 or rect["width"] <= 0 or rect["height"] <= 0
+                or rect["x"] + rect["width"] > canvas["width"]
+                or rect["y"] + rect["height"] > canvas["height"]):
+            raise RuntimeError(f"包装图层 {layer['name']} 超出画布")
+        layers.append({"name": layer["name"], "path": str(image), "rect": dict(rect),
+                       "image_size": _image_size(image)})
+    return layers
+
+
+def _image_size(image):
+    """Pixel size of a layer image; the editor fits by it, the render stretches to the rect."""
+    res = lib.run_cmd(["ffprobe", "-v", "error", "-select_streams", "v:0",
+                       "-show_entries", "stream=width,height", "-of", "json", str(image)])
+    try:
+        stream = json.loads(res.stdout)["streams"][0]
+        return {"width": int(stream["width"]), "height": int(stream["height"])}
+    except (ValueError, KeyError, IndexError):
+        raise RuntimeError(f"无法读取包装图层尺寸: {image}") from None
+
+
+def compose_video_filter(chain, layers, *, mask_first):
+    """Join the existing filter chain, inserting packaging layers after the source mask.
+
+    Order: source-subtitle mask → packaging layers → text overlays / burned subtitles →
+    scaling. Without layers this is the plain comma-joined chain.
+    """
+    if not layers:
+        return ",".join(chain)
+    head, tail = (chain[:1], chain[1:]) if mask_first else ([], list(chain))
+    graph = [
+        f"movie=filename='{_escape_subtitle_filter_path(layer['path'])}',"
+        f"scale={layer['rect']['width']}:{layer['rect']['height']},format=rgba[pk{i}]"
+        for i, layer in enumerate(layers)
+    ]
+    current = "in"
+    if head:
+        graph.append(f"[in]{head[0]}[pm]")
+        current = "pm"
+    for i, layer in enumerate(layers):
+        out = "out" if i == len(layers) - 1 and not tail else f"po{i}"
+        graph.append(f"[{current}][pk{i}]overlay=x={layer['rect']['x']}:y={layer['rect']['y']}[{out}]")
+        current = out
+    if tail:
+        graph.append(f"[{current}]{','.join(tail)}[out]")
+    return ";".join(graph)
+
+
+def timeline_image_segments(layers, canvas, duration_s):
+    """Full-length image segments in the timeline's center-origin, Y-up transform.
+
+    The editor shows an image fitted inside the canvas (keeping its own aspect) at scale 1;
+    the render stretches it to the rect, so x and y scales are derived separately.
+    """
+    width, height = canvas["width"], canvas["height"]
+    segments = []
+    for layer in layers:
+        rect, size = layer["rect"], layer["image_size"]
+        fit = min(width / size["width"], height / size["height"])
+        segments.append({
+            "source_path": layer["path"],
+            "timeline_start": 0.0,
+            "timeline_end": duration_s,
+            "scale": {"x": round(rect["width"] / (size["width"] * fit), 6),
+                      "y": round(rect["height"] / (size["height"] * fit), 6)},
+            "position": {
+                "x": round((rect["x"] + rect["width"] / 2 - width / 2) / (width / 2), 6),
+                "y": round((height / 2 - rect["y"] - rect["height"] / 2) / (height / 2), 6),
+            },
+        })
+    return segments
+
+
+def packaging_settings(work_dir):
+    """What the manifest records: the plan file and each layer image's identity."""
+    path = Path(work_dir) / PACKAGING_LAYERS if work_dir is not None else None
+    if path is None or not path.exists():
+        return {"artifact": PACKAGING_LAYERS, "present": False, "layers": []}
+    plan = json.loads(path.read_text(encoding="utf-8"))
+    layers = []
+    for layer in plan["layers"]:
+        image = Path(layer["path"]).expanduser().resolve()
+        layers.append({"name": layer["name"], "path": str(image), "rect": layer["rect"],
+                       **(file_identity(image) if image.is_file() else {})})
+    return {"artifact": PACKAGING_LAYERS, "present": True, "identity": file_identity(path),
+            "template": plan.get("template"), "layers": layers}