@oh-story/dsh 0.1.11 → 0.1.13

package/lib/video-recap/skills/video-understanding/scripts/narration_lint.py

@@ -1,707 +0,0 @@
-"""Enforce narration timing, evidence, budget, and sentence-integrity rules.
-
-This is the single validator for the agent-authored narration.json: shape, numeric
-timing and text checks live here, and every later consumer trusts its result.
-"""
-
-import json
-import math
-from pathlib import Path
-
-from lib import CONFIG, log
-from agent_text import (
-    _clean_narration_punctuation,
-    _find_scene_for_midpoint,
-    _normalise_narration_segment,
-    _post_dedup_narration,
-    _recommended_char_budget,
-    _scene_available_seconds,
-    _text_char_count,
-    _truncate_at_sentence,
-)
-from deslop_qc import analyze_deslop_qc
-from speech_ownership import (
-    entry_overlaps_source_speech,
-    load_source_sentence_evidence,
-)
-
-
-def _lint_issue(level, index, code, message, **extra):
-    issue = {"level": level, "index": index, "code": code, "message": message}
-    issue.update(extra)
-    return issue
-
-
-def _is_number(value):
-    return (
-        isinstance(value, (int, float))
-        and not isinstance(value, bool)
-        and math.isfinite(value)
-    )
-
-
-def _visual_overlay_issues(index, seg):
-    """Shape-check the renderer handoff recap reads verbatim from a validated segment.
-
-    recap owns which overlay `type` values it actually renders and drops the rest; lint owns
-    the shape, because nothing between here and that filter re-checks it — and the filter runs
-    after TTS, so a malformed overlay caught there would already have cost a synthesis pass.
-    """
-    overlays = seg.get("visual_overlays")
-    if overlays is None:
-        return []
-    if not isinstance(overlays, list):
-        return [
-            _lint_issue(
-                "error", index, "invalid_visual_overlays", "visual_overlays must be an array"
-            )
-        ]
-    issues = []
-    for position, overlay in enumerate(overlays):
-        if not isinstance(overlay, dict):
-            issues.append(
-                _lint_issue(
-                    "error", index, "invalid_visual_overlay",
-                    "visual_overlays entries must be objects",
-                    overlay_index=position,
-                )
-            )
-            continue
-        for key in ("type", "text"):
-            value = overlay.get(key)
-            if not isinstance(value, str) or not value.strip():
-                issues.append(
-                    _lint_issue(
-                        "error", index, "invalid_visual_overlay",
-                        f"visual_overlays[].{key} must be a non-empty string",
-                        overlay_index=position,
-                    )
-                )
-        for key in ("start", "end"):
-            if key in overlay and not _is_number(overlay[key]):
-                issues.append(
-                    _lint_issue(
-                        "error", index, "invalid_visual_overlay",
-                        f"visual_overlays[].{key} must be numeric",
-                        overlay_index=position,
-                    )
-                )
-    return issues
-
-
-def _scene_bounds_for_midpoint(scenes_analysis, start, end):
-    scene = _find_scene_for_midpoint(scenes_analysis, start, end)
-    if not scene:
-        return None
-    return scene["start"], scene["end"]
-
-
-def _frame_fact_times_for_segment(scenes_analysis, start, end):
-    """Return frame-fact timestamps covered by a narration segment.
-
-    These timestamps are cheap visual anchors. A narration slot that spans too
-    many anchors is more likely to drift into "general story summary" instead
-    of staying attached to what is on screen.
-    """
-    scene = _find_scene_for_midpoint(scenes_analysis, start, end)
-    if not scene:
-        return []
-    return sorted(
-        ts
-        for ts in map(float, scene.get("frame_facts", {}))
-        if start <= ts <= end
-    )
-
-
-def _clip_span(clip):
-    """A validated plan clip carries source_start/source_end; a raw agent plan start/end."""
-    if "source_start" in clip:
-        return clip["source_start"], clip["source_end"]
-    return clip["start"], clip["end"]
-
-
-def _clip_matches_for_segment(seg, clip_plan, requested_clip_id):
-    if not clip_plan:
-        return []
-    clips = clip_plan["clips"]
-    midpoint = (seg["start"] + seg["end"]) / 2
-    if requested_clip_id is not None:
-        clips = [clip for clip in clips if clip.get("clip_id") == requested_clip_id]
-    return [
-        clip
-        for clip in clips
-        if _clip_span(clip)[0] <= midpoint <= _clip_span(clip)[1]
-    ]
-
-
-def _source_sentence_entry_issue(index, start, anchors, speech_owned):
-    """Return a blocking issue when narration enters midway through source speech.
-
-    The validator reports a correction instead of silently moving audio. Source
-    sentence integrity is invariant; an editorial policy string cannot bypass it.
-    """
-    if not speech_owned:
-        return None
-    # A cold-open at the first frame is not an interruption: the source sentence
-    # has not been allowed to start. All later entries must use a measured anchor.
-    if start <= 0.25:
-        return None
-    if not anchors:
-        return _lint_issue(
-            "error",
-            index,
-            "source_sentence_anchors_unavailable",
-            "Source speech owns this entry but no verified sentence-end anchor is available. "
-            "Move/remove the narration or regenerate output speech evidence before TTS.",
-            entry_time=round(start, 3),
-            suggested_start=None,
-        )
-    # Only the measured acoustic pause owns a safe entry. A tiny 80ms post-anchor
-    # tolerance covers timestamp/sample rounding; the old +450ms allowance could
-    # already be several Chinese syllables into the next sentence.
-    for anchor in anchors:
-        when = anchor["time"]
-        pause_start = anchor.get("pause_start", when - 0.12)
-        if pause_start - 0.05 <= start <= when + 0.08:
-            return None
-
-    suggested = next(
-        (anchor for anchor in anchors if anchor["time"] > start + 0.08), None
-    )
-    return _lint_issue(
-        "error",
-        index,
-        "interrupts_source_sentence",
-        "Narration enters before the source sentence finishes. Move this block to the suggested "
-        "sentence-end anchor, or shorten/move/remove it when there is no later verified anchor, "
-        "then rerun lint before TTS. Source sentence interruption has no override.",
-        entry_time=round(start, 3),
-        suggested_start=round(suggested["time"], 3) if suggested else None,
-        source_text_tail=str(suggested.get("text_tail", "")).strip() if suggested else "",
-        anchor_confidence=suggested["confidence"] if suggested else None,
-    )
-
-
-def _has_connected_predecessor(narration, idx, start):
-    """A back-to-back narration handoff (<=150ms gap) does not expose the source track,
-    so the next TTS block is not a new source-speech entry."""
-    for other_idx, other in enumerate(narration):
-        if other_idx == idx or not isinstance(other, dict):
-            continue
-        other_start, other_end = other.get("start"), other.get("end")
-        if not _is_number(other_start) or not _is_number(other_end):
-            continue
-        if other_start < start and -0.001 <= start - other_end <= 0.15:
-            return True
-    return False
-
-
-def lint_narration(
-    narration, scenes_analysis=None, *, clip_plan=None, mode="full", work_dir=None,
-    require_chronological=False,
-):
-    """Preflight-check agent narration before TTS; write narration_lint.json when work_dir is set.
-
-    Segments are sorted by start for the timing checks; ``require_chronological`` (the
-    --preserve-approved-text contract) additionally rejects input that is not already in order."""
-    scenes_analysis = scenes_analysis or []
-    errors = []
-    warnings = []
-    normalized = []
-    source_evidence = load_source_sentence_evidence(work_dir, mode=mode)
-    source_sentence_anchors = source_evidence["anchors"]
-    if not isinstance(narration, list):
-        errors.append(
-            _lint_issue(
-                "error",
-                None,
-                "invalid_json_shape",
-                "narration.json must be a JSON array",
-            )
-        )
-    else:
-        previous_start = None
-        for idx, seg in enumerate(narration):
-            if not isinstance(seg, dict):
-                errors.append(
-                    _lint_issue(
-                        "error",
-                        idx,
-                        "invalid_segment",
-                        "Narration segment must be an object",
-                    )
-                )
-                continue
-            start, end = seg.get("start"), seg.get("end")
-            if not _is_number(start) or not _is_number(end):
-                errors.append(
-                    _lint_issue(
-                        "error", idx, "invalid_time", "start/end must be finite numbers"
-                    )
-                )
-                continue
-            if require_chronological and previous_start is not None and start < previous_start:
-                errors.append(
-                    _lint_issue(
-                        "error",
-                        idx,
-                        "out_of_order",
-                        "Segments must be listed in chronological order",
-                        start=start,
-                        previous_start=previous_start,
-                    )
-                )
-            previous_start = start
-            text = seg.get("narration")
-            if not isinstance(text, str):
-                errors.append(
-                    _lint_issue(
-                        "error",
-                        idx,
-                        "invalid_narration",
-                        "narration must be a string",
-                        start=start,
-                        end=end,
-                    )
-                )
-                continue
-            text = text.strip()
-            pause = seg.get("pause_after_ms", CONFIG["breath_ms"])
-            if not isinstance(pause, int) or isinstance(pause, bool) or pause < 0:
-                errors.append(
-                    _lint_issue(
-                        "error",
-                        idx,
-                        "invalid_pause",
-                        "pause_after_ms must be a non-negative integer number of milliseconds",
-                    )
-                )
-                continue
-            errors.extend(_visual_overlay_issues(idx, seg))
-            if end <= start:
-                errors.append(
-                    _lint_issue(
-                        "error",
-                        idx,
-                        "invalid_time_range",
-                        "end must be greater than start",
-                        start=start,
-                        end=end,
-                    )
-                )
-                continue
-            if not text:
-                errors.append(
-                    _lint_issue(
-                        "error",
-                        idx,
-                        "empty_narration",
-                        "narration text must not be empty",
-                        start=start,
-                        end=end,
-                    )
-                )
-                continue
-
-            char_count = _text_char_count(text)
-            budget = _recommended_char_budget(start, end)
-            # estimate at the REAL playback rate (after the narration_speed atempo); otherwise a
-            # beat sized to its 1.3x-sped slot looks "over budget" when it actually fits.
-            play_rate = CONFIG["speech_rate"] * CONFIG["narration_speed"]
-            estimated_tts_seconds = char_count / play_rate
-            slot_seconds = _scene_available_seconds(start, end)
-            if budget < 5:
-                warnings.append(
-                    _lint_issue(
-                        "warning",
-                        idx,
-                        "slot_too_short",
-                        "Narration slot is very short; TTS may be clipped",
-                        start=start,
-                        end=end,
-                        budget_chars=budget,
-                    )
-                )
-            elif estimated_tts_seconds > slot_seconds:
-                warnings.append(
-                    _lint_issue(
-                        "warning",
-                        idx,
-                        "over_budget",
-                        "Text may exceed the available TTS slot",
-                        start=start,
-                        end=end,
-                        budget_chars=budget,
-                        actual_chars=char_count,
-                        estimated_tts_seconds=round(estimated_tts_seconds, 2),
-                        slot_seconds=round(slot_seconds, 2),
-                    )
-                )
-            if text[-1] not in "。！？!?….":
-                warnings.append(
-                    _lint_issue(
-                        "warning",
-                        idx,
-                        "incomplete_sentence",
-                        "Narration should end with a complete sentence punctuation",
-                        text_tail=text[-8:],
-                    )
-                )
-
-            if not _has_connected_predecessor(narration, idx, start):
-                entry_issue = _source_sentence_entry_issue(
-                    idx,
-                    start,
-                    source_sentence_anchors,
-                    entry_overlaps_source_speech(
-                        start,
-                        source_evidence,
-                        authored_overlap=seg.get("overlaps_speech", True),
-                    ),
-                )
-                if entry_issue:
-                    errors.append(entry_issue)
-
-            scene_bounds = _scene_bounds_for_midpoint(scenes_analysis, start, end)
-            if scenes_analysis and not scene_bounds:
-                warnings.append(
-                    _lint_issue(
-                        "warning",
-                        idx,
-                        "outside_scene",
-                        "Narration midpoint does not match any detected scene",
-                        start=start,
-                        end=end,
-                    )
-                )
-            elif scene_bounds and (start < scene_bounds[0] or end > scene_bounds[1]):
-                warnings.append(
-                    _lint_issue(
-                        "warning",
-                        idx,
-                        "crosses_scene_boundary",
-                        "Narration extends outside its midpoint scene boundary",
-                        start=start,
-                        end=end,
-                        scene_start=scene_bounds[0],
-                        scene_end=scene_bounds[1],
-                    )
-                )
-
-            frame_fact_times = _frame_fact_times_for_segment(
-                scenes_analysis, start, end
-            )
-            if (end - start) > CONFIG["visual_beat_max_seconds"] and len(
-                frame_fact_times
-            ) > CONFIG["visual_beat_max_facts"]:
-                warnings.append(
-                    _lint_issue(
-                        "warning",
-                        idx,
-                        "visual_beat_too_broad",
-                        "Narration spans many visual anchors; split or tighten timing so the voiceover stays tied to current pictures",
-                        start=start,
-                        end=end,
-                        duration=round(end - start, 2),
-                        frame_fact_times=[round(ts, 2) for ts in frame_fact_times[:8]],
-                    )
-                )
-
-            if mode == "cut":
-                requested_clip_id = seg.get("source_clip_id")
-                if requested_clip_id is not None:
-                    try:
-                        requested_clip_id = int(requested_clip_id)
-                    except (TypeError, ValueError):
-                        errors.append(
-                            _lint_issue(
-                                "error",
-                                idx,
-                                "invalid_source_clip_id",
-                                "source_clip_id must be an integer",
-                            )
-                        )
-                        continue
-                matches = _clip_matches_for_segment(seg, clip_plan, requested_clip_id)
-                if not matches:
-                    errors.append(
-                        _lint_issue(
-                            "error",
-                            idx,
-                            "outside_clip_plan",
-                            "Cut-mode narration must fall inside a selected clip",
-                            start=start,
-                            end=end,
-                        )
-                    )
-                elif len(matches) > 1 and requested_clip_id is None:
-                    errors.append(
-                        _lint_issue(
-                            "error",
-                            idx,
-                            "ambiguous_source_clip",
-                            "Repeated/overlapping clips require source_clip_id",
-                            start=start,
-                            end=end,
-                        )
-                    )
-                if len(matches) == 1:
-                    clip_start, clip_end = _clip_span(matches[0])
-                    if start < clip_start or end > clip_end:
-                        warnings.append(
-                            _lint_issue(
-                                "warning",
-                                idx,
-                                "crosses_clip_boundary",
-                                "Narration extends beyond its clip; it will be trimmed to the clip and may describe footage that was cut",
-                                start=start,
-                                end=end,
-                                clip_start=round(clip_start, 3),
-                                clip_end=round(clip_end, 3),
-                            )
-                        )
-
-            normalized.append(
-                {"index": idx, "start": start, "end": end, "char_count": char_count}
-            )
-
-    sorted_segments = sorted(normalized, key=lambda item: item["start"])
-    if isinstance(narration, list) and not sorted_segments:
-        errors.append(
-            _lint_issue(
-                "error",
-                None,
-                "empty_narration_file",
-                "narration.json must contain at least one valid narration segment",
-            )
-        )
-    for prev, curr in zip(sorted_segments, sorted_segments[1:]):
-        if curr["start"] < prev["end"]:
-            errors.append(
-                _lint_issue(
-                    "error",
-                    curr["index"],
-                    "time_overlap",
-                    "Segment overlaps the previous narration segment",
-                    previous_index=prev["index"],
-                    previous_end=prev["end"],
-                    start=curr["start"],
-                    end=curr["end"],
-                )
-            )
-
-    # Block-coverage check (full mode only; cut-mode density is measured on the mapped output
-    # timeline, not the source timestamps used here). Coverage is diagnostic, not a creative quota:
-    # flag wall-to-wall or sparse drafts so the Agent consciously checks the visual/audio board,
-    # plus missing original-audio gaps and fragmented one-sentence TTS blocks.
-    metrics = {}
-    if mode == "full" and len(sorted_segments) >= 2:
-        timeline_start = 0.0
-        timeline_end = sorted_segments[-1]["end"]
-        scene_ends = [scene["end"] for scene in scenes_analysis]
-        if scene_ends:
-            timeline_end = max(timeline_end, max(scene_ends))
-        span = max(0.0, timeline_end - timeline_start)
-        # Score coverage at the SAME conservative rate the writer is budgeted at
-        # (_recommended_char_budget uses speech_rate * speech_safety_margin * narration_speed),
-        # else the metric scores ~18% stricter than its own budget and false-flags under_narrated.
-        play_rate = (
-            CONFIG["speech_rate"] * CONFIG["speech_safety_margin"] * CONFIG["narration_speed"]
-        )
-        spoken = [s["char_count"] / play_rate for s in sorted_segments]
-        spoken_ends = [
-            min(sorted_segments[i]["end"], sorted_segments[i]["start"] + spoken[i])
-            for i in range(len(sorted_segments))
-        ]
-        # Measure the UNION of estimated playback intervals. Adjacent authored
-        # blocks can overlap the conservative text-duration estimate; summing them
-        # double-counted time and falsely called a recap wall-to-wall.
-        estimated_intervals = sorted(
-            (sorted_segments[i]["start"], spoken_ends[i])
-            for i in range(len(sorted_segments))
-            if spoken_ends[i] > sorted_segments[i]["start"]
-        )
-        merged_intervals = []
-        for start, end in estimated_intervals:
-            if merged_intervals and start <= merged_intervals[-1][1]:
-                merged_intervals[-1][1] = max(merged_intervals[-1][1], end)
-            else:
-                merged_intervals.append([start, end])
-        narrated_seconds = sum(end - start for start, end in merged_intervals)
-        coverage = narrated_seconds / span if span > 0 else 0.0
-        orig_min = CONFIG["original_block_min_seconds"]
-        orig_gaps = [sorted_segments[0]["start"] - timeline_start]
-        orig_gaps.extend(
-            sorted_segments[i + 1]["start"] - spoken_ends[i]
-            for i in range(len(sorted_segments) - 1)
-        )
-        orig_gaps.append(timeline_end - spoken_ends[-1])
-        original_blocks = sum(1 for g in orig_gaps if g >= orig_min)
-        avg_chars = sum(s["char_count"] for s in sorted_segments) / len(sorted_segments)
-        cov_target = CONFIG["narration_coverage_target"]
-        cov_max = CONFIG["narration_coverage_max"]
-        cov_min = CONFIG["narration_coverage_min"]
-        block_min_chars = CONFIG["narration_block_min_chars"]
-        metrics = {
-            "segment_count": len(sorted_segments),
-            "timeline_span_seconds": round(span, 2),
-            "narrated_seconds": round(narrated_seconds, 2),
-            "narration_coverage": round(coverage, 2),
-            "coverage_target": cov_target,
-            "original_block_count": original_blocks,
-            "avg_block_chars": round(avg_chars, 1),
-        }
-        if coverage > cov_max:
-            warnings.append(
-                _lint_issue(
-                    "warning",
-                    None,
-                    "no_original_blocks",
-                    "Narration is nearly wall-to-wall — the original audio never gets to breathe. Pull back at a "
-                    "few strong moments and write NO narration there so the original plays at full volume. "
-                    "Choose those moments by audio_owner, not by a fixed ratio.",
-                    narration_coverage=round(coverage, 2),
-                    coverage_max=cov_max,
-                )
-            )
-        elif coverage < cov_min:
-            warnings.append(
-                _lint_issue(
-                    "warning",
-                    None,
-                    "under_narrated",
-                    "Narration coverage is sparse. This is not automatically wrong: verify that every long gap is "
-                    "intentionally owned by original dialogue/action/ambience/music/silence in visual_audio_board.json. "
-                    "Only add a block when it has a specific narration job.",
-                    narration_coverage=round(coverage, 2),
-                    coverage_min=cov_min,
-                )
-            )
-        if original_blocks == 0 and span >= 3 * orig_min:
-            warnings.append(
-                _lint_issue(
-                    "warning",
-                    None,
-                    "no_original_breaks",
-                    "No deliberate original-audio blocks — narration runs end-to-end with no gap for a strong "
-                    "original moment (a key line, an action beat, the music). Leave a few multi-second gaps "
-                    "between blocks where the original plays alone.",
-                    original_block_min_seconds=orig_min,
-                )
-            )
-        if len(sorted_segments) >= 8 and avg_chars < block_min_chars:
-            warnings.append(
-                _lint_issue(
-                    "warning",
-                    None,
-                    "fragmented_beats",
-                    "Beats are fragmented into single short sentences; each is synthesized as a separate TTS "
-                    "utterance, which sounds choppy. Merge adjacent related sentences into one fluent BLOCK "
-                    "that completes a continuous thought; sentence count is not the target.",
-                    avg_block_chars=round(avg_chars, 1),
-                    block_min_chars=block_min_chars,
-                )
-            )
-
-    deslop_qc = analyze_deslop_qc(
-        [seg for seg in narration if isinstance(seg, dict)]
-        if isinstance(narration, list)
-        else [],
-        work_dir=work_dir,
-    )
-    for blocker in deslop_qc["blockers"]:
-        errors.append(
-            _lint_issue(
-                "error",
-                blocker["index"],
-                blocker["code"],
-                blocker["message"],
-                source=blocker["source"],
-                matches=blocker.get("matches"),
-                sentence=blocker.get("sentence"),
-            )
-        )
-
-    report = {
-        "ok": not errors,
-        "error_count": len(errors),
-        "warning_count": len(warnings),
-        "metrics": metrics,
-        "deslop_qc": deslop_qc,
-        "errors": errors,
-        "warnings": warnings,
-    }
-    if work_dir is not None:
-        Path(work_dir, "deslop_qc.json").write_text(
-            json.dumps(deslop_qc, ensure_ascii=False, indent=2), encoding="utf-8"
-        )
-        Path(work_dir, "narration_lint.json").write_text(
-            json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8"
-        )
-    return report
-
-
-def validate_narration_or_raise(
-    narration, scenes_analysis=None, *, clip_plan=None, mode="full", work_dir=None,
-    require_chronological=False,
-):
-    report = lint_narration(
-        narration, scenes_analysis, clip_plan=clip_plan, mode=mode, work_dir=work_dir,
-        require_chronological=require_chronological,
-    )
-    if report["errors"]:
-        sample = "; ".join(
-            f"#{e['index']}: {e['code']}" for e in report["errors"][:3]
-        )
-        raise ValueError(f"narration.json 预检失败: {sample}; 详见 narration_lint.json")
-    if report["warnings"]:
-        log(
-            f"narration lint: {len(report['warnings'])} warnings (see narration_lint.json)"
-        )
-    else:
-        log("narration lint: ok")
-    return report
-
-
-def _validate_narration_budget(narration, scenes_analysis):
-    """Trim lint-validated narration to its timing budgets; drop what cannot be spoken."""
-    del scenes_analysis  # scene boundaries are advisory (lint warns); authored timing is kept
-    cleaned = []
-    for raw in narration:
-        item = _normalise_narration_segment(raw)
-        max_chars = _recommended_char_budget(item["start"], item["end"])
-        if max_chars < 5:
-            log(f"  丢弃过短解说段 {item['start']:.1f}-{item['end']:.1f}s")
-            continue
-        if _text_char_count(item["narration"]) > max_chars * 1.25:
-            truncated = _truncate_at_sentence(item["narration"], max_chars)
-            if truncated and _text_char_count(truncated) >= 5:
-                log(f"  解说超预算，已截短: {item['start']:.1f}-{item['end']:.1f}s")
-                item["narration"] = truncated
-            else:
-                log(
-                    f"  解说超预算且无法安全截断，已丢弃: {item['start']:.1f}-{item['end']:.1f}s"
-                )
-                continue
-        item["narration"] = _clean_narration_punctuation(item["narration"])
-        stripped = item["narration"].strip()
-        if stripped and stripped[-1] in "，：、；,—":
-            item["narration"] = stripped.rstrip("，：、；,—") + "。"
-        cleaned.append(item)
-
-    cleaned.sort(key=lambda n: n["start"])
-    deduped = []
-    for item in cleaned:
-        if deduped and item["start"] < deduped[-1]["end"]:
-            prev = deduped[-1]
-            log(
-                f"  解说时间重叠: {item['start']:.1f}-{item['end']:.1f}s vs "
-                f"{prev['start']:.1f}-{prev['end']:.1f}s"
-            )
-            if _text_char_count(item["narration"]) > _text_char_count(
-                prev["narration"]
-            ):
-                deduped[-1] = item
-        else:
-            deduped.append(item)
-    return _post_dedup_narration(deduped)