1仕組みと動作原理

字幕ではなく「グラフィックパッケージング」としての位置付け：元映像はカット編集せずフル再生し、エージェントが対話内でカードのHTML（タイミング＋内容）を1枚ずつ生成し、合成HTMLに組み立ててhyperframesでMP4としてレンダリングします。固定のカード一覧はなく、文字起こし内容に応じて動的に決定されます。

skills/talking-head-recut/SKILL.md

Talking Head Recut takes a local video that **plays in full** and layers a sequence of timed, designed **graphic cards** onto it — titles, lower-thirds, data callouts, quotes, side panels, picture-in-picture — synced to what's being said. The agent designs the cards (timing + content) and **writes each card's HTML directly in the conversation**, then assembles a single composition HTML and renders it to MP4 via `hyperframes`. There is no fixed archetype list and no prescribed card structure — the overlays emerge from what the transcript actually says.

ここでの処理内容：同系統のembedded-captions（逐語字幕の追加）との明確な役割分担。SKILL.mdでは両者を姉妹関係（'Captions add the _spoken words_ as a readable subtitle; this adds _designed graphics_ on top of the playing video.'）として定義し、相互ルーティング（Plain subtitles → embedded-captions）を提供しています。

実行面は本リポジトリのCLIおよびシステム標準のffmpeg/ffprobeのみ：文字起こしはローカルWhisperを使用し、サードパーティ製サービス、APIキー、プロキシ、レート制限は一切ありません。

skills/talking-head-recut/SKILL.md

This skill runs entirely on the **hyperframes** CLI plus system `ffmpeg` / `ffprobe`. Transcription is local **Whisper** via `hyperframes transcribe` — no third-party service, API key, or rate-limited proxy.

ここでの処理内容：NOTICE.mdに明記されたリファクタリングの成果です。元プロジェクトで使用されていたサードパーティ製`@notedit/vtake` CLIおよび`vtake.app`プロキシによる文字起こしを、ローカルWhisperの`hyperframes transcribe`に置き換え、固定のブランドアウトロも削除しました。そのため、本スキルにはクレデンシャル読み取り処理が一切ありません。

ステップ3〜5は純粋なローカルメディア処理：ffprobeで幅/高さ/フレームレート/長さを取得、ffmpegでmp3を抽出、hyperframes transcribeで**フラットな単語配列**（transcript.json）を出力し、エージェントが誤認識語の修正と句読点/ポーズによる文の分割を独自に行います。

skills/talking-head-recut/SKILL.md

`transcript.json` is a **flat array of word objects** — `[{ "text": "...", "start": s, "end": s }, …]` (no `segments` array, no `words` wrapper; the per-word key is **`text`**). Read it and fix obvious ASR errors:

ここでの処理内容：「セグメント構造を持たない」仕様をハード制約として定義（モデルが無駄にsegmentsやwordsラッパーを探すのを防止）。同音異義語、製品名、専門用語の修正を指示しつつ**元のタイムスタンプを維持**させます。また、Whisperの最後の単語が動画末尾を超えて黒画面になるのを防ぐ「メディア長へのクランプ」ルールも備えています。

レンダリング戦略として、明示的な1回限りの4問ゲート（アスペクト比／レイアウト／スタイル／カード密度）を設け、推奨値を事前計算（元動画の比率からrecommendedRatio、動画長からautoCountを算出）し、ホスト環境に応じた3段階のフォールバックプロンプトを備えています。

skills/talking-head-recut/SKILL.md

**Environment compatibility — pick the best available question channel.** Not every runtime exposes the same structured-question tool. Apply this order: 1. **Native clarification tool** — use the structured 4-question call below. 2. **Other native clarification tool** (e.g. `ask_question`, `request_user_input`, IDE-specific prompt) — use that tool with the same 4 question texts and option lists. Preserve the recommendation markers and the precomputed values. 3. **No native tool** (Codex CLI, plain text-only runtimes) — **ask directly in normal conversation**.

ここでの処理内容：実行ホスト（Claude Code / Codex CLI / IDE）ごとにヒアリングツールが異なるため、フォールバック順序を定義しつつ一貫した選択肢と推奨タグを維持します。また、「1ターンあたり最大2〜5問」のグローバル制限を遵守します。ユーザーが事前にデフォルトを許可している場合や自律シグナルがある場合は、recommendedRatio + layout=stack + 中立スタイル + autoCountを採用し、返答内でその旨を説明します。

