1仕組みと動作原理
HyperFramesを中国語ナレーション動画の唯一の制作基盤（チュートリアル動画に限定しない）と位置付け、ユーザーからクリック駆動型のWebデモが明示的に要求されない限り、従来のweb-video-presentationルートは使用しない。
skills/hyperframes-teaching-video/SKILL.md
Use HyperFrames as the primary production surface for Chinese narrated videos, not only teaching videos. … Do not use the old Web Video Engineer / `web-video-presentation` implementation path unless the user explicitly asks for a click-driven webpage presentation.
ここでの目的：同名ディレクトリに残るレガシーな手法との境界を明確にしつつ、旧ルートの長所（ナレーション優先、大字幕、16:9チェック、明示的なレンダリング検証）を継承する。
デフォルトのビジュアルとトーン：Apple Keynote / macOS風、口語調とし、定型的な導入（「AI時代、もう〜はやめましょう」など）や視聴者に見せるべきでない内部タグ（s03、フォルダ名など）は禁止する。
skills/hyperframes-teaching-video/SKILL.md
Use Apple Keynote / macOS style unless the user gives a stronger reference … Avoid starting with formulaic lines like "AI 时代，别再...".
ここでの目的：「AI生成らしさ」を排除する文面ルールを前面に出し、中国語優先を徹底する（英語はコード識別子、API名、UI要素名のみに限定）。
アニメーション作成前にナレーション原稿を書き上げ、執筆の参照先はreferences/CODE-GARDEN-VOICEOVER.mdのみとする。執筆開始前にDESIGN.mdへ位置付けを定義した1文を記述する。
skills/hyperframes-teaching-video/SKILL.md
For narration drafting or rewriting, read `references/CODE-GARDEN-VOICEOVER.md` first. … Before writing the script, write a one-sentence **positioning statement** in `DESIGN.md`
ここでの目的：ワークフロー、ケーススタディ、ショーケースなどの要件が汎用的な「ツールの使い方」チュートリアルに変質するのを防ぐため、位置付け文によって動画のジャンル（チュートリアル、解説、事例分析、製品紹介、フロー分解、振り返り、公開アセット）を明示させる。
単一のsync manifestを唯一の信頼できる情報源とする：3つの配列を手動管理するのではなく、ナレーション、字幕、シーン開始位置をすべてここから派生させる。
skills/hyperframes-teaching-video/SKILL.md
Keep one sync manifest as the source of truth for narration, subtitles, and scene starts.
ここでの目的：assets/sync-script.json（{ "scene": "#scene-3", "text": "..." } 形式）を用いてnarration.txt、sync-map.js、HTMLの再生時間を生成し、Webページのステップ数と音声ファイル数の不整合を構造的に防ぐ。
TTSに具体的なデフォルト値を設定：Doubao/Volcano seed-tts-2.0 + zh_male_liufei_uranus_bigtts + speech_rate=20。代替としてEdge TTSを用意し、男女の音声プリセットと+20%の速度を推奨する。
skills/hyperframes-teaching-video/SKILL.md
In `/Users/d2/project/web vidio` projects, default to Doubao / Volcano `seed-tts-2.0`, voice `zh_male_liufei_uranus_bigtts`, and `speech_rate=20` unless the user says otherwise. … Recommended Edge TTS defaults for Chinese: voice `zh-CN-YunxiNeural` for a male presenter voice, or `zh-CN-XiaoxiaoNeural` for a female presenter voice; rate `+20%` unless the user requests a slower or faster delivery.
ここでの目的：作成者のローカル制作環境の規約（ローカル絶対パス /Users/d2/project/web vidio を含む）を固定化し、Doubaoの認証情報が無効かつEdge TTSが許容される場合のフォールバック条件と事前チェック（command -v edge-tts）を定める。
再生時間は実測音声から取得することを必須化：音声ファイルが存在する場合、文字数やEdge TTSの単語境界メタデータ、原稿テキストによる推測は禁止し、ffprobeによる再確認後に再生時間とcueタイミングを反映する。
skills/hyperframes-teaching-video/SKILL.md
Do not estimate timing from character count, Edge TTS word-boundary metadata, or narration text alone when audio files exist.
ここでの目的：「字幕と画面の表示タイミングをナレーションに完全に同期させる」ことを測定可能な制約にする。TTSプロバイダ変更時はナレーション、sync map、字幕、シーンタイミング、MP4を再生成するものとし、古いsync mapに新しい音声を組み合わせることを禁止する。
字幕仕様をピクセル単位および行数で厳格に定義：中国語で約66〜72px、高コントラストまたはドロップシャドウ、デフォルトで中央下部のプレーンテキスト（「ナレーション：」ラベルなし、大きな背景帯なし）、表示字幕は厳密に1行を維持する。
skills/hyperframes-teaching-video/SKILL.md
Keep visible subtitles to one line. … Use roughly 66-72px Chinese text for burned-in HyperFrames subtitles, strong contrast or shadow, and enough bottom margin to avoid covering the scene focus.
ここでの目的：「1080pの画面録画でも明瞭に読めること」を絶対基準とする。cueが改行する場合は、2行表示を許容せず、隣接する短いcueに分割してTTSおよびタイミングを再生成する。
HyperFramesの実装規約はエコシステムのルールに準拠：ルート要素にdata-durationを付与、音声にはネイティブの<audio>要素を使用、window.__timelinesに一時停止状態のGSAPタイムラインを登録、決定論的アニメーションを採用し、トランジションはデフォルトでソフトクロスフェードとする。
skills/hyperframes-teaching-video/SKILL.md
Register a paused GSAP timeline in `window.__timelines` and build deterministic animation.
ここでの目的：画面全体のワイプ、白フラッシュ、ライトスイープ、急激なvisibility切り替え、画面が空白になりやすいトランジションを明示的に禁止し（演出上高エネルギーな効果が求められる場合を除く）、要素を一度に配置せずナレーションに合わせて順次登場させる。
検証は実生成物のみを対象とする：npm run check（またはhyperframes lint/inspect）、MP4レンダリング後のffprobeによる実時間確認、ffmpegによるコンタクトシート抽出と各項目の目視確認を実施する。
skills/hyperframes-teaching-video/SKILL.md
ffprobe -v error -show_entries format=duration,size -of json renders/final.mp4
ここでの目的：「完了」の定義を実際のMP4ファイルに紐付け、7項目の目視チェックリスト（空白フレームや途切れたトランジションがないか、現在のナレーション箇所の視覚的強調、音声に連動した要素登場、重要コンテンツを遮らない字幕、中国語表記、テンポ感、余計なラベルのない1行字幕）を提供する。
公開下書きには安全装置を設ける：実ブラウザを用いて下書きの作成やフィールドの検証を行うことは認めるが、プラットフォーム、アカウント、タイトル文面、タグ、MP4、カバー画像をユーザーが確認するまで最終公開ボタンは押さない。
skills/hyperframes-teaching-video/SKILL.md
When using a live browser to upload to social platforms, prepare drafts and verify fields, but do not click the final publish/submit button until the user confirms
ここでの目的：自動化の範囲を下書き作成フェーズに留め、最終送信には必ず人間の確認を挟む。これが本スキルにおける外部アクションの唯一のレッドラインである。
2コア機能
01チュートリアルにとどまらない、汎用的な中国語ナレーション動画の制作（解説、製品デモ、フロー分解、事例研究、ショーケース、SNS向けショート動画）
02実音声時間に基づくナレーション同期 + 大字幕（1行、66-72px、デフォルト中央下部プレーンテキスト）
03デュアルTTS構成：Doubao/Volcano（seed-tts-2.0、刘飞 2.0、speech_rate 20）およびEdge TTS（zh-CN-YunxiNeural / zh-CN-XiaoxiaoNeural、+20%）
04TTS事前チェックと無断フォールバックの禁止：事前にcommand -v edge-ttsまたはimport edge_ttsを実行し、依存関係が不足している場合は処理をブロックして報告（勝手にプロバイダや低速デフォルトへ切り替えない）
05HyperFrames HTML合成実装：data-duration、ネイティブ<audio>、window.__timelines登録の一時停止GSAPタイムライン、順次要素登場、ソフトクロスフェードトランジション
06実MP4の検証とフレーム目視確認（hyperframes lint/inspect、ffprobe実時間確認、ffmpegコンタクトシート + 7項目目視チェックリスト）
07カバー/サムネイルおよび公開用下書きアセット（9:16ポスター、プラットフォーム向け文面・タグ、下書き状態および確認項目）
08よくある修正処方箋（短すぎる→解説を追加して再執筆、焦点がない→時差登場+旧要素の減光、トランジションが空白→クロスフェード化、字幕が小さい/改行→フォントサイズ変更またはcue分割）
3外部依存関係
| Kind | Dependency / Endpoint |
|---|---|
| cli | HyperFrames CLI（lint / inspect；渲染经项目 npm run render 或 npx hyperframes） |
| cli | ffprobe / ffmpeg（真实时长核对、抽接触表） |
| api | Doubao / Volcano 语音合成（seed-tts-2.0，需凭证；本 skill 未自带客户端，走项目 TTS 脚本） |
| cli | Edge TTS（免豆包 key，但需网络与 edge-tts CLI/Python 包） |
| network | 社交平台网页（用真实浏览器准备发布草稿，需用户确认后才提交） |
| reference | 口播写作参考（随包分发）：references/CODE-GARDEN-VOICEOVER.md |
4推奨統制措置と判定根拠
安全運用のための推奨統制措置
Agent 向け
段階的・都度認可、サンドボックス推奨
管理者向け
承認フロー、ロールバック可能、全履歴監査
判定根拠（ファイルパスと抜粋）
- scripts/: ローカルスクリプトまたはコマンドの実行: （本スキルディレクトリ内にはスクリプト、テンプレート、実行可能コードは含まれていません）
- 网络端点: 外部ネットワークアクセスの宣言: 音声合成：Doubao / Volcano TTS（プロジェクトのTTSスクリプトが認証情報を保持）またはEdge TTS（要インターネット接続、Doubaoキー不要）
- 本地工作目录: ファイルの読み書きと成果物出力: プロジェクト内：DESIGN.md（位置付け文および選択したTTSプロバイダ/音声/速度を含む）、assets/sync-script.jsonおよびそれから生成されるnarration関連ファイル
監査ノート： 本スキルのディレクトリ内にはSKILL.md、references/CODE-GARDEN-VOICEOVER.md、agents/openai.yamlのみが存在します（スクリプト、エンドポイント、認証情報を読み取るコードはありません）。オレンジ（Amber）判定となっているのは、SKILL.md自身が宣言している制作パイプラインに起因します：① **音声合成バックエンド**——デフォルトでDoubao / Volcano seed-tts-2.0（アカウント認証が必要）を指定し、キー不要の代替案としてEdge TTS（ネットワーク接続は必須）を挙げているため、ナレーション原稿が外部サービスに送信されます；② **公開下書き作成**——実ブラウザを使用してSNSプラットフォーム上で下書きを作成し、各項目を照合する指示が含まれます（アカウント関連の操作ですが、最終送信前のユーザー確認が義務付けられています）；③ **素材収集**——最新または外部の映像素材が必要な場合、検索を行ってホットリンクではなくローカルに保存するよう指示しています。これらはいずれも外部対象が予測可能であり、人間の確認や安全なフォールバック（Edge TTSはキー不要、下書き送信の抑止）が設定されています。TLSの無効化、--no-verifyの使用、自動化検出回避（AutomationControlledの偽装やキーストローク偽装）、サンドボックスの解除、任意コード実行などのセキュリティリスクは見られません。
5二重目の独立検証
- [ok] 本 skill 是否夹带脚本/凭证读取（档位下限依据） — find 目录只返回 SKILL.md、references/CODE-GARDEN-VOICEOVER.md、agents/openai.yaml；grep 无 process.env / fetch / curl 调用点。所有外部能力都以「指示」形式出现，由项目侧脚本或宿主 CLI 执行。
- [ok] TTS 外部依赖与凭证是否真实存在（橙档依据） — SKILL.md 原文给出 Doubao/Volcano seed-tts-2.0 + zh_male_liufei_uranus_bigtts + speech_rate=20 的项目默认，并写 'Edge TTS does not require the Doubao API key, but it still needs network access and the `edge-tts` CLI or Python package installed.' 即既确认凭证类后端存在，也确认有免 key 备选。
- [ok] 社交平台动作是否越界（是否会自动发布） — 原文 'When using a live browser to upload to social platforms, prepare drafts and verify fields, but do not click the final publish/submit button until the user confirms the exact platform, account, title/copy/tags, MP4, and cover.' 明确把最终提交留给人工确认，属安全阀而非绕过。
- [discrepancy] 文档里写死的本机路径对其他使用者意味着什么 — ［判定：私有前提，非缺陷］SKILL.md 写 'In `/Users/d2/project/web vidio` projects, default to Doubao / Volcano `seed-tts-2.0` …'——该默认值绑定作者本机目录；在别处使用需替换为本地路径/项目约定，否则「默认音色语速」这一段不适用（不是安全风险，但是可见的可移植性问题）。
- [ok] 字幕/时长是否真以实测音频为准（避免估算冒充） — SKILL.md 明写 'Do not estimate timing from character count, Edge TTS word-boundary metadata, or narration text alone when audio files exist.' 并要求对每段或最终音频跑 ffprobe、由真实时长重生成 sync-map.js；缺依赖时要求报阻断而不是静默换提供方或换慢速默认值。
- [ok] 仓库级验证/提交指示是否真在文档中（工程侧影响） — SKILL.md 末尾 'If the target is inside a git repository, inspect the diff, run verification, and commit the task-related changes unless there is no change, no repository, or a real blocker.'——即 skill 会指示 agent 做 git 提交；已在 file_writes 与 risks 中标注，供使用者知情。
6結論
最適な用途： HyperFramesを用いて中国語ナレーション動画（チュートリアル、解説、製品/機能紹介、ワークフローやケーススタディの分析、SNS向けショート動画など）を制作する個人または小規模チームで、Doubao/VolcanoまたはEdge TTSの音声生成環境およびnpm run check/renderスクリプトが用意されている（または導入予定の）環境に最適です。また、実測音声に基づいて字幕や画面の登場タイミングを厳密に制御したい場面にも適しています。
不向きな用途： 以下のケースには適していません：① クリック操作主導のWebプレゼンテーションを求める場合（同リポジトリのweb-video-presentationを使用してください）；② ナレーションテキストを外部TTSに送信できず、ローカルTTS環境も用意できない場合；③ 人手による目視確認を行わない完全自動化パイプライン（検収に目視リストが含まれます）；④ エージェントによるgitコミットを許可しないリポジトリ（ドキュメント末尾のコミット指示を修正するか、明示的に無効化する必要があります）。
Install Agent-Ready
① Verified Mirror 2026-09-28
Option A · Direct DownloadDownload hyperframes-teaching-video.tar.gz
sha256:
Option B · Copy Guide for Agent4d726d1ecfb6c878…Agent はこの JSON ガイドから自動的にダウンロードして検証します。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit f2c70b812b.