1仕組みと動作原理
タイミングの真実のソース（Source of Truth）は「最新の承認済みナレーション音声＋シーンレンダリング」に厳格に固定され、古い完成品からのタイミング逆算は明示的に禁止されています。これは、全工程におけるすべてのリタイミング、字幕、音楽の決定における共通の基準となります。
skills/audio-sync-assembly/SKILL.md
- Use the latest approved narration audio as timing source.
ここで行っていること：「何を基準とするか」を第一の Source of Truth として定義しています。ファミリ内の失敗パターンリストにある「source renders and audio clips が存在する限り、古い完成版 MP4 からタイミングを逆算してはならない」に対応しており、バージョン改訂ごとに前回の完成品から推論を重ねることで生じる誤差の蓄積を防ぎます。
「最小限の介入」を徹底：全体の一律速度変更をデフォルトとせず、シーンの特性に応じた段階別戦略（全区間 setpts / 区間リタイミング / 無音＋静止フレーム挿入 / わずかな atempo 調整 / プロダクトモーメント直前のみのリタイミング）を適用します。
skills/audio-sync-assembly/SKILL.md
Choose the smallest timing intervention:
ここで行っていること：本スキルの最も中核的なプロダクション基準です。まず「最小の時間的介入は何か」を問い、「動画全体のリタイミング」を最も典型的な誤り（Common Mistakes の筆頭）として位置づけています。
いかなる決定の前にもプローブを実施：ffprobe またはリポジトリ備え付けのプローブスクリプトを使用し、各クリップの尺、フレームレート、解像度、音声トラックの有無、サンプリングレート、チャンネル数を事前に測定します。
skills/audio-sync-assembly/SKILL.md
- Duration. - Frame rate. - Resolution. - Audio stream presence.
ここで行っていること：「計算する前にまず測定する」をワークフローの最初のステップとして定着させ、勘による setpts 比率設定を排除します。同じセクション内で ffprobe と「this repo's media probe script」の2つの実行パスを提示しています。
アセンブリ順序において、字幕を「BGMなしナレーションマスター」に固定：narration-only master を先に組み立て、そこから字幕生成・焼き込み、BGMトラック構築、音声ミキシングを行い、最終出力およびプレビューを出力します。
skills/audio-sync-assembly/SKILL.md
3. Generate captions from narration-only master.
ここで行っていること：「BGM入りの完成版に合わせて字幕を作成する」ことで生じるタイミングのズレを工程順序によって根絶します。captions-and-music-bed との分担境界でもあります（後者は冒頭で「ナレーションタイムラインが確定していること」を前提としています）。
セグメントの分割点はセマンティックイベントに従って決定し、均等時間分割を明確に禁止：シーン転換、プロダクトモーメント、課題の提示、グラフの節目、タイトル表示、末尾の静止、ナレーションの休止に合わせます。
skills/audio-sync-assembly/SKILL.md
Avoid splitting on arbitrary equal chunks.
ここで行っていること：一見公平に見えて必ずズレを生じさせる「秒数による均等分割」をアンチパターンとして指定し、カット点は必ずナラティブのイベントに紐付けるよう規定しています。
プレビュー動画は全編再レンダリングしない：今回の変更の影響を受けるセンシティブな箇所（ナレーション更新箇所、デモ転換、課題タイミング、字幕スタイル確認区間、ラスト10秒、変更されたシーン境界）のみを断片として出力します。
skills/audio-sync-assembly/SKILL.md
Generate preview clips for:
ここで行っていること：検証コストを変更規模に見合ったレベルに抑えます。これはリポジトリの AGENTS.md にある「影響を受けた箇所のみプルーフを提出する」という原則と一致しています。
2コア機能
01全区間/区間リタイミング、静止フレームによる一時停止、音声 tempo の微調整、および明示的な結合を行う FFmpeg コマンドテンプレート
02音声差し替え時の判定ルール：新旧の尺をプローブ → 後続の同期を保つため小幅な tempo 調整 → 言い回しのタイミングが大幅に変わった場合は区間マップを再構築し字幕を再生成
03フレーズ単位のビジュアルアライメント：セリフの発話開始タイミングをグローバルタイムスタンプ（課題カード、製品ステータス、グラフの節、シーンタイトル表示、CTA/ロゴ到達）へマッピング
04タイムラインマニフェストのフィールド仕様：シーンID、ソースレンダリングのパスと尺、目標尺、音声パスとトリム開始/終了、挿入無音、静止フレーム、区間リタイミング比率、グローバルシーン開始点、プルーフ用タイムスタンプ
05一時停止処理の判断基準：無音挿入＋静止または軽微なモーションの維持、独断でBGMを持ち上げない、一時停止時間を後続シーンの開始オフセットに加算
06リグレッション防止チェックリスト：1シーンの変更のために動画全体をリタイミングするミス、音声差し替えによる後続のズレ、字幕タイミングの更新忘れ、非キーフレーム開始のストリームコピー、映像より先にBGMが終わる問題
3外部依存関係
| Kind | Dependency / Endpoint |
|---|---|
| cli | ffmpeg（setpts / trim / tpad / atempo / apad / atrim / concat / fps / scale / setsar），走 filter_complex 显式拼装 |
| cli | ffprobe（探测时长/帧率/分辨率/音轨/采样率与声道） |
| package | 仓库根确定性脚本 scripts/probe_media.py 与 scripts/timeline_manifest_to_ffmpeg.py（本 skill 以「this repo's media probe script」泛指，非自身目录自带） |
| package | 模板 templates/timeline-manifest.example.json（记录目标时序的 JSON 结构） |
| package | 输入素材：最新批准的旁白音频与场景渲染（用户/项目本地提供，非外部服务） |
4推奨統制措置と判定根拠
安全運用のための推奨統制措置
Agent 向け
段階的・都度認可、サンドボックス推奨
管理者向け
承認フロー、ロールバック可能、全履歴監査
判定根拠（ファイルパスと抜粋）
- scripts/: ローカルスクリプトまたはコマンドの実行: （ホストエージェントにより実行）ffmpeg コマンドライン：setpts / trim / tpad / atempo / apad / atrim / concat
- 本地工作目录: ファイル読み書きとアーティファクト出力: プロジェクト内 renders/ のシーンおよび最終 MP4、assembly/ のアセンブリスクリプトまたはコマンドプラン、captions/ の字幕ファイル
監査ノート： 本スキルのディレクトリには SKILL.md および references/ffmpeg-retiming.md（純粋な指示書であり実行ファイルなし）のみが含まれています。実際のインターフェースはローカル CLI（ffmpeg/ffprobe）およびローカルファイルの読み書き（レンダリング、マニフェスト、字幕、プレビュー断片、検証用フレーム）に限定されており、設計基準の「ローカルツール/CLIの呼び出しのみ、またはローカル読み書きのみ」に合致しています。**外部サービスへの素材送信は行いません**：スキルディレクトリ内をスキャンした結果、http(s):// エンドポイント、fetch/requests、token/環境変数の読み取り、アップロードや生成サービスの呼び出しは一切存在せず、音声と映像はすべてローカルの ffmpeg パイプライン内で処理されます。リポジトリルートの scripts/ にある Python スクリプトも、ローカルの ffprobe/ffmpeg 呼び出しとファイル I/O のみを行います（second_pass 確認済み）。同ファミリの9つのスキルは同一の評価基準を持っています：ディレクトリ内には SKILL.md（＋任意の references/*.md）のみが存在し、動作範囲はローカル読み書きとローカル CLI に限定され、エンドポイント、認証情報、素材の外部送信は存在しません。
5二重目の独立検証
- [ok] 「外部依赖只有本地 CLI」是否成立（决定蓝档还是黄/橙档） — 本目录正则扫描无 http(s)://、无 fetch/requests、无 token/env/cookie；SKILL.md 只出现 ffprobe 与 this repo's media probe script，references 只出现 ffmpeg filter 片段。不存在素材外发或端点查询，故落蓝档。
- [ok] ffmpeg 命令模板是否真能跑（不是示意伪代码） — references/ffmpeg-retiming.md 给的是标准 filtergraph 语法（setpts=factor*(PTS-STARTPTS)、tpad=stop_mode=clone:stop_duration、atempo、concat=n=...），可原样接进 -filter_complex；缩放/fps/format 同段给出，属可执行模板。
- [discrepancy] SKILL.md 的时间线清单字段与 templates/timeline-manifest.example.json 是否一一对应 — SKILL.md 列了扁平 11 项（Scene ID / Source render path / Source duration / Target duration / Audio path / Audio trim start-end / Inserted silence / Hold frames / Segment retime ratios / Global scene start / Proof timestamps），模板 JSON 却是嵌套结构：project{name,width,height,fps,output} + segments[{id,video,source_duration,target_duration,audio,strategy,maps}] + captions{} + music{} + proofs[]。差异在于「插入静音/保持帧/分段重定比」被折叠进 strategy+maps（maps 里用 hold_source_time 表达保持帧），「全局场景起点」由脚本按目标时长累加算出而非显式字段，「证明时间戳」在 proofs[] 而非 segment 内。按 SKILL.md 的字段名手写 JSON 不会与模板同构，照抄者需以模板为准。
- [discrepancy] 「this repo's media probe script once available」是否说明探测脚本当前不存在 — 措辞（once available）把探测脚本当成「将来可能有」，但 pin 内仓库根已存在 scripts/probe_media.py（ffprobe -print_format json 的封装，输出时长/体积/码率/视频编码与分辨率/帧率/像素格式/音频编码/采样率/声道），且 render-qa-and-surgical-changes 明确点名它。属文档措辞落后于仓库状态，不影响行为，但会让读者低估可用工具。
- [ok] 与 captions-and-music-bed 的职责是否重叠冲突 — 本 skill 只把「生成字幕/建音乐床」写进组装顺序的第 3-6 步（顺序约束），字幕规则与 ducking 判据全部留给 captions-and-music-bed，无重复定义。
6結論
最適な用途： 適した用途：レンダリング済みの1つまたは複数のシーンと、承認済みの1つまたは複数のナレーションがあり、正確なタイミングで1本の完成動画にアセンブルする必要がある場合。ナレーションの尺と映像のテンポが一致しない、一時停止や静止フレームの挿入が必要、ビジュアルビートを具体的なセリフに合わせたい、またはナレーション差し替え後に後続のタイミングを再編成したい場合に最適です。また、end-to-end-video-playbook の build-in-layers におけるステップ 3〜6 のアセンブリ層としての呼び出しにも適しています。
不向きな用途： 適さない用途：① シーン映像のデザインや生成が必要な場合（hyperframes-scene-builder / motion-design-systems を使用）；② 字幕の文言・スタイル、選曲やダッキングの判断（captions-and-music-bed を使用）；③ 承認済み完成品に対するごく軽微な修正の検収（全編の再アセンブルを避けるため render-qa-and-surgical-changes を使用）；④ 環境に ffmpeg/ffprobe が存在しない場合（本スキルの全判断基準はローカルの ffmpeg パイプラインを前提としており、純粋なコードによる代替手段はありません）。
Install Agent-Ready
① Verified Mirror 2026-09-28
Option A · Direct DownloadDownload audio-sync-assembly.tar.gz
sha256:
Option B · Copy Guide for Agent099bc62047c52f2e…Agent はこの JSON ガイドから自動的にダウンロードして検証します。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit f6b043d9fd.