デザイン次元を直交する3次元に分解：10種のスタイル × 4種のレイアウト × 3種の画面フレーム = 120通りの組み合わせを、それぞれ自己完結型HTMLスニペット（スコープ付き<style>、<script>なし、外部リンクなし、アニメーションはdata-anim-*のみ）として保持します。

skills/talking-head-recut/references/DESIGN_INDEX.md

Style × Layout × VideoFrame (10) (4) (3) = 120 possible combinations

ここでの処理内容：デザインの自由度をモデルの即興に頼るのではなく、検索可能なリファレンスライブラリとして整備しています。各スニペットはカード規約（'scoped `<style>`, no `<script>`, no external URLs, animations only via `data-anim-*`'）に準拠。assets/vendor/gsap.min.jsが同梱され作業ディレクトリにコピーされる理由も、完全なオフライン動作を担保するためです。

アセンブリ時の2つの厳格なルール：① 入力動画は高密度なキーフレームで再エンコード必須（GOP間隔が広いとレンダラーのシーク時にフレームがフリーズするため）；② 映像はミュートの<video>を使用し、同一ソースからルートレベルの#source-audioトラックを別立てで読み込むことで、原音を保持しつつ音量やダッキングの個別制御を可能にします。

skills/talking-head-recut/SKILL.md

ffmpeg -y -i "$VIDEO_PATH" -c:v libx264 -crf 18 -g 30 -keyint_min 30 \ -pix_fmt yuv420p -movflags +faststart -c:a aac "$WORK_DIR/public/input-video.mp4"

ここでの処理内容：注記による理由の説明：'Sources with a sparse GOP (keyframe interval > ~1s) freeze on seek in the renderer (a frozen frame under the overlays)'。音声を分離する理由は：'This uses a separate audio track rather than data-has-audio="true" so its volume and ducking remain independently controllable on the timeline.'

SKILL.md自体のコンテンツに対する構造アサーションテストを同梱：正規の合成例が元動画をミュートvideo＋同音源audioとして確実に保持していること、両トラックのsrc/data-start/data-durationが一致しtrack属性が異なることを検証します。

skills/talking-head-recut/media-contract.test.mjs

assert.equal(readAttribute(audio, "src"), readAttribute(video, "src")); assert.equal(readAttribute(audio, "data-start"), readAttribute(video, "data-start")); assert.equal(readAttribute(audio, "data-duration"), readAttribute(video, "data-duration")); assert.notEqual( readAttribute(audio, "data-track-index"), readAttribute(video, "data-track-index"), );

ここでの処理内容：本スキルで唯一の実行可能コードであり、**ドキュメント自体**をテスト対象としています（SKILL.mdをテキストとして読み込み、例示された合成の属性規約を検証）。後からSKILL.mdを編集した際に正規サンプルが壊れるのを防ぐ、ドキュメント整合性のリグレッションテストです。

2コア機能

01既存の口頭説明／インタビュー／ポッドキャスト動画を、タイミング制御されたデザインカード（キネティックタイトル、テロップ、データコールアウト、引用、サイドパネル、PiP）でパッケージング

02元動画の縦横比に基づき推奨値と理由タグを事前計算するマルチアスペクト比出力（16:9 / 9:16 / 4:5）

031ターンあたりの質問上限を遵守した、ホスト環境を跨ぐ構造化ヒアリングのフォールバック（ネイティブツール → 他のネイティブツール → プレーンテキスト4問ゲート）

04ローカル文字起こしとタイムライン整合（フラットな単語配列 + 独自文分割 + ASRエラー修正 + メディア長へのクランプ）

05120通りのスタイル×レイアウト×フレーム組み合わせのリファレンスライブラリ（各スニペットは自己完結型でスクリプト・外部リンクなし）

06HFレイアウト／アニメーションQAルールのインライン適用（静的なキーフレーム先行、オーバーレイ層のみのアニメーション、data-track-index/data-duration、clipクラス、具体的フォント名指定などのリント制約）

