コードからYouTube動画:ショート動画と長尺動画
動画を、モーションデザイナーが行うような方法で、しかしコードで作成します。HTMLページが時間値から任意のフレームを描画し、ナレーションがタイミングを設定し、スクリプトが結果をレンダリング、ミックスし、アップロード前に検証します。
script.json ──► OmniVoice (MCP) ──► voice/*.wav ──► timeline.py ──► timeline.js ─────────┐
│ フォーマット: short | long | long-4k ▼
└─ スタイルプリセット ─► style.css / style.js ─────────────────────► page(s).html (seek(t), フォーマットごとのK.layout)
│ check_page ► stills ► render (キャッシュされたチャンク)
音楽(リクエストされた場合のみ) ─► make_music.py ─┐ ▼
効果音 (CC0) ─────────────────────────────────────┴─► mix_audio.py ─► mix.wav ─► mux ─► final.mp4 ─► verify_video.py
(長尺動画の場合: chapters.txt, captions.srt, thumbnail.jpg)
$SKILL はこのスキルのフォルダを意味します。すべての処理は1つのCLIコマンド python3 $SKILL/scripts/short.py <command> を通じて実行されます。
フォーマット
short | long | long-4k | |
|---|---|---|---|
| フレーム | 1080×1920 (9:16) | 1920×1080 (16:9) | ページ 1920×1080、出力 3840×2160 |
| 長さ | ≤ 180 秒 (最適 < 60 秒) | 任意 (通常 5–15 分) | 任意 |
| セーフゾーン | x 60–940, y 288–1440 (ショート動画UI) | x 96–1824, y 54–1026 (タイトルセーフ) | long と同じ |
| キャプション | 焼き込み (スタイルに合わせる) | captions.srt (YouTube用); 焼き込みはオプション | long と同じ |
| 追加要素 | — | チャプター、チャプターごとに1ページ、サムネイル 1280×720 | long と同じ |
プロファイルは engine/formats.json にあります。ページは K.W/K.H と K.layout({short, long}) テーブルを使用するため、1つのプロジェクトを両方のフォーマットで作成できます。16:9 動画については reference/long-form.md を読んでください。
フォルダ内の構成
| パス | 説明 |
|---|---|
scripts/short.py | パイプラインCLI: doctor, styles, init, style, kit, timeline, check, stills, thumb, music, mix, render, mux, verify, build |
scripts/timeline.py | 音声の長さ → シーンのタイミング、単語のキュー、キャプション、効果音キュー、ビートスナップ、ページセグメント、チャプター、SRT |
scripts/import_voice.py | OmniVoiceクリップを取り込む:変換、無音トリミング、不良TTSテイクを拒否 |
scripts/make_music.py | シンセサイズされたBGM(7つのムード)、ビートグリッド上、任意の長さ。ユーザーが音楽を要求した場合のみ |
scripts/mix_audio.py | 音声 + 音楽(ダッキング)+ 効果音 → −14 LUFS、トゥルーピーク ≤ −1.5 dBTP |
scripts/verify_video.py | 正確性のゲート:サイズ、アスペクト、コーデック、fps、フレーム数、A/V同期、ラウドネス、黒/フリーズフレーム、チャプター、セーフゾーンシート |
engine/formats.json | フォーマットプロファイル(サイズ、セーフゾーン、キャプションのデフォルト、制限) |
engine/render.cjs | Playwrightキャプチャ → ffmpeg H.264(モーションブラー、フレーム範囲、4K用2倍キャプチャ)、コンタクトシート |
engine/check_page.cjs | レンダリング前チェック:ページコントラクト、フォント、決定性、セーフゾーン、キャプション、テキストサイズ、空フレーム |
engine/kit.js | アニメーションツールキット(スプリング、キュー、キャプション、トランジション、フォーマットごとのレイアウト、Manim風描画/書き込み) |
template/ | 両方のフォーマットで作成可能な完全な作業用動画(エディトリアルスタイル) |
styles/ | 8つのスタイルプリセット: style.json + STYLE.md; 3b1b-math と kodekloud-devops には両方のフォーマットの完全なデモあり |
assets/ | フォント(OFL/MIT)とCC0効果音 |
reference/ | 該当する手順に達したときに読む(末尾の表を参照) |
ワークフロー
0. セットアップ(初めてのマシンで)
bash $SKILL/scripts/setup.sh # playwright + chromium を ~/.cache/yt-video に、numpy/scipy
python3 $SKILL/scripts/short.py doctor
1. ブリーフィング(1ラウンドの質問、その後作業)
1回のメッセージで質問します(可能な場合はAskUserQuestionを使用);ユーザーが既に言ったことはスキップします:
- フォーマット: ショート動画 (9:16) または長尺動画 (16:9, 1080p または 4K)。明白な場合(「ショート動画」「10分の動画」など)は推測します。
- トピックと視聴者が覚えるべきこと。スクリプト、記事、またはURLがあればそれも。
- スタイル:
short.py styles。デフォルトはeditorial。選択したらstyles/<name>/STYLE.mdを読んでください。 - 音声: クローン(参照クリップ + そのトランスクリプト)、デザイン(「女性、若年成人、低めの声、イギリス英語」)、またはデフォルト。
reference/voice-omnivoice.mdを参照。 - 音楽: 要求がない限りオフ。もしあれば:ムード(
make_music.py --list)。要求されていない音楽を決して追加しないでください。 - 長さ: ショート動画は20〜45秒(最大180秒)。長尺動画:目標に応じて;チャプターを計画します。
2. スクリプトを書き、承認を得る
reference/shorts-design.md(ショート動画)または reference/long-form.md(16:9)を読んでください。script.json を書きます(スキーマは reference/page-contract.md):1シーンにつき1つのアイデア;すべてのシーンの visual は、各ビジュアル変更がどの話された単語に当たるかを指定します;長尺動画のシーンには chapter タイトルを、長い動画の場合はチャプターごとに page を指定します。ユーザーにシーンテーブル(id、セリフ、ビジュアル、キュー単語;長尺動画の場合はチャプター)を表示し、音声を生成する前に承認または編集を待ちます。事実、数値、引用、結果を決して捏造しないでください;UIモックアップ内の例の値は問題なく、例示としてリストされます。
3. プロジェクトを作成する
python3 $SKILL/scripts/short.py init videos/<slug> --style <style> --format short|long|long-4k
テンプレート(またはスタイルの demo/)、kit.js、フォント、スタイルトークンをコピーします。承認された script.json を所定の場所に配置します(その format は保持します)。
4. OmniVoice(MCP)によるナレーション → voice/<scene-id>.wav
reference/voice-omnivoice.md に従ってください:OmniVoice MCPツールを見つけ、同じ音声設定でシーンごとに1クリップを生成し、それぞれをインポートします:
python3 $SKILL/scripts/import_voice.py <clip> videos/<slug> <scene-id> --text "<セリフ>"
無音、クリップ、または非現実的に速い/遅いテイクでは失敗します — それらは再生成します。OmniVoiceに到達できない場合はその旨を伝えます;推定されたタイミングでビジュアルを作成し、後で音声を追加することもできます。
5. タイムライン
python3 $SKILL/scripts/short.py timeline videos/<slug>
timeline.js(シーンと単語の時間、セグメント、チャプター)に加えて out/captions.srt を書き出し、チャプターがある場合は out/chapters.txt も書き出します。ビジュアルは K.cue('scene', 'word') を通じて単語にヒットします。
6. ページを構築する
reference/page-contract.md、reference/kit-api.md、reference/scene-patterns.md、およびスタイルの STYLE.md を読んでください。動画が両方のフォーマットで存在する可能性がある場合は、すべてのレイアウトに K.layout({short, long}) エントリを指定します。すべてのビジュアル変更はキュー単語上に配置されます。
7. レンダリング前にチェックする(低コストでほとんどの問題をキャッチ)
python3 $SKILL/scripts/short.py check videos/<slug> # すべてのページが PASS しなければなりません
python3 $SKILL/scripts/short.py stills videos/<slug> # out/stills*.png、セーフゾーンは赤で表示
スチルを自分で確認してください。 空、クリップ、重なり、読めない、スタイルから外れている、またはその単語と一致しないものがあれば修正します。フレーム0には既にフックが表示されている必要があります。
8. 音楽(要求された場合のみ)とミックス
python3 $SKILL/scripts/short.py music videos/<slug> # 音楽がオフの場合は何もしません
python3 $SKILL/scripts/short.py mix videos/<slug>
reference/music-and-sound.md を参照してください。
9. ドラフト → レビュー → 最終版
python3 $SKILL/scripts/short.py build videos/<slug> --draft # 30 fps、モーションブラーなし、1080p:高速レビューコピー
python3 $SKILL/scripts/short.py build videos/<slug> --final # モーションブラー、crf 16、long-4k の場合は4K
build はタイムライン → チェック → 音楽 → ミックス → レンダリング → mux → 検証を実行し、最初の失敗で停止します。レンダリングはチャンク化されキャッシュされるため、編集後の再ビルドでは変更された部分のみが再実行されます。最初にドラフトを送信し、最終版の所要時間を開始前に伝えてください(長尺動画の最終版は時間がかかることがあります;バックグラウンドで実行してください)。
10. 検証して納品する
verify_video.py は build の中で実行されます;MP4は VERIFY PASSED と表示されたときにのみ完了します。out/verify_sheet_<mode>.png(フレーム0 + シーンごとに1フレーム、UI/セーフゾーンが赤で表示)を開いて確認してください。reference/verification.md にすべてのチェックの説明があります。
長尺動画の場合は short.py thumb videos/<slug> も実行します(または専用の thumbnail.html をレンダリングします)。
納品物:MP4、プロジェクトフォルダ(index.html は実際のサウンドトラックでブラウザでプレビュー可能)、および短いメモ:シーンまたはチャプター、何が例示的か、音声設定、音楽のムード(または「音楽なし」)、検証サマリー(LUFS、トゥルーピーク、長さ);長尺動画の場合は chapters.txt、captions.srt とサムネイルも含めます。自分では聞けません:ユーザーに耳で確認するタイムスタンプを提供します(フック、最も忙しい効果音の瞬間、最も大きな音楽の瞬間、各チャプターの開始点)。
最も重要なルール
seek(t)は時間の純粋関数です。レンダリングパス内ではMath.random、Date.now、CSSアニメーション/トランジション、タイマーを使用しないでください。チェッカーがこれを強制します。- テキストはフォーマットのセーフゾーン内に収まるようにします。1080/1920をハードコードしないでください:
K.W、K.H、K.SAFE、K.layoutを使用します。 - フレーム0では意味のあるものが画面に表示され、何かが1〜2秒ごと(ショート動画)または数秒ごと(長尺動画)に動きます。
- ビジュアルヒットは話された単語(
K.cue)に合わせ、推測された時間には合わせません。 - 音楽はリクエストがあった場合のみ。効果音はスタイルのデフォルトに従います(ユーザーがオフにできます)。
- スタイルは指定されたクリエイターからインスピレーションを得ています;彼らのロゴ、マスコット、キャラクター、イントロ、または名前を画面に表示しないでください。
- 音声が「良い」とは決して言わないでください — 測定された数値と確認するタイムスタンプを報告してください。
参照ファイル
| 読むタイミング | ファイル |
|---|---|
| ショート動画を作成するとき | reference/shorts-design.md |
| 16:9 / 長尺動画全般 | reference/long-form.md |
| ページの構築、script.jsonのスキーマ | reference/page-contract.md |
| ツールキットの使用 | reference/kit-api.md |
| シーンのデザイン | reference/scene-patterns.md |
| スタイルの選択/作成 | styles/README.md, styles/<name>/STYLE.md |
| ナレーションの生成 | reference/voice-omnivoice.md |
| 音楽と効果音 | reference/music-and-sound.md |
| チェックに失敗した場合 | reference/verification.md, reference/troubleshooting.md |