Back to Details

skill-captions

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skill-字幕

Skill-字幕

Separate subtitle timing from subtitle appearance:
  • Let 
    ra-audio-to-subtitles
    own ASR, phrase grouping, timestamps, SRT/VTT, and 
    caption-qc.json
    .
  • Let this skill own typography, panel geometry, fixed anchoring, preview, overlay rendering, burn-in, and render QC.
  • Never estimate production timing from character count, scene duration, or TTS segment duration.
将字幕时间轴与字幕外观分离：
  • 让 
    ra-audio-to-subtitles
    负责 ASR、短语分组、时间戳、SRT/VTT 和 
    caption-qc.json
    。
  • 让本 skill 负责字体排版、面板几何、固定锚定、预览、叠加渲染、烧录和渲染 QC。
  • 绝不根据字符数、场景时长或 TTS 分段时长估算生产级时间轴。

Required workflow

必需工作流

  1. Lock the final narration audio or final merged video.
  2. Run 
    ra-audio-to-subtitles
    unless the project already has the canonical caption artifacts described in 
    references/timing-contract.md
    .
  3. Require 
    caption-qc.json
    to report 
    status: pass
    .
  4. Select a style from 
    references/style-registry.json
    . Use 
    anchor-dark
    when the contract does not specify another style.
  5. Generate a representative still preview before rendering a full video.
  6. Inspect the preview against 
    references/layout-qc.md
    .
  7. Render the captioned derivative. Preserve the clean video and portable SRT/VTT.
  8. Run 
    scripts/validate_caption_render.py
    and archive its JSON report.
  1. 锁定最终旁白音频或最终合并视频。
  2. 除非项目已经包含 
    references/timing-contract.md
    所描述的规范字幕产物，否则运行 
    ra-audio-to-subtitles
    。
  3. 要求 
    caption-qc.json
    报告 
    status: pass
    。
  4. 从 
    references/style-registry.json
    中选择样式。如果契约未指定其他样式，则使用 
    anchor-dark
    。
  5. 在渲染完整视频之前，先生成一张有代表性的静帧预览。
  6. 根据 
    references/layout-qc.md
    检查预览效果。
  7. 渲染带字幕的衍生版本。保留无字幕视频和可移植的 SRT/VTT。
  8. 运行 
    scripts/validate_caption_render.py
    并归档其 JSON 报告。

Registered styles

已注册样式

anchor-dark
reproduces the approved Kimi K3 subtitle treatment: STHeiti Medium, warm white text, a tight charcoal translucent rounded panel, no text stroke, no text shadow, no large panel shadow, and a fixed bottom-center anchor. Read 
references/style-anchor-dark.md
before changing its values.
anchor-light
keeps the exact same typography, size, padding, width, bottom anchor, line fitting, and resolution scaling as 
anchor-dark
. Only its surface changes: dark ink on a warm-white translucent panel with a fine border and subtle soft shadow. Read 
references/style-anchor-light.md
before changing its values. This is the second registered style; 
anchor-dark
remains the default.
Scale every 1080p metric by 
target_height / 1080
. Render 4K captions at 2× their 1080p measurements; never upscale a rasterized 1080p subtitle layer.
anchor-dark
复现已批准的 Kimi K3 字幕样式：STHeiti Medium、暖白色文字、紧凑的炭黑色半透明圆角面板、无文字描边、无文字阴影、无大面积面板阴影，并采用固定的底部居中锚点。在修改其数值前，请阅读 
references/style-anchor-dark.md
。
anchor-light
保持与 
anchor-dark
完全相同的字体排版、尺寸、内边距、宽度、底部锚点、行适配和分辨率缩放。仅表层样式发生变化：改为暖白色半透明面板上的深色文字，并添加细边框和轻微柔和阴影。在修改其数值前，请阅读 
references/style-anchor-light.md
。这是第二个已注册样式；
anchor-dark
仍为默认样式。
将每个 1080p 度量值按 
target_height / 1080
缩放。以 1080p 度量值的两倍渲染 4K 字幕；绝不放大多栅格化的 1080p 字幕图层。

Commands

命令

Preview a QC-passed project:
bash
python3 .claude/skills/skill-captions/scripts/render_captions.py \
  final.mp4 media/captions/captions.json \
  --qc media/captions/caption-qc.json \
  --preview qc/caption-preview.png \
  --preview-only
Burn the default style:
bash
python3 .claude/skills/skill-captions/scripts/render_captions.py \
  final-clean.mp4 media/captions/captions.json \
  --qc media/captions/caption-qc.json \
  --out renders/final-captioned.mp4 \
  --preview qc/caption-preview.png
Burn the light translucent style:
bash
python3 .claude/skills/skill-captions/scripts/render_captions.py \
  final-clean.mp4 media/captions/captions.json \
  --qc media/captions/caption-qc.json \
  --style anchor-light \
  --out renders/final-captioned.mp4 \
  --preview qc/caption-preview.png
