mohdkhatab/shorts-video-studio

Shorts Video Studio

30〜60 秒、1080x1920 の MP4 + SRT + スクリプトを生成します。すべて手続き型 (Python + OpenCV + PIL + ffmpeg) で、キュー駆動型アニメーション エンジンによって視覚要素が正確に発話単語に一致します。

このスキルに含まれるファイル

• scripts/shorts_engine_template.py - 動作するリファレンス エンジン (9 シーン、9 背景、8 トランジション、オーディオ、音声同期)。コピーして編集してください。ゼロから書き直さないでください。
• scripts/tts_elevenlabs.py - REST API 経由でナレーションを生成します (ELEVENLABS_API_KEY が必要)。最初に --check と --list-voices を実行してください。
• scripts/review_frames.py - コンタクト シートと QA エビデンスを生成します。持続時間、コーデック、解像度、統合 LUFS、ラウドネス範囲、トゥルー ピークを確認します。失敗時は非ゼロで終了します。
• scripts/setup.sh - .venv を作成し、依存関係をインストールし、ffmpeg とフォントを確認します。その後 source .venv/bin/activate を実行してください。
• assets/fonts/ - 15 の OFL-1.1 フォント ファイル / 12 ファミリー + Noto Color Emoji (実際のアイコン)。ライセンスが含まれ、assets/fonts/LICENSES.md に索引があります。
• references/design-bible.md - パレット、フォント、アイコン ボキャブラリ、背景、トランジション、エフェクト、レイアウト グリッド。シーンをデザインする前に読んでください。
• references/script-and-voice.md - スクリプトの公式、ヒングリッシュのルール、事実確認ルール、音声とアラインメントの詳細。スクリプトを書く前に読んでください。

パイプライン (手順を順番に実行)

1. リサーチ - トピックがニュース/トレンドの場合、3 つ以上のソースをウェブ検索し、日付と数字を含む事実を収集します (「<日付> 時点」)。数字を決して捏造しないでください。検証できなかった主張はマークし、表現を穏やかにしてください (「レポート ケ ムタビク」)。
2. スクリプト - 約 45〜50 秒で 120〜140 語。最初の 2.5 秒でフック、7〜9 の短いビート、最後に CTA。script-and-voice.md を参照してください。script.txt として保存します (各シーン 1 段落)。
3. シーン計画 - 各段落が 1 シーン。各シーンについて、背景スタイル、パレット、2 つのフォント、アイコン (絵文字)、ヒーロー アニメーション、キュー ワード、次のシーンへのトランジションを決定します。下記のバラエティ ルールを適用します。計画を plan.md に書き込みます。
4. 音声 - スクリプト全体の ONE テイクのナレーションを生成します (tts_elevenlabs.py または ElevenLabs MCP)。voice.mp3 として保存します。オーディオをダウンロードできない場合 (サンドボックス)、ユーザーにファイルのアップロードを依頼します。その間、推定タイミングでビルドを進めます。
5. ビルド - テンプレートを video.py にコピーし、SCENES テキストを置き換え、bgN/dN 関数を記述し、HIT と TRANS を設定します。すべてのアニメーションの開始にキュー ルックアップ C(scene_idx, "spokenword", occurrence, default_seconds) を使用します。
6. テスト レンダリング - TEST=1 python video.py で PNG を出力します (終了状態、中間状態、各トランジションの 1 フレーム)。review_frames.py を実行するか、目視で確認します。QA ゲートが指摘するすべての問題を修正します。
7. 最終レンダリング - VOICE=voice.mp3 python video.py を実行します。デタッチド (setsid nohup ... &) で実行し、ログをポーリングします。フォアグラウンド呼び出しはツールのタイムアウトで強制終了される可能性があります。50 秒の動画で 1 CPU あたり約 1.5〜3 分です。ミックスは自動的に LUFS (デフォルト -16) にラウドネス正規化されます。
8. QA ゲート (下記) を最終 mp4 に対して実行し、video.mp4、captions.srt、script.txt、plan.md、qa_report.md を納品します。

