Back to Details

ra-local-talking-head-cut

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

本地口播精剪

本地口播精剪

Deliver a reproducible local workflow, not an editing product. Keep upstream skills untouched and write every job under the source project's engineering directory.
交付可复现的本地工作流，而不是剪辑产品。保持上游 skill 不变，并将每个任务写入源项目的工程 目录。

Required workflow

必需工作流

  1. Probe the source. Preserve width, height, and frame rate unless the user explicitly requests a delivery conversion.
  2. Transcribe with the installed 
    video-use/helpers/transcribe.py
    using 
    volc.seedasr.auc
    and word timestamps. Reuse its cached normalized JSON.
  3. Run 
    scripts/prepare_transcript.py
    with 
    references/default-glossary.json
    . It must create 
    review.md
    , 
    precut-review.srt
    , 
    corrected-script.md
    , 
    uncertain-terms.md
    , and 
    subtitle-approval.json
    .
  4. Give the user the source video plus 
    precut-review.srt
    and the readable review. Correct only well-supported terminology. Never guess an uncertain model or product name. Stop here and wait for explicit user approval. Do not build an EDL or render a cut while approval is pending.
  5. Resolve uncertain terms by adding confirmed mappings to a job-local copy of the glossary, then rerun preparation so both the script and pre-cut SRT are regenerated together. Preparation always resets approval. After the user confirms the regenerated SRT, set 
    subtitle-approval.json
    to 
    approved: true
    , record the confirmation time, and leave 
    unresolved_terms
    empty. Never keep approval across regeneration.
  6. Write optional 
    decisions.json
    for semantic deletions. Delete repeated starts and failed takes before their later complete version; preserve unique meaning. Use normalized word indexes only inside artifacts, never in the user-facing report.
  7. Run 
    scripts/build_edl.py
    with the approval file. The script must refuse to continue unless subtitles are approved and all uncertainty is resolved. Its default pacing keeps pauses up to 550 ms, compresses longer pauses to 380-450 ms, removes only unambiguous 
    呃/额
    , and pads source head/tail. Do not replace this with blanket deletion of every pause above 200 ms.
  8. Run 
    scripts/render_cut.py
    without transitions to create a hard-cut preview. It preserves source dimensions/fps, applies 15 ms audio fades at every cut, uses light dialogue cleanup, and performs two-pass loudness normalization to -16 LUFS / -1.5 dBTP. Stronger denoise or gates are candidates, not defaults: reject a candidate when the same ASR alignment test drops by more than 0.01 or falls below 0.90.
  9. Run 
    scripts/analyze_visual_cuts.py
    on the hard-cut preview. Inspect its contact sheet and use only its recommended 80-120 ms transitions, capped at three per video. Rerender with 
    --transitions
    only when a valid semantic cut also has a large visual discontinuity. Do not add blanket transitions.
  10. Run 
    scripts/qc.py
    against the chosen clean final MP4 and pass it the same transition JSON when transitions were used. Require matching dimensions/fps, valid audio/video, expected duration, and loudness within the gate. Inspect both the general and transition contact sheets.
  11. Run 
    scripts/generate_final_subtitles.py
    against the exact final MP4 and approved 
    corrected-script.md
    . It delegates timing/alignment to 
    ra-audio-to-subtitles
    and refuses delivery unless 
    caption-qc.json
    is PASS. ASR is the timing source; approved script text is the display source. Never reuse 
    precut-review.srt
    after timeline edits.
  12. When the deliverable needs visible subtitles, run 
    skill-captions
    with the final 
    captions.json
    and PASS 
    caption-qc.json
    . Use 
    anchor-dark
    unless the contract selects another style. Preview a representative frame, burn the derivative, and require 
    caption-render-qc.json
    to pass. Keep the clean rough cut and portable SRT.
  1. 检查源文件。除非用户明确要求进行交付格式转换， 否则保留宽度、高度和帧率。
  2. 使用已安装的 
    video-use/helpers/transcribe.py
    ，通过 
    volc.seedasr.auc
    生成带词级时间戳的转写结果。复用其缓存的 标准化 JSON。
  3. 运行 
    scripts/prepare_transcript.py
    ，并传入 
    references/default-glossary.json
    。它必须创建 
    review.md
    、 
    precut-review.srt
    、
    corrected-script.md
    、
    uncertain-terms.md
    和 
    subtitle-approval.json
    。
  4. 向用户提供源视频、
    precut-review.srt
    和可读的审阅稿。 仅修正有充分依据的术语。绝不猜测尚不确定的模型或产品名称。 在此停止并等待用户明确批准。 在字幕批准完成前，不得构建 EDL 或渲染剪辑。
  5. 通过将已确认的映射添加到任务本地的 glossary 副本来解决不确定术语， 然后重新运行准备流程，使脚本和剪辑前 SRT 一并重新生成。准备流程始终 会重置批准状态。在用户确认重新生成的 SRT 后，将 
    subtitle-approval.json
    设为 
    approved: true
    ，记录确认时间，并确保 
    unresolved_terms
    为空。重新生成时绝不能保留批准状态。
  6. 编写可选的 
    decisions.json
    以记录语义删除。删除重复开头和失败 录制的片段，以保留后续完整版本；不要丢失独有含义。规范化词索引只能 用于 artifact 内部，绝不能出现在面向用户的报告中。
  7. 使用批准文件运行 
    scripts/build_edl.py
    。除非字幕已批准且所有 不确定项均已解决，否则脚本必须拒绝继续。默认节奏会保留不超过 550 ms 的停顿，将更长的停顿压缩至 380-450 ms，只删除明确无歧义的 
    呃/额
    ，并为源视频首尾添加填充。不得改为一刀切删除所有超过 200 ms 的停顿。
  8. 运行 
    scripts/render_cut.py
    且不使用 transition，以生成 hard-cut 预览。 它保留源尺寸/fps，在每个剪切点应用 15 ms 音频淡入淡出，执行轻度 对白清理，并进行两遍响度标准化至 -16 LUFS / -1.5 dBTP。更强的 降噪或 gate 仅作为候选项，而非默认设置：如果同一 ASR 对齐测试的 得分下降超过 0.01 或低于 0.90，则拒绝该候选项。
  9. 对 hard-cut 预览运行 
    scripts/analyze_visual_cuts.py
    。检查其 contact sheet，仅使用其推荐的 80-120 ms transition，且每个视频最多 三个。只有当有效的语义剪切点同时存在较大的视觉不连续时，才使用 
    --transitions
    重新渲染。不得批量添加 transition。
  10. 对选定的无字幕最终 MP4 运行 
    scripts/qc.py
    ；如果使用了 transition， 则向其传入同一份 transition JSON。要求尺寸/fps 匹配、音视频有效、 时长符合预期，且响度处于门限内。检查常规 contact sheet 和 transition contact sheet。
  11. 针对最终 MP4 文件本身和已批准的 
    corrected-script.md
    运行 
    scripts/generate_final_subtitles.py
    。它将时间轴生成和对齐工作委托给 
    ra-audio-to-subtitles
    ，除非 
    caption-qc.json
    为 PASS，否则拒绝 交付。ASR 是时间来源；已批准的脚本文本是显示文本来源。剪辑时间轴 变更后，绝不重复使用 
    precut-review.srt
    。
  12. 当交付物需要可见字幕时，使用最终的 
    captions.json
    和 PASS 的 
    caption-qc.json
    运行 
    skill-captions
    。除非 contract 指定其他样式， 否则使用 
    anchor-dark
    。预览一帧代表性画面，渲染烧录字幕的衍生 版本，并要求 
    caption-render-qc.json
    通过。保留无字幕的粗剪版本 和便携 SRT。

