insaneyilin/html-video-demo

HTML 動画とローカルナレーション

再生可能な MP4、字幕、継続編集可能な HTML ストーリーボード、および生成設定を納品します。ユーザーの現在のプロジェクト、素材、音色、スタイルを基準とします。これらのスクリプトは AI エージェント、アカウント、モデルサービスの API に依存しません。

開始前

• ターゲットプロジェクトの説明、既存の完成動画、ローカルの作業規約を読み、実際の機能とデモ範囲を確認します。計画段階の機能を既存の UI として見せないでください。
• 独立した動画プロジェクトディレクトリを指定し、元のコード、本番データ、旧バージョンの完成動画を復元可能な状態に保ちます。既存の動画を編集する場合は、最新の設定を読み込み、関連する出力をバックアップします。
• 確定済みの音色はそのまま使用します。新しい音色を選択する場合は、優先的に同一の短い原稿で等ラウドネス試聴を行います。既に選択されたプランについて、ユーザーに再度確認を求める必要はありません。
• 初回実行時、またはマシンを変更した場合は、環境とコマンド を参照してください。このパッケージの音声合成は Apple Silicon / MLX を必要とします。Node レンダリングのエントリポイントは音声合成から独立しています。

制作フロー

1. コンテンツを確定する。 視聴者が理解すべき操作を、因果関係が明確なストーリーボードにまとめます。各シーンには主要な情報を 1 つだけ含め、ナレーションは口語的に、画面には重要な文字情報を残します。コンテンツに応じてシーン数と総時間を決定し、固定の 9 シーンや 2 分テンプレートは使用しません。
2. 実際の素材を準備する。 デモデータを使って画面、部分的なスクリーンショット、実際の操作を収録します。ブラウザ操作は現在のエージェントとプロジェクトの要件に従います。画面と素材 を参照し、他のプロジェクトのスクリーンショット、個人情報、内部アドレスを再利用しないでください。
3. 音声を確定する。 project.json で音色、スタイル、言語を設定します。まず新しい音色の短いサンプルを聞き、その後バッチ生成します。隣接する意味段落をまとめて有界なナレーショングループとし、同じ音色、スタイル、サンプリングパラメータを使用します。文単位でランダムに種を変えたり、デフォルトで無限長の合成を行ったりしないでください。グループ化の原則は ナレーションとアライメント を参照してください。
4. コンテンツとタイミングを確認する。 独立した ASR で文の欠落や重複を見つけ、強制アライメントで原稿の位置を特定します。この 2 つは役割が異なります。アライメントは時間情報を提供しますが、実際にすべてのテキストが正しく発話されたことを証明するものではありません。同音異義語、英語の専門用語、最後の数文字を確認します。
5. 音声に合わせて画面を配置する。 実際のポーズ箇所で章を区切り、最後の文字が完全に終了することを保証し、コンテンツに適した余韻時間を設けます。デフォルトの約 1 秒は技術解説の開始点として適しています。部分的な強調や操作録画は、古いバージョンの固定秒数ではなく、音声マーカーに従います。
6. html-video でレンダリングする。 まず HTML のフレーム落ちをチェックし、次に ContentGraph、ProjectOrchestrator、Hyperframes を使用してエクスポートします。外部リソースはローカライズするか埋め込みます。アニメーションには window.__hvPlayAll() を使用し、フォント読み込み中の先送り再生を避けます。プロトコルについては 画面と素材 を参照してください。
7. 完成動画をチェックする。 MP4 を完全にデコードし、音声と動画の長さ、各カットポイントのオーディオトラックを確認します。その後、ブラウザでの再生、シーク、画面表示をチェックします。WAV や字幕ファイルのみのチェックでは、最終的な動画が正しいことを証明するのに不十分です。確認後、ローカルプレビュー、MP4、字幕、ソースファイルを提供します。

実行可能なエントリポイント

すべてのパスは引数で指定します。完全なフィールドは プロジェクトフォーマット を参照してください。以下の SKILL_DIR はこのスキルのディレクトリを、DEMO_PROJECT は独立した動画プロジェクトを指します。

python "$SKILL_DIR/scripts/audio.py" init --project "$DEMO_PROJECT"
# project.json を編集し、assets/ を準備します。必要に応じて、事前に audition を実行します。
python "$SKILL_DIR/scripts/audio.py" validate --project "$DEMO_PROJECT"
python "$SKILL_DIR/scripts/audio.py" synthesize --project "$DEMO_PROJECT"
python "$SKILL_DIR/scripts/audio.py" check-text --project "$DEMO_PROJECT"
python "$SKILL_DIR/scripts/audio.py" align --project "$DEMO_PROJECT"
node "$SKILL_DIR/scripts/compose.mjs" --project "$DEMO_PROJECT"
node "$SKILL_DIR/scripts/verify.mjs" --project "$DEMO_PROJECT" --stage scenes
node "$SKILL_DIR/scripts/render.mjs" --project "$DEMO_PROJECT"
node "$SKILL_DIR/scripts/verify.mjs" --project "$DEMO_PROJECT" --stage export
node "$SKILL_DIR/scripts/serve.mjs" --project "$DEMO_PROJECT"

Node のレンダリング、ブラウザチェック、スクリーンショットコマンドは、HTML_VIDEO_ROOT または --html-video を使用してインストール済みの html-video の場所を指定します。隔離された環境の Python を使用し、依存関係をシステム Python にインストールしないでください。

修正とトラブルシューティング

• テキスト変更：影響を受けるグループを再合成し、確認、アライメント、ビルド、レンダリングを実行します。画像やレイアウト変更：再ビルド、画面確認、レンダリングを実行します。音色変更：音声とタイミングのフローを最初から実行します。
• 音声がトークン上限に達する、または重複して出力される場合：問題のあるグループを短くし、検証済みの他のグループを優先して保持します。不完全な結果を成功として納品しないでください。連続して失敗する場合は、診断情報と利用可能な素材を残し、具体的なブロッカーを説明します。
• 末尾の文字が不完全な場合：「元の合成 → デコード長 → 正規化 → 連結 → MP4」の順に調査します。無音を追加しても、既にカットされた音節を補うことはできません。 現在のスクリプトは、Qwen3-12Hz のパディングなし長さに異常が検出された場合にのみローカル修正を有効にし、サードパーティのインストールディレクトリは変更しません。末尾問題と音声トラブルシューティング を参照してください。
• 今回の音色、配色、グループ数、特定バージョンのライブラリの欠陥を、すべてのタスクに対する固定要件として扱わないでください。別の TTS や既存のナレーションを使用する場合でも、同じ時間、サンプル、エクスポート検証の制約を維持します。
• 完成動画を外部プラットフォームに公開したり、業務資料をアップロードしたり、他者に通知したりすることは、デフォルトのローカル作成手順には含まれません。ユーザーの明示的な許可に従って実行します。