バラエティ ルール (これにより、人間が作ったように見え、AI が作ったように見えなくなります)

これらのいずれかに違反すると、QA ゲートで FAIL になります。

• すべてのシーンは、独自の背景テクニックとパレットを持ちます (光線、シンセウェーブ グリッド、ハーフトーン サンバースト、コード レイン、グラデーション + ブロブ、設計図グリッド、ハザード ストライプ、レーダー リング、紙吹雪など)。隣り合う 2 つのシーンが同じになることは決してありません。1 つのグローバルな色も使用しません。
• 動画全体で 7 種類以上のフォントを使用し、カテゴリを混在させます (コンデンスド インパクト、チャンキー ディスプレイ、ワイド ディスプレイ、グロテスク、セリフ、イタリック セリフ、モノスペース、ピクセル、手書き)。1 つのシーン内では最大 2〜3 フォントに抑えます。
• 5 種類以上のテキスト処理: グラデーション フィル、太いアウトライン + ハード オフセット シャドウ、グロー、文字ごとのバウンス、タイプライター、ステッカー/ピル チップ、回転スタンプ、手書き傾き。
• 幾何学図形ではなく、実際のアイコン: カラー絵文字 (Noto Color Emoji) をアイコンとして使用し、アニメーション化します (オーバーシュートを伴うポップ、スピンイン、フロート、オービット、スイング)。テキストのみのシーンを決して納品しないでください。ブランド ロゴ (Adobe、GitHub のオクトキャットなど) は使用せず、一般的なアイコンを使用してください。
• 8 種類以上のトランジションを、シーン変更ごとに 1 つ使用します。グリッチ、ホイップ パン ブラー、ズーム スルー、アイリス + リング、スラット ワイプ、フラッシュ + シェイク、ピクセル化、プッシュ アップ。同じものを 2 回使用しないでください。
• インパクト モーメントには複合効果を組み合わせます。スパーク バースト + 衝撃波リング + カメラ シェイク + RGB スプリット + ブーム SFX。
• キャプション: 一度に 2〜3 語、太いアウトライン付きの大きい太字、現在の単語はシーンの色でハイライト、各チャンクに小さなポップ スケール。
• すべてにモーション: 何もアニメーションなしで表示されず、何も完全に静止しません (アイドル ウォブル / フロート / スロー ズーム 0 -> 3.5%)。

レイアウトとセーフ ゾーン (作業キャンバス 720x1280、1080x1920 にアップスケール)

• 上部 0〜130 px: クリアに保ちます (プラットフォーム UI)。タグ チップは y~62 のみ。
• コンテンツ ゾーン y 150〜830。キャプション ゾーンの中心 y = 950 (H-330)。下部 250 px: クリアに保ちます (プラットフォーム UI)。
• 幅の予算 640 px。あふれる可能性のある行には TXF(text, size, font, maxw) を使用します。推定幅 = 文字数 x 0.55〜0.75 x フォントに応じたサイズ (ワイド ディスプレイ フォントは約 0.75)。
• カウンター: 固定フォント サイズ、カウント中に自動縮小しません (ジッター防止)。

音声 + 同期 (概要。詳細は参考文献を参照)

• 1 テイクを取得し、次にアラインメントします。apply_voice_peaks は音節エネルギーのピークを検出し、DP マッチングでスクリプトの音節と照合します (約 0.2 秒以内で安定)。ALIGN=pauses は、明確なポーズがある低速の音声のフォールバックです。
• キューは、小文字に変換され、句読点が除去されたテキストがトークンで始まる最初の単語を使用します (数字: 完全一致)。繰り返される単語には occurrence を使用します。
• シーンの開始 = シーンの最初の単語 - 0.45 秒。合計時間は音声に従います (+1.2 秒のテール)。
• 音楽は合成され (パッド + キック + ハット + ベース + アルペジオ)、音声の下で約 55% ダックされます。音声にはハイパス + コンプレッション + loudnorm (-15 LUFS) が適用されます。トランジションごとにウーッシュ、インパクトにブーム、タイピング チック、カウンターにディン、CTA にポップ。