07単一フレームスナップショットによるセルフチェックとレンダリング（macOS GPUレンダリング切り替え対応）

08納品レポート仕様 + オプションのリアルタイムプレビュー（ユーザーの要求時かつレンダリング完了後のみ起動）

3外部依存関係

Kind	Dependency / Endpoint
cli	hyperframes CLI（doctor / transcribe / render / snapshot / preview / skills update）
cli	ffmpeg / ffprobe（系统依赖：取元数据、抽音频、重编码输入视频）
cli	本地 Whisper（经 hyperframes transcribe，无 key/无代理）
package	GSAP 3.15.0（随包 vendored，复制进工作目录的 public/vendor/）
package	随包字体（Inter / Caveat / Virgil / LXGWWenKaiTC，woff2）
network	hyperframes skills update（自刷新，需网络；本 skill 唯一需要联网的环节）
package	上游开源项目（本 skill 卡片设计系统的来源，仅署名引用，非运行时依赖）

4推奨統制措置と判定根拠

安全運用のための推奨統制措置

Agent 向け

段階的・都度認可、サンドボックス推奨

管理者向け

承認フロー、ロールバック可能、全履歴監査

判定根拠（ファイルパスと抜粋）

scripts/: ローカルスクリプトまたはコマンドの実行: （同梱の本番スクリプトなし）ワークフローがホストに実行を要求: npx hyperframes doctor / transcribe / render / snapshot
本地工作目录: ファイルの読み書きと成果物の出力: videos/<project>/metadata.json、audio.mp3、transcript.json、storyboard.json（ag

監査ノート： 極めて抑制的な動作設計です。ディレクトリ全体で実行可能コードはテストファイル1つのみ（SKILL.mdをテキストとして読み込みアサーションを行うだけで本番スクリプトは存在しない）であり、処理は本リポジトリのhyperframes CLIとシステム標準のffmpeg/ffprobeに依存し、完全にローカルで実行されます。文字起こしにはローカルWhisperを使用し（キー、プロキシ、レート制限なし）、認証情報の読み取り・保存やサードパーティAPI呼び出しは一切確認されません。GSAPおよびフォントは同梱されており、レンダリング時に外部ネットワークを必要としません。唯一のネットワーク通信は自己更新コマンドの`skills update`のみです。安全評価で「緑」とならない理由は、ローカルの動画および文字起こしテキストの読み書き（自動クリーンアップされない作業ディレクトリへの永続化）を伴うこと、およびGSAPスクリプトを含むローカルHTMLを出力するためです。

5二重目の独立検証

[ok] 是否真的无凭证、无第三方 API（蓝档判定的关键） — 整目录 grep：(API_KEY|TOKEN|SECRET|\.env|keychain|Bearer|Authorization) 命中 15 处全为 'tokens' 子串误配（设计 token 语境）；heygen/OPENAI/ANTHROPIC 0 命中；process.env 0 命中；fetch 0 命中。SKILL.md 与 NOTICE.md 双重声明转录为本地 Whisper。结论成立。
[ok] 『无脚本』是否属实（有没有隐藏的执行体） — 全量清单中 .mjs 仅 1 个且为测试；无 .sh/.py/.cjs。流程里的命令是文档中给宿主执行的 ffmpeg/CLI 调用，不是随包脚本。『runs entirely on the hyperframes CLI plus system ffmpeg/ffprobe』表述与文件构成一致。
[ok] 『外部资源』逐条回查调用点 — npx hyperframes doctor/transcribe/render/snapshot/preview 均在 SKILL.md 原文；ffprobe/ffmpeg 两条命令在 Step 3 原文、重编码命令在 Step 9 原文；随包字体与 gsap 的复制命令在 Step 9 原文；上游仓库链接在 NOTICE.md 原文。无推测项。
[discrepancy] 转录模型选择与同批 skill 的口径差异 — 本 skill 硬编码 `--model small.en`（Step 4 原文），而同仓 embedded-captions 的 transcribe.cjs 明确**禁止**默认 small.en（注释：'Default = multilingual `small`, NOT `small.en`. Per media-use: ".en models mistranslate non-English and mis-handle accented speech"'，并记录了曾被 small.en 在重口音说话人上产出错误转录的实例）。本 skill 在 description 中虽未宣称多语种，但也没有对非英语素材给出提示。这是**同一仓库内两个 skill 对同一问题给出相反默认**的真实出入，对非英语/重口音素材的使用者有实际影响（本 skill 使用者也可能会中同样的坑）。
[ok] vendored GSAP 的许可约束是否被标注 — assets/vendor/gsap.min.js 文件头写明 'GSAP 3.15.0 … @license Copyright 2026, GreenSock. All rights reserved. Subject to the terms at https://gsap.com/standard-license.'；随包分发即意味着产出物沿用该许可约束（同批其它 skill 走 CDN 引用、许可披露方式不同）。已在 meta.license 与 risks 中记录。
[unlocatable] 验证：渲染/预览类声明是否可在源码内证实其行为 — SKILL.md 描述的行为（稀疏 GOP 导致渲染器 seek 卡帧、单帧 snapshot 的位置与命名、`--at` 单值会忽略 --out）需要实际运行 hyperframes render/snapshot 才能证实；本次为只读侦查且不得运行构建/渲染，故记为无法在源码内定位，不作为已验证事实。

