Home / All Skills / Content & Media Creation / captions-and-music-bed
English (EN)简体中文 (ZH)日本語 (JA)
Content & Media Creation · saranambiar/hyperframes-video-agent-skills

captions-and-music-bed

Generate, style, preview, and burn captions, and build music/percussion beds with ducking, loop/tail selection, fade-outs, and final silence. Use when captions are requested, captions are out of sync, subtitle style needs approval, background music competes with voiceover, or music must start/end at exact moments.

L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandWrite FileDual-pass Audit
Author saranambiarGitHub saranambiar/hyperframes-video-agent-skills ↗Stars 48License Apache-2.0（仓库根 LICENSE 为 Apache License Version 2.0；GitHub API license.spdx_id = Apache-2.0）Commit f6b043d9fd
Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

Hardcoded entry condition: Use strictly after the narration timeline is stabilized—preventing timing authority conflicts with audio-sync-assembly.

skills/captions-and-music-bed/SKILL.md
Use this skill after the narration timeline is stable.
What this does: Establishes 'caption/music timing must be anchored to the finalized narration' as a prerequisite; the family assembly skill also schedules caption generation after the narration-only master.

Dual single-source-of-truth division: Verbiage is sourced from the original user script, while timing is taken from the final music-free narration master; the two remain distinct and never substitute for one another.

skills/captions-and-music-bed/SKILL.md
- Use the user's script as wording source. - Use the final narration-only master as timing source.
What this does: Serves as the core criterion—'what is displayed' and 'when it appears' rely on distinct sources, preventing transcription text from altering words or script line counts from approximating timing.

Ironclad caption timing rules: Captions appear at the very first word, only one line is displayed at a time, punctuation and casing are preserved, and silent hooks or silent CTAs show no captions.

skills/captions-and-music-bed/SKILL.md
Start the caption when the first word is spoken.
What this does: Turns the most common 'starts several words late' defect (listed in failure-modes as 'Captions start several words late.') into a hard constraint and provides recovery procedures (If captions are late → verify alignment source, check whether silence shifted the global timeline).

Style modifications require a single-frame preview before full burn-in: Pick the most visually dense frame for a static render to tune font size, bounding box opacity, margins, and width prior to burning the entire video.

skills/captions-and-music-bed/SKILL.md
Preview style before burning the full video when style changes.
What this does: Embeds the economic reality that 'style is subjective and re-burning the full video is expensive' directly into the workflow; references/caption-rules.md reiterates 'Preview on a visually busy frame before full burn-in.'

Music bed acceptance is judged by being 'audible' rather than merely 'present in the stream': Provides ducking parameters and mixing chains, explicitly mandating raising the bed or lowering thresholds if technically present but inaudible.

skills/captions-and-music-bed/SKILL.md
If music is "technically there" but inaudible, raise bed or reduce ducking threshold.
What this does: Provides actionable remediation against 'probe confirms the audio stream exists, but human ears cannot hear it' false passes (technically present, experientially failed).

Audio source tail strategy: If the source track ends earlier than the video, restart it from a musically viable later section, reserve enough duration without truncating the final beat, apply a smooth fade-out, and preserve user-requested trailing silence.

skills/captions-and-music-bed/SKILL.md
If the music source ends early, restart from a musically useful tail section.
What this does: Treats looping/tail selection as a musical judgment rather than a mechanical loop, explicitly requiring trailing silence to be maintained (addressing the three tail failure modes).

A ten-step bed construction procedure enumerates subjective volume decisions (source offset, hook level, narration bed level, dense explanation level, ducking behavior across pauses, CTA level, end point, fade-out, limiter mix).

skills/captions-and-music-bed/SKILL.md
1. Probe source music duration. 2. Pick source start offset.
What this does: Solves the hardest problem in music bed creation—'how loud each segment should be'—by breaking it into 10 explicit decision points instead of glossing over it with a single generic amix filter.

2Core Capabilities