Commands

命令

bash
SKILL_DIR="<this skill directory>"
JOB="<engineering job directory>"
WORDS="$JOB/transcripts/<source-name>.json"

python3 "$SKILL_DIR/scripts/prepare_transcript.py" \
  "$WORDS" --out-dir "$JOB/transcript-review" \
  --glossary "$SKILL_DIR/references/default-glossary.json"

python3 "$SKILL_DIR/scripts/build_edl.py" \
  <source.mp4> "$WORDS" --out "$JOB/edl.json" \
  --approval "$JOB/transcript-review/subtitle-approval.json" \
  --decisions "$JOB/decisions.json"

python3 "$SKILL_DIR/scripts/render_cut.py" \
  "$JOB/edl.json" --out "$JOB/local-hard-cut-preview.mp4"

CODEX_PY="$HOME/.cache/codex-runtimes/codex-primary-runtime/dependencies/python/bin/python3"
"$CODEX_PY" "$SKILL_DIR/scripts/analyze_visual_cuts.py" \
  "$JOB/local-hard-cut-preview.mp4" --edl "$JOB/edl.json" \
  --out-dir "$JOB/visual-cut-qc"

python3 "$SKILL_DIR/scripts/render_cut.py" \
  "$JOB/edl.json" --out "$JOB/local-benchmark.mp4" \
  --transitions "$JOB/visual-cut-qc/visual-cut-qc.json"

python3 "$SKILL_DIR/scripts/qc.py" \
  <source.mp4> "$JOB/local-benchmark.mp4" \
  --edl "$JOB/edl.json" \
  --transitions "$JOB/visual-cut-qc/visual-cut-qc.json" \
  --out-dir "$JOB/qc"

python3 "$SKILL_DIR/scripts/generate_final_subtitles.py" \
  "$JOB/local-benchmark.mp4" \
  --script "$JOB/transcript-review/corrected-script.md" \
  --approval "$JOB/transcript-review/subtitle-approval.json" \
  --out-dir "$JOB/captions"