6結論

embedded-captionsとの明確な役割分担（グラフィック装飾 vs 字幕生成）と双方向の誘導により、スキルの選択ミスを防止

外部スクリプト・認証情報・外部通信ゼロ：ローカルWhisper文字起こし、完全ローカルレンダリング、GSAPおよびフォントを同梱（オフライン対応）

レンダラーの既知の落とし穴をワークフローに組み込み（キーフレーム高密度エンコードを必須化し、シーク時の画面フリーズを回避）

Docs-as-code（コードとしてのドキュメント）：SKILL.md内の正規合成例をmedia-contract.test.mjsの構造アサーションで検証し、ドキュメントの形骸化を防止

丁寧なマルチホスト適応：構造化ヒアリングの3段階フォールバック + 質問数上限 + 事前承認時のデフォルト自動採用と説明出力

検索可能なデザイン空間：120通りの組み合わせを持ち、各スニペットはスクリプト・外部リンク排除の規約に準拠（テンプレート層のリスクを低減）

最適な用途： カット編集やカラーグレーディングを行わずに、既存の口頭説明・インタビュー・ポッドキャスト動画をリッチに「パッケージング」したい方に最適です。キネティックタイトル、テロップ、データコールアウト、引用カード、サイドバー、PiPを追加し、プラットフォームに合わせて16:9 / 9:16 / 4:5を選択できます。また、ローカルWhisper文字起こし、APIキー/プロキシ不要、同梱またはシステムツール依存で完結するため、プライバシーや完全オフライン環境を重視するユーザーにも適しています。デザイン面では10種類のスタイル（小紅書風の中国系デザインを含む）と中国語楷書体フォントも提供されています。

不向きな用途： 以下の場合には適しません：① 逐語字幕のみを求めている場合（/embedded-captionsを使用してください。説明欄でも「Not plain subtitles」と除外明記されています）；② ゼロから動画を生成する場合（product-launch-videoやfaceless-explainerなどの生成系ワークフローを使用してください）；③ 単体のモーショングラフィックス動画が必要な場合（/motion-graphicsを使用）；④ クリップのカットや素材の並べ替えが必要な場合（本スキルは元動画を**カットせずフル再生**することが前提です）；⑤ 英語以外または訛りの強い素材で、文字起こしモデルの手動調整を行いたくないユーザー（デフォルトのsmall.enには既知のリスクがあります）；⑥ 処理中のリアルタイムな目視確認を求めるユーザー（実行中にプレビューは開かず、レンダリング完了後の要求時のみ起動します）；⑦ 機密性が高く痕跡の完全消去が必須の素材（作業ディレクトリに元動画のコピーや文字起こしがデフォルトで保持されます）。

Install Agent-Ready

① Verified Mirror 2026-09-15

Option A · Direct DownloadDownload talking-head-recut.tar.gz

sha256: ff96f4df7b933a0f…

Option B · Copy Guide for Agent

install.json

Agent はこの JSON ガイドから自動的にダウンロードして検証します。

② Upstream GitHub

GitHub Repo ↗

Pinned to commit b8328f9573.