QA ゲート (審査/QA エージェントは納品前にすべてに合格する必要があります)

0. python scripts/review_frames.py out/video.mp4 out/contact.png 12 が PASS を出力する必要があります (そうでない場合は非ゼロで終了)。ラウドネスとピークは volumedetect ではなく、これから取得します。
1. 持続時間 30〜60 秒、1080x1920、h264+aac、統合ラウドネスがおおよそ -18 〜 -13 LUFS、トゥルー ピーク < -1 dBTP (クリッピングなし)。
2. 9 フレーム以上のコンタクト シート + 各トランジション フレームを確認。テキストのクリップ/オーバーフローなし、要素の重なりなし、上部 130 px または下部 250 px にタグ/キャプション以外の要素なし、キャプションがすべての背景で読みやすいこと。
3. バラエティ ルールが満たされていること (使用されたフォント、パレット、背景、トランジションを plan.md にリストします)。
4. 事実: スクリプト内のすべての数字/日付/名前が plan.md に記載されたソースにトレース可能であること。未確認の主張は表現が緩和されていること。ソースがない限り「コピー」/「盗んだ」という表現がないこと。関連する場合、アルファ/制限事項が述べられていること。
5. 同期スポット チェック: 5 つのキュー (フック ワード、数字、名前、トランジション、CTA) を選び、視覚要素が発話単語の 0.25 秒以内に開始することを確認します (SRT/SW 時間とフレーム タイムスタンプを比較)。 いずれかのチェックが失敗した場合: 修正し、再レンダリングし、ゲートを再実行します。残っている既知の問題は正直に報告します。

すでに遭遇した落とし穴 (回避してください)

• システム Python への pip install は、最近の Debian/Ubuntu では失敗します (externally-managed-environment、PEP 668)。scripts/setup.sh (.venv を作成) と source .venv/bin/activate を使用してください。--break-system-packages に手を出さないでください。
• ffmpeg volumedetect の mean_volume (無加重 dBFS) を LUFS ターゲットと比較することは無意味であり、以前のビルドでゲートに失敗する原因になりました。常に ebur128 で測定してください (review_frames.py が既に使用しています)。
• PIL 画像または非連続クロップに対する Image.fromarray は、TypeError: expected string or buffer を引き起こします。スプライトは連続した numpy 配列として保持してください。rcard() は PIL 画像を返します。配列ではありません。
• cv2.add への空の配列スライスはアサーション エラーを引き起こします。バンドをスライスする前に b > a をガードしてください。
• setsid nohup なしで開始されたバックグラウンド プロセスは、ツール呼び出しが戻るときに強制終了されます。
• サンドボックス化されたオーディオ生成 (MCP) はサンドボックスでダウンロードできません。ユーザーに mp3/wav のアップロードを依頼してください。
• ポーズベースの同期は、タイトな AI 音声では失敗します (-35 dB で 4 つのポーズのみ見つかる)。そのため、ピークベースのアラインメントがデフォルトです。
• 重複するキュー ウィンドウ: 2 つの要素が 1 つの発話単語を共有する場合、2 つ目を 0.2〜0.4 秒オフセットします。
• バリエーション セレクタ付きの絵文字 (例: シールド、警告) は、embedded_color=True で問題なくレンダリングされます。ダウンサンプリングは INTER_AREA、アップサンプリングは INTER_CUBIC でリサイズします。
• 欠落したフォントは、[warn] 行とともに DejaVu/Liberation に静かにフォールバックします。レイアウトを非難する前に、レンダリング ログで [warn] を確認してください。