1实现原理 · 为什么它能做到

进入条件被写死：只在旁白时间线稳定之后使用——避免与 audio-sync-assembly 抢「时序主导权」。

skills/captions-and-music-bed/SKILL.md

Use this skill after the narration timeline is stable.

这里在做什么：把「字幕/音乐的时序基准必须是已定稿的旁白」前置成使用前提；族内装配 skill 也把字幕生成安排在 narration-only 母版之后。

双重真源分工：措辞取用户脚本原文，时序取最终无音乐旁白母版；两者分开、互不代替。

skills/captions-and-music-bed/SKILL.md

- Use the user's script as wording source. - Use the final narration-only master as timing source.

这里在做什么：这是核心判据——「写什么」与「什么时候出」用不同来源，防止用转写文本改字、或用脚本行数估时间。

字幕时序铁律：首词即出、一次只显示一行、保留标点与大小写、静默 hook 与静默 CTA 不出字幕。

skills/captions-and-music-bed/SKILL.md

Start the caption when the first word is spoken.

这里在做什么：把最常见的「晚几个词」故障（failure-modes 也列了 Captions start several words late.）变成硬规则，并给恢复步骤（If captions are late → 查对齐来源、查静默是否挪动了全局时间）。

样式变更必须先做单帧预览再全量烧：挑一张视觉最密的帧出静态图，调字号/底板透明度/边距/宽度后才烧全片。

skills/captions-and-music-bed/SKILL.md

Preview style before burning the full video when style changes.

这里在做什么：把「样式是主观项、烧完再改很贵」这一经济性判据写进流程；references/caption-rules.md 重申 Preview on a visually busy frame before full burn-in.

音乐床的验收判据是「听得见」而不是「流里有」：给出 ducking 参数与混音链，并明确「技术上存在但听不见」要抬床或降阈值。

skills/captions-and-music-bed/SKILL.md

If music is "technically there" but inaudible, raise bed or reduce ducking threshold.

这里在做什么：针对「probe 显示有音轨、耳朵听不到」这类技术性通过、体验性失败给出可执行修正。

音源尾部策略：源曲早于视频结束就从「音乐上有用的」后段重启，留够时长不切掉最后一拍，缓淡出并保留用户要求的最终静音。

skills/captions-and-music-bed/SKILL.md

If the music source ends early, restart from a musically useful tail section.

这里在做什么：把循环/尾部选择处理成音乐判断而非机械 loop，并要求最终静音被显式保留（对应 failure-modes 的三条尾部故障）。

十步建床程序把主观音量决策逐一列出（源偏移、hook 音量、旁白床音量、密集解释段音量、停顿是否保持 ducked、CTA 音量、结束时间、淡出、limiter 混音）。

skills/captions-and-music-bed/SKILL.md

1. Probe source music duration. 2. Pick source start offset.

这里在做什么：音乐床最难的是「哪一段该多大声」，这里把它拆成 10 个必须逐一决定的点，避免用一条 amix 糊过去。

2核心能力

01ASS 字幕样式起点：仓库根模板给出 1920x1080、底部居中（Alignment=2）、Arial 44、半透明黑底板、MarginV=56 的 Caption 样式

02字幕分块规则：按自然短语/换气点/标点/最长行长/画面复杂度切；不得改变语义、不得添加脚本没有的标点

03时序来源优先级三级（最终旁白母版词级对齐 > 用户或转写短语时间戳 > 场景级已知时间加人工估计），并禁止用已过期的编辑前音频定时

04音乐 ducking 的可执行 FFmpeg 链：aresample/aformat/asplit 分旁白与侧链，sidechaincompress 参数化，amix 后接 alimiter

05音量策略按时段分级（hook 无旁白可大声、早期旁白下压、密集解释段更低且短停顿不抽高、结尾 CTA 可抬升后淡出）

06字幕故障恢复（迟到 / 过大）与音乐听点 QA（前 5 秒、首次旁白进入、密集解释段、长停顿、尾部重启、最后 5 秒）

3外部依赖

Kind	Dependency / Endpoint
cli	ffmpeg 滤镜链（aresample / aformat / asplit / sidechaincompress / amix / alimiter）用于旁白与音乐床的 ducking 混音
package	ASS（Advanced SubStation Alpha）字幕格式与样式头，由 templates/caption-style.ass 提供起点
package	仓库根脚本 scripts/build_ass_captions.py（把 JSON/CSV 的 start/end/text 事件展开为单行 ASS，默认每行 ≤58 字符）——本 skill 只点名样式模板未点名该脚本，脚本归属在仓库层
package	输入素材：用户提供的脚本文本、最终旁白母版、音乐源文件（本地资产，非外部服务）
package	字体 Arial（写死在 ASS 样式行的 Fontname 字段；渲染机无此字体会被 libass 替换字体，影响观感）

