HyperFrames 中文视频实战

HyperFrames 中文视频实战 は何をしますか？

HTML で動画を書き、エンジンが 1 フレームずつレンダリングして MP4 にします。このスキルは、2026 年 10 月に実際に制作した 6.5 分の中国語解説動画（実データ、音声、スクリーンショットを含む）の実戦から得た知見をまとめたものです。特に、公式ドキュメントには書かれておらず、実際に動かして初めてわかった落とし穴に焦点を当てています。

全流程（5 ステップ）

1. 初期化: npx hyperframes init <dir> → Node22+、FFmpeg が必要です。ローカル環境では HYPERFRAMES_BROWSER_PATH=/usr/bin/google-chrome を設定してください（エンジンが自動で chrome-headless-shell をダウンロードしようとしますが、ネットワークの問題で失敗する可能性があります。落とし穴#1 を参照）。
2. 構造とコンテンツ: メインの index.html で各シーンのサブコンポジションを連携させます。コンテンツ素材（実データやスクリーンショット）はまず scripts/sources.md に整理してから画面に載せます——情報密度は解説動画の生命線です。
3. アニメーション: 各シーンは一時停止状態の GSAP タイムラインを使用します。文ごとの字幕システム＋リズムハイライト（レシピは references/scene-recipe.md を参照）。
4. 検証: npx hyperframes check がすべて緑色になることがレンダリングの前提条件です。修復方法は references/pitfalls.md にまとめています（エラーの 90% はマニュアルに解決策があります）。
5. 音声（任意）: edge-tts で生成 → 実際の長さに合わせて話速を調整 → 音声ファイルは必ずメインの index.html のルート要素内に配置してください（サブコンポジション内では機能しません。落とし穴#6 を参照）→ 再レンダリング。
6. 品質チェックと納品: レンダリング後、npx hyperframes snapshot でキーフレームを抽出して 1 枚ずつ確認します（視覚的な自己チェックのサイクル：レンダリング→フレーム確認→改善→再レンダリング）。サムネイル画像は snapshot から直接出力し、他のツールは使いません。

重要なコマンド: プレビューは --background オプションを使用（ホットリロード可能）。1080p で 365 秒のレンダリングには約 9～10 分かかります（5 ワーカー・スクリーンショットモード、GPU なしの場合）。

いつどの資料を読むか

• エラーやレンダリングの異常が発生した場合 → まず references/pitfalls.md を確認（症状から検索可能。カメラの transform チェーンという未解決のエンジンバグに関する結論も含む）。
• 新しいシーンを書く場合 → references/scene-recipe.md（文ごとの字幕 JS テンプレートやアニメーションパターンの解説あり）。
• 音声を追加する場合 → references/voice-pipeline.md。
• 参考動画（抖音など）を分析する場合 → pitfalls.md の末尾「参考動画の定量的分解」を参照。
• 既存の動きの部品や同じ分野のスキル、音声のアップグレード、剪映との連携など外部ツールを探す場合 → references/ecosystem.md（オープンソースのエコシステムリスト。公式の capture --video による 1:1 再現方法も含む）。

付属スクリプト

• scripts/inject_subtitles.py —— 文ごとの字幕を一括注入（HTML/CSS/JS を一度に処理。手書きミス防止）。
• scripts/gen_voice.py —— edge-tts で一括生成＋シーンの長さに合わせて自動で話速調整（uv run で実行）。
• scripts/frame_audit.py —— レンダリングフレームの重心監査（画面のずれや空白を自動検出。カメラトラブルシューティングに必須）。

3 つの鉄則

1. シーンファイルを変更する前に必ず grep する: Studio は要素に data-hf-id を挿入することがあり、文字列置換が静かに失敗する可能性があります（落とし穴#2）。
2. 大きなキャンバスに対するカメラ方式には手を出さない: エンジンのレンダリングパイプラインは連続した transform チェーンを正しく駆動できません。複数の方法で検証しましたが解決策はありません（落とし穴#8）。アニメーションは要素レベルでのみ行ってください。
3. ナレーションのタイムラインを先に固定する: 字幕のタイミングと音声の長さがすべてのアニメーションのリズムを決定します。タイムラインを先に固定してからアニメーションを作成するのが、最も手戻りが少ない方法です。