Skip an interval that already contains burned captions:
bash
python3 .claude/skills/skill-captions/scripts/render_captions.py \
  final-clean.mp4 media/captions/captions.json \
  --qc media/captions/caption-qc.json \
  --exclude 0:23.936 \
  --out renders/final-captioned.mp4
Create a reusable transparent caption band:
bash
python3 .claude/skills/skill-captions/scripts/render_captions.py \
  final-clean.mp4 media/captions/captions.json \
  --qc media/captions/caption-qc.json \
  --overlay-out renders/caption-band.mov
Validate the result:
bash
python3 .claude/skills/skill-captions/scripts/validate_caption_render.py \
  --source final-clean.mp4 \
  --render renders/final-captioned.mp4 \
  --captions media/captions/captions.json \
  --qc media/captions/caption-qc.json \
  --out qc/caption-render-qc.json
预览一个已通过 QC 的项目：
bash
python3 .claude/skills/skill-captions/scripts/render_captions.py \
  final.mp4 media/captions/captions.json \
  --qc media/captions/caption-qc.json \
  --preview qc/caption-preview.png \
  --preview-only
烧录默认样式：
bash
python3 .claude/skills/skill-captions/scripts/render_captions.py \
  final-clean.mp4 media/captions/captions.json \
  --qc media/captions/caption-qc.json \
  --out renders/final-captioned.mp4 \
  --preview qc/caption-preview.png
烧录浅色半透明样式：
bash
python3 .claude/skills/skill-captions/scripts/render_captions.py \
  final-clean.mp4 media/captions/captions.json \
  --qc media/captions/caption-qc.json \
  --style anchor-light \
  --out renders/final-captioned.mp4 \
  --preview qc/caption-preview.png
跳过已包含烧录字幕的时间区间：
bash
python3 .claude/skills/skill-captions/scripts/render_captions.py \
  final-clean.mp4 media/captions/captions.json \
  --qc media/captions/caption-qc.json \
  --exclude 0:23.936 \
  --out renders/final-captioned.mp4
创建可复用的透明字幕带：
bash
python3 .claude/skills/skill-captions/scripts/render_captions.py \
  final-clean.mp4 media/captions/captions.json \
  --qc media/captions/caption-qc.json \
  --overlay-out renders/caption-band.mov
验证结果：
bash
python3 .claude/skills/skill-captions/scripts/validate_caption_render.py \
  --source final-clean.mp4 \
  --render renders/final-captioned.mp4 \
  --captions media/captions/captions.json \
  --qc media/captions/caption-qc.json \
  --out qc/caption-render-qc.json

Hard rules

硬性规则

  • Use the final audio/video as the only timing source.
  • Consume 
    captions.json
    start/end values directly.
  • Refuse final burn-in when caption QC is missing or failed.
  • Keep a fixed bottom anchor. Let multiline panels grow upward.
  • Keep captions inside the frame and clear of titles, UI, faces, and PiP.
  • Keep English model/product tokens intact.
  • Preserve one canonical caption timeline across renderers.
  • Keep the clean master; a burned-caption MP4 is a derivative.
  • For a new or materially changed style, show a short preview before the full render.
  • Do not add karaoke, behind-person typography, VFX captions, or animated hero words unless the user explicitly requests the separate 
    embedded-captions
    lane.
  • 仅使用最终音频或视频作为时间轴来源。
  • 直接使用 
    captions.json
    中的 start/end 值。
  • 如果字幕 QC 缺失或未通过，则拒绝执行最终烧录。
  • 保持固定的底部锚点。允许多行面板向上扩展。
  • 确保字幕位于画面内，并避开标题、UI、人脸和 PiP。
  • 保持英文模型和产品词元原样。
  • 在所有渲染器之间共用一条规范字幕时间轴。
  • 保留无字幕母版；烧录字幕的 MP4 是衍生版本。
  • 对于新样式或发生实质变化的样式，在完整渲染之前先展示简短预览。
  • 除非用户明确要求使用独立的 
    embedded-captions
    工作流，否则不要添加 karaoke、人物背后排版、VFX 字幕或动画化重点词。

Integration contract

集成契约

Video orchestrators should call this skill after 
ra-audio-to-subtitles
. Handoff contracts may set 
caption_style
to 
anchor-dark
or 
anchor-light
; otherwise use 
anchor-dark
. Renderers may reproduce the registered CSS in Remotion or HyperFrames, but must preserve the style metrics and fixed-anchor behavior.
视频编排器应在 
ra-audio-to-subtitles
之后调用本 skill。交接契约可以将 
caption_style
设置为 
anchor-dark
或 
anchor-light
；否则使用 
anchor-dark
。
渲染器可以在 Remotion 或 HyperFrames 中复现已注册的 CSS，但必须保留样式度量值和固定锚点行为。