4管控建议与判定依据

建议配套管控措施

面向 Agent

分级或逐次授权，建议在沙箱运行

面向管理者

审批流程、可回滚、全程审计

判定依据（文件路径与关键语句摘要）

scripts/: 执行本地脚本或命令: （由宿主 agent 执行）ffmpeg：字幕烧录与音频混音链（aresample/aformat/asplit/sidechaincompress/
本地工作目录: 文件读写与工件输出: captions/ 下的 ASS 字幕文件

审计说明： 。skill 目录仅 SKILL.md + references/{caption-rules,music-ducking}.md（纯指令）；接触面是本地 CLI（ffmpeg 的 ducking/混音/烧字幕滤镜链）与本地读写（captions/*.ass、预览静帧、混音后成片、proof frame），符合蓝档。**没有把素材送外部服务**：全量扫描本 skill 目录内无 http(s):// 端点、无 fetch/requests、无 token/env 读取、无上传或生成服务调用。音乐源与旁白均为用户提供的本地文件，skill 不推荐、不下载、不上传任何音源。九件同族 skill 判级口径一致：目录内只有 SKILL.md（+ references），行为面是本地读写与本地 CLI，无端点、无凭证、无素材外发。

5第二遍独立确认

[ok] 「无外部依赖、素材不出网」是否成立 — 本目录正则扫描零命中 URL/fetch/token；音乐源与脚本均声明为用户提供（Music source rules 只讲 offset/duck/tail）。无上传、无生成服务、无账号额度消耗，不构成橙档。
[ok] ducking 片段是否是可执行 filter_complex — music-ducking.md 给的是四行完整链（asplit 出 narr/side 经 sidechaincompress 得 ducked 再 amix inputs=2 duration=first 后 alimiter=limit=0.95），参数（threshold=0.028:ratio=4:attack=18:release=260）具体非占位，可原样拼接。
[ok] ASS 模板能否被仓库脚本直接复用 — templates/caption-style.ass 结构与 scripts/build_ass_captions.py 的 header_from_template 期望一致：脚本取 Dialogue: 之前的部分当 header；模板 [Events] Format 行的字段数（Layer,Start,End,Style,Name,MarginL,MarginR,MarginV,Effect,Text）与脚本输出的 Dialogue 行匹配。
[discrepancy] 「本 skill 负责生成 ASS」是否被 SKILL.md 声明 — SKILL.md 只给样式起点与规则，未点名 scripts/build_ass_captions.py；把字幕文件从哪来写进脚本清单的是 render-qa-and-surgical-changes 与仓库 README。若只加载本件，agent 需自行决定生成方式（手写 ASS 或调仓库脚本）。
[discrepancy] 字体依赖是否被声明 — ASS 样式行写死 Fontname=Arial，但 SKILL.md 与 references 均未提示字体缺失风险；Linux 渲染机常无 Arial，libass 会回退替换字体，字号与行宽观感与预览不同。该风险真实存在但文档未覆盖。
[ok] QA 判据是否可自动验证 — SKILL.md 把听觉/视觉可读列为主判据（Check music is present and audible, not merely technically in the stream.），并给 probe 音频流作为辅助——即承认脚本只能验一半，另一半需人耳/人眼预览。

6结论

双重真源（措辞取脚本、时序取旁白母版）把字幕最容易出错的两件事分开治理

主观项一律「先预览后全量」，把返工成本压在单帧上

音乐验收标准写成 audible 并给出修正动作，直击「probe 通过但听不到」的假通过

FFmpeg 混音链完整可跑，参数具体（阈值/比率/启动释放/限幅）

失败模式清单可直接当 QA 勾选表（5 条音乐 + 4 条字幕类）

适合： 适合：旁白时间线已稳定的项目里做「字幕层 + 音乐层」——生成/样式化/预演/烧录字幕、字幕迟到或过大需要修、需要背景音乐在旁白下 ducking、需要音乐在指定时刻起止或保留最终静音、或需要针对密集解释段与停顿做音量策略的场合。

不适合： 不适合：① 旁白时序还没定稿（先用 audio-sync-assembly 定时间线，本 skill 第一行即以此为前提）；② 需要替用户选曲或下载音乐（skill 不含任何音源来源与端点）；③ 场景画面设计与动效（走 motion-design-systems / hyperframes-scene-builder）；④ 需要多行字幕或逐词高亮样式的场合——默认规则是单行单条，逐词样式需自行扩展 ASS 且不受本 skill 判据覆盖。

Install Agent-Ready

① Verified Mirror 2026-09-28

Option A · Direct DownloadDownload captions-and-music-bed.tar.gz

sha256: 07c0b567449820c1…

Option B · Copy Guide for Agent

install.json

agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。

② Upstream GitHub

GitHub Repo ↗

Pinned to commit f6b043d9fd.