01ASS caption styling baseline: The repository root template specifies a Caption style at 1920x1080, bottom-centered (Alignment=2), Arial 44, semi-transparent black backing box, and MarginV=56.
02Caption chunking rules: Split by natural phrases, breathing pauses, punctuation, maximum line length, and visual complexity; preserve exact semantics and never add punctuation absent from the script.
03Three-tier timing source hierarchy (final narration master word-level alignment > user or transcription phrase timestamps > scene-level known timing with manual estimation); timing against stale pre-edit audio is strictly forbidden.
04Actionable FFmpeg music ducking chain: aresample/aformat/asplit split narration and sidechain, sidechaincompress provides parameterized ducking, followed by amix and alimiter.
05Tiered volume strategy across segments (loud during voiceless hooks, suppressed during early narration, lowered further during dense explanations without pumping on short pauses, raised for the closing CTA before fading out).
06Caption troubleshooting (late / oversized) and music listening QA checkpoints (first 5s, initial narration entry, dense explanation segments, long pauses, tail restarts, final 5s).

3External Dependencies

KindDependency / Endpoint
cliffmpeg 滤镜链（aresample / aformat / asplit / sidechaincompress / amix / alimiter）用于旁白与音乐床的 ducking 混音
packageASS（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 替换字体，影响观感）

4Recommended Governance & Evidence

Suggested Controls for Safe Operation
For Agent Runtime
Graded/per-use authorization, sandbox recommended
For Administrators
Approval workflow, rollback support, full audit
Evidence & Triggers (File Paths & Excerpts)
  • scripts/: Executes local scripts or commands: (Executed by host agent) ffmpeg: caption burn-in and audio mixing chains (aresample/aformat/asplit/sidechaincompress/)
  • 本地工作目录: File read/write & artifact generation: ASS caption files under captions/
Audit Notes: The skill directory contains only SKILL.md + references/{caption-rules,music-ducking}.md (pure instructions); its operational surface is restricted to local CLI (ffmpeg ducking/mixing/caption burn-in filter chains) and local I/O (captions/*.ass, preview static frames, mixed final videos, proof frames), matching the Blue profile. **No assets are transmitted to external services**: A full audit of the skill directory reveals zero http(s):// endpoints, zero fetch/requests calls, zero token/env accesses, and zero upload/generation service integrations. Music and narration tracks are strictly local user-provided files; the skill neither recommends, downloads, nor uploads audio assets. Classification criteria are consistent across all nine sister skills: only SKILL.md (+ references) present, behavior strictly limited to local I/O and local CLI, with zero endpoints, credentials, or asset egress.

5Second-Pass Verification

  • [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 音频流作为辅助——即承认脚本只能验一半，另一半需人耳/人眼预览。

6Verdict & Scenarios

  • Dual sources of truth (verbiage from script, timing from narration master) cleanly decouple the two most error-prone aspects of captioning.
  • All subjective styling follows 'preview first, full burn second', keeping rework costs confined to a single frame.
  • Music acceptance criteria are strictly defined as audible with concrete corrective actions, directly resolving false passes where audio passes probe checks but cannot be heard.
  • Provides fully executable FFmpeg mixing chains with specific, tuned parameters (threshold, ratio, attack/release, limiting).
  • Failure-modes inventory functions directly as a QA checklist (5 music items + 4 caption items).
    • Best for: Suitable for: Implementing caption and music layers once the narration timeline is stable—generating, styling, previewing, and burning captions; fixing late or oversized subtitles; ducking background music under narration; timing music to exact moments or preserving trailing silence; and crafting segment-specific volume curves for dense explanations and pauses.
    Not for: Not suitable for: (1) Projects where the narration timeline is not finalized (use audio-sync-assembly first; this skill strictly presupposes that step); (2) Selecting or downloading music tracks for the user (skill includes no music sources or endpoints); (3) Scene visual design and motion graphics (handled by motion-design-systems / hyperframes-scene-builder); (4) Multi-line captions or word-by-word karaoke highlighting styles—the default standard is single-line single-cue, and word-by-word styles require custom ASS extensions not covered by this skill's acceptance criteria.
    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
    Agents automatically download and verify mirrors from this JSON guide.
    ② Upstream GitHub
    GitHub Repo ↗
    Pinned to commit f6b043d9fd.