1仕組みと動作原理
実際の選定インターフェースは35行のアイデンティティカタログ（10のクラシックDNA + 25のテーマ）であり、エンジンとオーサリングファイルはテーブル参照から導出されます。SKILL.mdはバックエンドエンジン名をユーザーへの質問として提示することを明示的に禁止しています。
skills/embedded-captions/SKILL.md
**Never surface "Standard vs Cinematic vs Theme" as a question** — those are backend names (a product has one UX even with several engines). The catalog encodes everything routing needs: reading surface, voice, recommend-for, scene needs, adjacency notes for the genuinely-close pairs (loud↔ordnance, neon↔neonsign, cream↔stardust).
ここで行われていること：「3つのエンジン」の複雑性を製品内部に隠蔽しています。ユーザーは視覚的アイデンティティ（anchor/cream/ordnanceなど）を選択するだけで、スキルがCATALOG.mdの該当行からオーサリングファイルとコンパイルチェーンを導出します。検証：CATALOG.mdには実際に `| \`` で始まる35行のアイデンティティ行があり、dna/ 配下に10個のJSON、themes/ 配下に25個のJSONが存在し、三者の整合性が取れています。
字幕は3つのステートとしてモデル化されます：drop（つなぎ言葉、非表示）/ rail（画面下部1/3に表示される逐語的字幕、手前側で大半のテキストを担う）/ embed（昇格された強調ワード、被写体の背面に合成されマット処理による遮蔽が発生）。embedは希少な要素として定義されます。
skills/embedded-captions/SKILL.md
| **rail** | the default — ordinary spoken content (verbatim) | clean lower-third subtitle, **in front**, readable. A punch word can get an inline `emphasis` highlight (accent colour / active-word pop) — it stays on the rail. | | **embed** | a promoted peak — the headline beat | one big word composited **behind the subject** (matte occlusion), designed entrance + exit |
ここで行われていること：「遮蔽（オクルージョン）」を特殊効果のリソースとして活用しています。まず動画の人物をマット処理で切り抜き、強調ワードを被写体レイヤーの背面に配置することで、テキストが人物に隠れた後に現れる演出を作ります。希少性は厳格なルールです：「ブロック（思考単位）あたりヒーローワードは≤1、2つ同時に表示させない、ヒーローウィンドウ間には1拍以上の間隔（コンパイラは0.6秒未満で警告）」、さらに複数ヒーローが存在する場合も最大のもの（APEX）のみが完全なロックアップ演出を受けます。
前処理は1本の並列コマンドで実行されます：マット処理 ∥ 文字起こし ∥ 音声エンベロープ の3系統を同時に走らせ、その後に直列で safe-zones を計算します。「手作業の3ステップによる漏れ」を単一の呼び出しに集約しています。
skills/embedded-captions/scripts/prepare.sh
# matte.cjs (CPU-heavy ONNX) ∥ transcribe.cjs (whisper) → then safe-zones.cjs # (matte and transcribe are independent; safe-zones needs the matte's frames_fg.) # Replaces hand-running steps 2 / 3 / 3b — one call, nothing forgotten, ~the cost # of the slower of the two instead of their sum.
ここで行われていること：3つのバックグラウンドプロセス（matte/transcribe/audio-envelope）がそれぞれログをリダイレクトして wait し、続いて safe-zones.cjs を実行します。失敗時は各プロセスの末尾ログを出力して非ゼロコードで終了します。frames_fg/、frames_bg/、matte.fps、transcript.json、safe-zones.json を出力し、以降のオーサリング工程の全入力を揃えます。
文字起こしはローカルの WhisperX（uvx経由、バージョン固定）を使用し、wav2vec2 による強制アライメントで単語レベルのタイムスタンプを取得します。これは後段のゲートが80msの厳格なアライメントを要求するためです。失敗した場合は本リポジトリの whisper.cpp にフォールバックします。
skills/embedded-captions/scripts/transcribe.cjs
// Pin whisperx so `uvx` fetches a reproducible build instead of resolving // "latest" on every run (a supply-chain + determinism foot-gun). Override // with $WHISPERX_VERSION if you've validated a different release. const whisperxSpec = `whisperx==${process.env.WHISPERX_VERSION || "3.8.6"}`;
ここで行われていること：サードパーティ製パッケージのバージョンを固定し（サプライチェーン対策および再現性担保）、`uvx --python 3.12 --from whisperx==3.8.6 whisperx <wav> --model small --device cpu --compute_type int8 --output_format json` の形式で呼び出します。デフォルトモデルは `small.en` ではなく多言語対応の `small` であり、コメントでその理由が明記されています（.en モデルは非英語や強い訛りのある音声を誤訳するため）。
マット処理はモデルの重みを内包せず、本リポジトリCLIの remove-background（u2net_human_seg）をシェル経由で実行します。初回実行時に約168MBがユーザーのキャッシュディレクトリにダウンロードされます。VFR（可変フレームレート）のソースはマット処理前にCFR（固定フレームレート）へ正規化されます。
skills/embedded-captions/scripts/matte.cjs
const r = cp.spawnSync("node", [hfCli(), "remove-background", matteSrc, "-o", mov], { stdio: ["ignore", "pipe", "pipe"], encoding: "utf8", });
ここで行われていること：「モデルアセット」をCLI側のキャッシュ管理に任せ、スクリプト自体には重みファイルを一切同梱していません。同一ファイルのコメントに理由が記録されています（旧実装では34MBの PP-MattingV2 + onnxruntime 推論ループを内包していたため）。VFRの正規化には実測値に基づく根拠があります（「あるクリップで fg 2251フレーム に対し bg 902フレーム を観測」）。
合成フェーズでは ffmpeg を使いマットを遮蔽レイヤーとして扱います。embed は「背景＋字幕を先にレンダリングし、人物アルファでオーバーレイ」、rail は「透明WebMとしてレンダリングし、最前面にオーバーレイ」します。フレームアライメント維持のため、フレームレートは matte.fps を唯一の基準とします。
skills/embedded-captions/scripts/render-and-composite.sh
# FPS: matte.fps (written by matte.cjs at the source's NATIVE rate) is authoritative # so the matte overlay stays frame-aligned with the render. Falls back to plan.fps / # frame-count inference / 24. Warn if plan.json fps disagrees with the matte.
ここで行われていること：レンダラーは plan.duration を参照する一方、マットのフレームレートは元動画のネイティブ値となるため、不一致が生じると被写体の浮遊や末尾の黒フレームが発生します。スクリプトは出力長を min(マットフレーム数/fps, ソース尺) にクランプし、前景色のみの末尾を防ぐ「Bug-1 guard」を備えています。また、ロールバック用に index.html + plan.json を history/ にスナップショット保存します。
幾何学的ゲートは、ヘッドレス Chromium の DOM 矩形 × マットアルファ によるピクセル単位の判定（遮蔽、枠外はみ出し、rail/climax の衝突）を行い、--strict オプションで80msの時間アライメントを検証します。約2秒/フレームのプレビューフレームを先に出力し、高コストな本レンダリング前にレイアウト破綻を発見させます。
skills/embedded-captions/SKILL.md
`node scripts/preview-frames.cjs <project> [t…]` composites **faithful preview frames in ~2s each** (caption layers screenshotted at seek-time + real video frame + matte occlusion + rail overlay = what the final composite will look like at that moment).
ここで行われていること：「レンダリングは高コスト → まず低コストで確認する」というワークフローの規律化を行っています（「フルレンダリングには数分かかるため、レイアウト問題の『発見』に使ってはならない」）。ゲート一覧：check-timing.cjs --strict（80ms）、check-occlusion + measure-layout（被写体遮蔽と枠外判定）、check-overflow（警告のみ）、check-rail-climax（rail と climax の重複表示、ハードフェイル）。
2コア機能
01元映像を編集しない字幕オーバーレイ：Standard/rail + peak embed のデュアルトラックモデル（drop/rail/embed の3ステート割り当て）
0235種類のアイデンティティ視覚カタログ + シーンパラメータ化DNA（アクセントカラー抽出、光源方向に合わせたコンタクトシャドウ、被写界深度に合わせたブラー、RMS音量に連動するヒーロー振幅）
03シネマティックな純粋 embed コンパイル：制作者はブロック（単語行 + プレーン + CSS + 1つのヒーロー）のみを記述し、タイムライン、ブロック内累積、ブロック間ページめくり、ヒーローの3幕構成、apex/minor レイヤリングをコンパイラが自動生成
04テーマモード：体系化されたテーマ憲法（本文規範 × ヒーローセットピース × 前景FX × プレートリアクション）により、コンパイル時に逐語的整合性を検証し、レンダリング時に final_fx.mp4 を生成
05ローカルでの単語レベル文字起こし（uvx経由の WhisperX）。無音部での幻覚防止ガードおよび無効な文字起こしの棄却判定付き
06被写体のマット切り抜きと遮蔽合成（CPU専用 ONNX、1080pで約2fps、重みファイル自動ダウンロード）
07判定ゲート：複数話者/ハードカット、人物なし、短尺/音声なし/顔が終始不可視、焼き付け字幕あり、手ブレ動画などに対し、項目ごとの拒否または分割処理を定義
08低コストプレビュー（約2秒/フレーム）と2つのQAリスト：レイアウト崩れを防ぐネガティブリストと、「デザイン品質」を担保する5項目のポジティブな基準チェック、さらに fresh-eyes サブエージェントによるプレビュー画像のブラインド評価を推奨
3外部依存関係
| Kind | Dependency / Endpoint |
|---|---|
| cli | ffmpeg / ffprobe（系统） |
| cli | hyperframes CLI（init / remove-background / render / lint / check / snapshot / preview） |
| cli | uvx（Python 运行器，按需拉取 whisperx==3.8.6） |
| network | 抠像权重下载（u2net_human_seg.onnx，约 168MB，仅首次） |
| network | GSAP CDN（仅示例渲染与引擎模板 HTML 里引用） |
| package | sharp（图像/alpha 数学）与 puppeteer（版面度量、截图） |
| package | python3（Theme 的 drawon setpiece 在编译期调用 gen-stroke-path.py） |
| cli | hyperframes skills update（自刷新，需网络） |
4推奨統制措置と判定根拠
安全運用のための推奨統制措置
Agent 向け
段階的・都度認可、サンドボックス推奨
管理者向け
承認フロー、ロールバック可能、全履歴監査
判定根拠（ファイルパスと抜粋）
- scripts/: ローカルスクリプトまたはコマンドの実行: bash scripts/prepare.sh <project>（node matte.cjs / transcribe.cjs / aud を並列起動）
- 网络端点: 外部ネットワークアクセスの宣言: uvx が必要に応じて PyPI から whisperx==3.8.6 およびその依存関係を取得（「latest」指定による再現性低下を防ぐためバージョン固定）
- 本地工作目录: ファイルの読み書きと成果物の出力: <project>/frames_fg/、frames_bg/、matte.fps、audio.mp3、_wx_audio.wav、_wx_out/（
監査ノート： 動作面：18個の .cjs + 3個の .sh + 1個の .py によるローカル実行チェーンであり、大量のローカルファイルI/Oおよび ffmpeg/Chromium の呼び出しを含みます。外部への通信は存在しますが、対象は明確でバージョンが固定されています（PyPIの whisperx==3.8.6（uvx）、hyperframes CLIが管理する u2net マット重み（約168MB、初回のみ）、jsdelivrの [email protected]、および `skills update` による自己更新）。**クレデンシャル、クッキー、キーチェーンの読み取りは一切確認されていません**（HeyGenに依存する同系統のスキルとは異なります）。TLSダウングレード、スクレイピング防止の回避、任意コード実行の余地は確認されませんでした（サブプロセスの呼び出しはすべて固定バイナリ/固定スクリプトであり、引数はローカルファイルに由来）。したがって「オレンジ（危険）」には該当しません。留意事項：① 初回実行時にサードパーティ製Pythonパッケージとモデル重みがダウンロードされる点（サプライチェーン面）；② ユーザーのローカル元映像を処理し、マット処理済みフレーム（人物の容姿を含む）がプロジェクトディレクトリに保存されるため、ディレクトリ権限の管理とクリーンアップが必要な点；③ 文字起こしされたテキストがモデルのコンテキストに入力されるため、コンテンツレイヤーでのプロンプトインジェクション対象となり得る点。
5二重目の独立検証
- [ok] 是否隐藏凭证读取（与同批 HeyGen 系 skill 的差异） — 对整目录 grep `\.heygen|HEYGEN|api[_-]?key|TOKEN|SECRET|keychain|Bearer|Authorization` → 0 命中；process.env 命中 12 处全部是 HYPERFRAMES_ROOT / WHISPER_MODEL / WHISPER_LANG / TRANSCRIBE_ENGINE / WHISPERX_VERSION 等行为开关。『全本地、无凭证』成立。
- [ok] 网络外发是否全部可预期 — 逐条回查：uvx 拉 whisperx（版本钉死 3.8.6，注释明说是为防供应链与不可复现）；模型下载由 hyperframes CLI 自管且路径固定在 ~/.cache/hyperframes/；CDN 引用仅在 engine.html / example-renders / _archive 模板内；无其它域名。未发现隐藏上报或遥测。
- [ok] 实现原理与功能声明是否相符 — 'runs locally end to end, including transcription and subject matting' 成立（本地 WhisperX + 本地 ONNX 抠像）；'without editing the footage' 成立（Standard/Cinematic 只叠加，脚本注释与 SKILL.md 均强调不调色/不覆盖）；唯一被允许改原片的是 Theme 的 PLATE 反应预算，SKILL.md 已显式标注为例外。
- [discrepancy] SKILL.md 的三引擎描述与脚本实际状态不一致（文档漂移） — SKILL.md 开篇仍把 Standard 描述为默认模式（'**Standard** (default) builds a clean verbatim **rail** … + an **embed** climax'），并在多处按 rail.html + index.html 描述两轨产出；但同 commit 的 scripts/render-and-composite.sh 第 35-37 行写着 'Standard mode retired 2026-06-12 — rail-surface needs are served by theme DNAs like "anchor"'，dna/README.md 第 15-16 行同样写 'Standard/rail mode was retired 2026-06-12'，make-composition.cjs 第 253-257 行则在检测到 standard 派生的 plan.json 时直接报错退出。然而 scripts/ 下仍保留完整的 STANDARD 合成分支（第 392 行起 'STANDARD mode (rail + embed) — detected by rail.html'）、modes/standard/ 目录与 44 个字体仍在包内。结论：**rail + peak embed 的实现仍在，但文档层（SKILL.md）已落后于引擎层（dna/README、render 脚本注释）**，两处关于『默认模式』的说法互相矛盾。这是对 pin commit 有效的真实出入，非第一遍误读。
- [ok] 『35 身份』等数量声明的准确性 — 实测 CATALOG.md 身份行 = 35；dna/*.json = 10（chrome/cream/documentary/editorial/glitch/ink/keynote/loud/neon/velocity）；themes/*.json = 25；references/*.md = 14。与 SKILL.md 自述一致。
- [ok] 门禁是否真的会执行（而非只写在文档里） — render-and-composite.sh 内确实依次调用 check-timing（plan+transcript 存在时）、measure-layout + check-occlusion（plan + frames_fg 存在时）、check-overflow（无 plan 的 custom 模式告警）、check-rail-climax（rail.html 存在时，支持 RAIL_CLIMAX_SKIP=1 覆盖），并把结果汇总进 _gates.txt；与 SKILL.md 的门禁描述对应。
6結論
最適な用途： 適しているケース：既存の単一人物の解説・トーク動画（口頭説明、インタビュー、解説系）があり、元映像のカットやカラーグレーディングを行わずに完成品レベルの字幕を追加したいユーザー。「下部1/3の読みやすい逐語字幕」と「被写体の背面に埋め込まれるピーク強調字幕」を組み合わせてデザインしたいクリエイター。CSSやGSAPを自作することなく、体系化された視覚アイデンティティ（控えめな anchor から ordnance/terminal/vhs/arcade などの特殊効果系まで35種）を利用したいチーム。中国語の「炸/特效/酷炫字幕（ド派手な／特撮風／クールな字幕）」に対する明示的なトリガーワードと選定ヒューリスティクスを備えています。
不向きな用途： 適していないケース：① 複数話者が含まれる、またはハードカットがある素材（SKILL.mdは事前カット分割または処理拒否を要求）；② トーキングヘッド形式ではない（人物被写体が存在しない）動画；③ 3秒未満、無音、または顔が終始確認できないクリップ；④ 既に焼き付け字幕や大量のテロップ・グラフィックが含まれる映像（第2の字幕システムとの重複を回避）；⑤ 文字起こしの品質が破綻しており（重度の訛りや非母語による意味不明な出力）、medium モデルに切り替えても改善しない場合（SKILL.mdは誤った字幕の納品ではなく拒否を義務付け）；⑥ 映像自体を変更したい（カラーグレーディング、エフェクト付与、クロップや再構図）要求（本スキルは元映像を変更しない方針を明記）；⑦ 単に文字が読めればよく、ピーク演出を必要としない低コスト・軽量な用途（よりシンプルな字幕ツールの利用が適切）。
Install Agent-Ready
① Verified Mirror 2026-09-15
Option A · Direct DownloadDownload embedded-captions.tar.gz
sha256:
Option B · Copy Guide for Agent9cdab9186d817c12…Agent はこの JSON ガイドから自動的にダウンロードして検証します。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit b8328f9573.