"$CODEX_PY" ".claude/skills/skill-captions/scripts/render_captions.py" \
  "$JOB/local-benchmark.mp4" "$JOB/captions/captions.json" \
  --qc "$JOB/captions/caption-qc.json" --style anchor-dark \
  --out "$JOB/local-benchmark-captioned.mp4" \
  --preview "$JOB/qc/caption-preview.png" --preview-at 15
Omit 
--decisions
when no semantic repeats or failed takes exist.
bash
SKILL_DIR="<this skill directory>"
JOB="<engineering job directory>"
WORDS="$JOB/transcripts/<source-name>.json"

python3 "$SKILL_DIR/scripts/prepare_transcript.py" \
  "$WORDS" --out-dir "$JOB/transcript-review" \
  --glossary "$SKILL_DIR/references/default-glossary.json"

python3 "$SKILL_DIR/scripts/build_edl.py" \
  <source.mp4> "$WORDS" --out "$JOB/edl.json" \
  --approval "$JOB/transcript-review/subtitle-approval.json" \
  --decisions "$JOB/decisions.json"

python3 "$SKILL_DIR/scripts/render_cut.py" \
  "$JOB/edl.json" --out "$JOB/local-hard-cut-preview.mp4"

CODEX_PY="$HOME/.cache/codex-runtimes/codex-primary-runtime/dependencies/python/bin/python3"
"$CODEX_PY" "$SKILL_DIR/scripts/analyze_visual_cuts.py" \
  "$JOB/local-hard-cut-preview.mp4" --edl "$JOB/edl.json" \
  --out-dir "$JOB/visual-cut-qc"

python3 "$SKILL_DIR/scripts/render_cut.py" \
  "$JOB/edl.json" --out "$JOB/local-benchmark.mp4" \
  --transitions "$JOB/visual-cut-qc/visual-cut-qc.json"

python3 "$SKILL_DIR/scripts/qc.py" \
  <source.mp4> "$JOB/local-benchmark.mp4" \
  --edl "$JOB/edl.json" \
  --transitions "$JOB/visual-cut-qc/visual-cut-qc.json" \
  --out-dir "$JOB/qc"

python3 "$SKILL_DIR/scripts/generate_final_subtitles.py" \
  "$JOB/local-benchmark.mp4" \
  --script "$JOB/transcript-review/corrected-script.md" \
  --approval "$JOB/transcript-review/subtitle-approval.json" \
  --out-dir "$JOB/captions"

"$CODEX_PY" ".claude/skills/skill-captions/scripts/render_captions.py" \
  "$JOB/local-benchmark.mp4" "$JOB/captions/captions.json" \
  --qc "$JOB/captions/caption-qc.json" --style anchor-dark \
  --out "$JOB/local-benchmark-captioned.mp4" \
  --preview "$JOB/qc/caption-preview.png" --preview-at 15
不存在语义重复或失败录制片段时，省略 
--decisions
。

Decision gates

决策门控

  • Prefer missed filler over lost meaning.
  • Treat transcript correction and playback deletion as separate operations.
  • Do not create an EDL while subtitle approval is false or unresolved terms remain.
  • Treat 
    precut-review.srt
    as source-timeline review material only.
  • Do not burn captions while 
    caption-qc.json
    is absent or not PASS.
  • Do not accept audio cleanup whose same-input ASR coverage regresses by more than one percentage point, even when it sounds superficially quieter.
  • Do not add transitions to every cut; a transition requires both a valid semantic boundary and measured visual discontinuity.
  • Do not call a rough-cut subtitle timeline production-ready.
  • Do not deliver when 
    cut-qc.json
    reports 
    fail
    .
  • Keep intermediates in 
    01-内容生产/视频工作台/制作中/<日期-主题>/
    ; archive only the user-approved final under 
    视频工作台/已制作/月上旬或月下旬/日期-主题/
    .
Read references/artifact-contract.md when integrating another renderer or modifying artifact schemas.
  • 宁可保留未删的填充词，也不要丢失含义。
  • 将转写稿校正与播放片段删除视为两个独立操作。
  • 当字幕未获批准或仍有未解决术语时，不得创建 EDL。
  • 仅将 
    precut-review.srt
    用作源时间轴的审阅材料。
  • 当 
    caption-qc.json
    不存在或结果不是 PASS 时，不得烧录字幕。
  • 即使音频清理后听感表面上更安静，也不得接受会导致相同输入下 ASR 覆盖率下降超过一个百分点的方案。
  • 不要给每个剪切点添加 transition；transition 必须同时具备有效的语义边界和经测量的视觉不连续。
  • 不要将粗剪字幕时间轴称为已达到生产交付标准。
  • 当 
    cut-qc.json
    报告 
    fail
    时，不得交付。
  • 将中间产物保存在 
    01-内容生产/视频工作台/制作中/<日期-主题>/
    ；仅将用户批准的最终产物归档到 
    视频工作台/已制作/月上旬或月下旬/日期-主题/
    。
在集成其他 renderer 或修改 artifact schema 时，阅读 references/artifact-contract.md。