スタジオデモ動画
ユーザーが指定した任意の製品(macOSアプリ、ウェブサイト、CLIなど、画面録画可能なものなら何でも)の、約90~180秒のナレーション付きデモを構築します。唯一の固定部分はナレーションバックエンド、つまりvideo-studio-mlx Studio API(POST /studio/tts)で、声のクローンを作成し各行を検証します。デモの対象は任意で、毎回変わります。この分離を念頭に置いてください。デモの対象がvideo-studio-mlx自体であると想定しないでください(それはreferences/の中の単なる例です)。
核となる原則: ナレーション優先、正確な長さに基づくアンカリング
ナレーションは映像よりも前に生成します。/studio/ttsは各セグメントの正確な長さと単語ごとのタイムスタンプを返します。これらがタイムライン全体とすべてのフォーカスエフェクトを決定します。その後、映像をたっぷりと録画し、各クリップを対応するセグメントに合わせます。先にカットして後から音声を当てると、脆弱で再調整が困難になります。
通常、出力の音声を再生したり聞いたりすることはできません。これを厳格な制約として扱います。フレームを抽出して映像を検証し、完成したファイルの一部に対してASRを実行して音声の内容と同期を検証します。すべてをこの方法でチェックできるように構築します。
パイプライン
- シーンごとのストーリーボードを作成 — ナレーションのテキスト、画面上のアクション、キャプション、そして(シーンごとに)ナレーションが言及する要素(フォーカスが指し示すもの)を定義します。再生速度は約2.1語/秒を目標とします(≈170語 ≈ 80秒)。
references/storyboard.example.jsonを<work>/storyboard.jsonにコピーします。ナレーション内の各要素が、そのシーンの映像内で実際に表示され、順番通りに現れるように記述します。聞き手のために書く: 単語は書かれている通りではなく、話される通りに綴ります。略語や頭字語は展開します(「regex」ではなく「regular expression」、「v3」ではなく「version three」)、裸の記号(~、/、&)は避け、数字や単位は迷ったら単語で書きます。TTSはリテラルテキストを読み上げ、ASRはそれに対して検証するため、書き言葉専用の省略形は誤った発音とWERの歪みの両方を引き起こします。 - ナレーションを生成 —
scripts/generate_narration.py <storyboard.json>を実行します。各シーンのテキストを/studio/ttsにPOSTし、すべてのシーンを1つの固定された声(ユーザーのref_audio、または一度だけ設計するvoiceインストラクト — 下記参照)でクローンし、ASRで検証して、narration/manifest.jsonにセグメントごとのduration_s、wer、単語ごとのwordsを書き出します。(references/studio-api.mdを参照。) - ターゲットを録画 — アプリ/サイトのシーンごとに1つのクリップ(録画を参照)と、フォーカスが指し示す要素のための名前付き要素矩形マップを取得します。
- 合成 —
scripts/compose.py <storyboard.json>を実行します。映像をグラデーションのステージ上にフレーム配置し、Pillowでキャプションを焼き付け、ヒーローショットをスローでズームインし、ナレーションにアンカリングされたフォーカス(ズーム+リング)を適用し、シーン間をクロスフェードし、計算されたタイムライン上にナレーションを配置し、多重化(mux)します。 - 検証 — すべてのシーンのフィルムストリップを作成します。各フォーカスが発話される単語のタイミングでフレームを抽出し、ハイライトが指定された要素上にあることを確認します。ASRで2~3の部分を分析し、正しいセリフが正しいシーンに配置されていることを確認します。
前提条件
- Studio APIにアクセス可能であること(デフォルト
http://127.0.0.1:8100)。セットアップ、クローン作成、およびアライン/ワードタイムスタンプの契約についてはreferences/studio-api.mdを参照してください。 - クローン作成用に、3~15秒の参照用wavファイル(24kHz、モノラル)とその正確なトランスクリプトが必要です。最初に
/asrでトランスクリプトを確認してください(クローンの品質は音声↔テキストのアライメントに依存し、「推奨される」長さには依存しません)。 - ビデオ全体で1つの声を使用します。 各シーンは別々の
/studio/tts呼び出しであるため、声の一貫性は、すべての呼び出しが1つの共有参照をクローンする場合にのみ保たれます。ユーザーが参照音声を提供した場合は、それからクローンします。そうでない場合は、ストーリーボードにvoiceデザインインストラクトを設定し、generate_narration.pyが最初に1つのクリップをデザインし、そこからすべてのシーンをクローンします(キャッシュされるため、再実行時も同じ声が維持されます)。どちらもない場合、各シーンは独立して合成され、シーン間で音色が変化するため、実際のビデオでは避けるべきです。 avfoundation(macOSキャプチャ)、zoompan、xfade、gblurをサポートするffmpegが必要です。drawtextは多くの場合利用できません(libfreetypeがないため)。キャプションはPillowでレンダリングします。- ウェブサイトターゲットの場合: 決定論的な録画と要素ボックス取得のためにPlaywright(またはPuppeteer)が必要です。
ターゲットの録画
各シーンには、ターゲット製品から次の2つが必要です。
- 画面録画されたクリップ(ナレーションより長めに録画します — クリック後の結果表示やスピナー表示には数秒かかることがあります)、および
- 名前付き要素矩形マップ: ナレーションが言及するすべての要素について、映像ピクセル単位(合成クリップが使用する座標空間)でのその矩形。
ターゲットのUIツールキットによって、これらを取得する方法が決まります。2つのバックエンド:
macOSアプリ — AppleScript + ffmpeg avfoundation
avfoundation "Capture screen N"を録画し、アプリウィンドウにライブクロップします。一度プローブします(約1.5秒録画し、フレームを抽出してcrop=W:H:X:Yを確認します)。ディスプレイはRetinaであるため、物理クロップサイズ = DPR × 論理サイズ です(DPRは通常2です)。- System Eventsで操作します。このアプリのツールキットに適した信頼性のあるプリミティブを見つけてください — アプリごとに異なります。 繰り返し発生する一般的な注意点:
- SwiftUI/AppKitのリストでは、座標ベースのクリックはしばしば機能しません。代わりに要素に対してAX
select/AXPressを使用してください。 - セグメントコントロールは
AXRadioButtonとして公開されます。ロールでクエリしてください。 - ビュー切り替え直後のAXクエリは競合することがあります(空の結果を返す)。リトライするか、セッション内のナビゲーションを完全に避けてください。
- ナビゲーションが不安定な場合は、必要な状態でアプリを再起動します(起動引数、環境変数、アプリがサポートするURLスキーム経由で)。安価で決定論的です。
- SwiftUI/AppKitのリストでは、座標ベースのクリックはしばしば機能しません。代わりに要素に対してAX
-capture_cursor 0(AXアクションはポインタを動かさないため、カーソルはフレーム外に留まります)。可視カーソルが必要な場合は、後処理で合成します(フォーカスを参照)。- 要素マップ: 各要素のAX
position+sizeをクエリし、映像ピクセルに変換します:(グローバル位置 − ウィンドウ原点) × DPR。ツールキットがフィールドの矩形を隠す場合は、グリッド入りの映像フレームから測定します。両者が矛盾する場合(スクロール状態が異なる)、映像フレームを信頼します。各フォーカスフレームを検証してください。
ウェブサイト — Playwright(スクリーンキャプチャよりも推奨)
recordVideoで録画します。recordVideo.sizeをviewportと同じに設定し、合成前にwebmを目的のfpsに正規化します。- 座標空間(最も注意すべき点): Playwrightはビューポートサイズで録画するため、
recordVideo.size == viewportの場合、映像ピクセル == CSSピクセル になります。deviceScaleFactor: 2はレンダリングをシャープにするだけで、録画ビデオのサイズを拡大するわけではありません。また、recordVideo.sizeがビューポートより大きい場合、余白は単に黒で埋められます(ページは左上に1倍のまま配置され、拡大されて領域を埋めるわけではありません)。したがって、boundingBox()は映像ピクセルを直接返します — DPRを掛けないでください。(異なるサイズで録画する場合は、recordedSize / viewportで矩形をスケーリングしてください。)すべてのシーンを録画する前に、抽出したフレームに既知の矩形をオーバーレイして常に検証してください。DPRの誤った仮定は、すべてのフォーカスリングを静かに間違った場所に配置します。 - すべての矩形を1つの固定されたスクロール位置でキャプチャします。 最初にすべてのスクロールを実行し、安定させてから、すべての
boundingBox()を読み取り、その状態を保持します。リングは映像座標に存在し、カメラがズーム/パンしても固定されたままである必要があります。オートフォーカスを使用したい場合は、ページクロックからインタラクショントラックを出力します。 - 最初にページを安定させます。CSSアニメーション /
prefers-reduced-motionを無効にし、クッキーバナーを却下し、スクロールバーを非表示にし、waitForLoadState('networkidle')を使用して、カメラに何も飛び込んでこないようにします。アプリがサポートする場合は、ナビゲーション前にlocalStorageをシードするaddInitScriptを使用して自動認証を行います。 - モーション: 長いページの場合は、フルページスクリーンショットをキャプチャしてパンする(垂直のケンバーンズ効果)ことをお勧めします。ジッターのあるライブスクロールを録画するよりも優れています。
実際のモデル映像 — 本物の出力を示し、待ち時間を隠します。 シーンで実際のモデル(実際のキャプション/チャット/推論)をライブ実行する必要がある場合は、実際のフローを録画しますが、待ち時間をタイムワープします。各 クリック → 結果 の間隔(ページ開始からのモノトニッククロック)をマークし、その間隔のみをffmpegで圧縮します(trim+setpts+concat; アクションは1倍のまま)。そして最後のフレームをフリーズします(tpad=stop_mode=clone)。これにより、任意のシーン長を結果上で再生できます。最初にダミーリクエストでモデルをウォームアップします。コールドロードはウォームコールの10〜40倍の時間がかかる場合があります(例:ビジョンモデル:コールド約38秒 → ウォーム約5秒)。ワープされたクリップに合わせてナレーションの単語とタイミングを調整します。これらのシーンは通常の再生にします(アクションが動きを伝えます)。完全なレシピとスニペットは references/playwright-recording.md を参照してください。
完全に動作するmacOSの例(正確なセレクタ、環境フック、クロップ矩形、要素矩形、ターンキーレコーダー)が references/video-studio-mlx-app.md にあります。この例は、たまたまStudio APIをホストしているのと同じアプリをデモしていますが、その詳細は説明用として扱い、あなたのターゲットは独自のものになります。
合成(scripts/compose.py)
設定駆動型、ターゲット非依存。各シーンは正規化された1080pクリップになります。映像は、暗いグラデーションステージ(ソフトシャドウ)上のフレーム付きカードにスケーリングされ、Pillowキャプション(ステップ用のlower-thirdピル、ヒーロー用の大きなタイトル+サブタイトルスクリム)、クリップ+キャプションのフェード、そして共有の最終グレーディング(カラー調整 + Sカーブ + クールなシャドウ + ビネット + フィルムグレイン + デバンディング)が適用され、異なるキャプチャが1つの演出された映画のように読み取れるようになります("grade": false で無効にするか、ブロックを渡して strength/tint を調整します)。ヒーローシーンはシネマティックな処理を受けます。静止画に対するイーズアウトするドリフトするケンバーンズプッシュ、カードの背後にあるつや消しの暗い背景プレート、段階的なタイトル→サブタイトルのフェードイン。クリップはシーンごとの xfade トランジションで連結されます(デフォルトは fade。シーンごとに transition/xfade_dur を設定します — fadeblackはヒーローへの移行に適しています)。オーディオ: ナレーションは adelay でマスタータイムラインに配置され、amix(normalize=0)でミックスされます。オプションの music ベッドはVOの下でサイドチェインダッキングされ、最終ミックスはloudnormで −16 LUFS にマスタリングされます(VOのみの場合もマスタリングされます)。
フォーカスエフェクト — ナレーションにアンカリング(ズーム+リングが単語に追随)
フォーカスは、ナレーションが名指ししているものを、それが発話された正確なタイミングで指し示さなければなりません。そのため、フレーズ → 要素として作成され、単語のタイムスタンプからタイミングが設定され、手動で秒数を置いたり、シーン全体を1つの要素に固定したりすることは決してありません。シーンは view(どの要素矩形マップを使用するか)と focus リスト(要素/ビュー名はあなたのターゲットアプリが持つものなら何でも可)を宣言します:
"view": "main",
"focus": [
{ "say": "search", "element": "search_field" },
{ "say": "results", "element": "result_list" },
{ "say": "generate", "element": "primary_button", "zoom": 1.7 }
]
composeがそれを解決する方法:
- いつ —
resolve_phraseは、セグメントのwords内でsayに一致する連続する単語の実行を見つけ、[開始, 終了] を返します。繰り返し単語は曖昧ではありません。単語リストは位置情報を持つため、occurrence(デフォルトは最初)で選択します。クリップ時間lead + word_startで再生されます。 - どこで —
elementは、シーンのview下のelements.json内の矩形(またはmap:keyを使用して共有マップ、例えば永続的なサイドバーを参照します)です。 - カメラ — マルチキーフレーム
zoompan(focus_camera)、絶対的なonベースのスムーズステップ。2つのフォーカス間では、デフォルトでターゲット→ターゲットに直接グライドします。次のターゲットが遠く(前のズームビューポートの外側)にあり、かつ間隔が長い(focus_gap_full、約2.2秒)場合にのみ、フルビューに戻ります。つまり、隣接する/既に表示されている要素の場合は、ジャーキーなズームアウト/ズームインの代わりに少しパンするだけです。パンは一定速度(所要時間 = 距離 ÷focus_pan_speedpx/秒、focus_move_minによる下限あり)です。カメラは前のフレーミングを保持し、次の単語が始まる直前に到着するように固定px/秒でスライドします。近くのパンも遠くのパンも同じように感じられ、「遅くてから速い」ということはありません。"focus_pan": trueはすべての場所で直接グライドを強制します。 - リング — カメラの前に映像座標で描画されるため、ズーム/パンしても要素に固定されたままになります。フレーズの前後でフェードイン/アウトします。
- ズームとリングは分離されており、ズームは自動的にフレームに収まるようにクランプされます(
fit_zoom)。ハイライトされた要素が完全にフレーム内に収まるようにズームが減少され、幅広いターゲットの場合はリングのみ(z=1)に低下してトリミングされないようにします。デフォルトでそれらをペアにしないでください。両方とも視線を誘導するためにのみ存在します。ターゲットのサイズに合う方を選択してください。ring:falseはリングなしの穏やかなズームを提供します。
補助データと拡張:
- 要素マップ(
elements.json): 映像ピクセル単位の、ビューごとの名前付き矩形。取得方法は録画を参照し、各フォーカスフレームをチェックして検証してください。 - 表示するよりも大きくキャプチャして、ズームがシャープに保たれるようにします。カメラはネイティブ映像をオンステージサイズにトリミングするため、約1.7倍でも実際のピクセルが残ります。macOSではRetinaキャプチャがすでにオーバーサンプリングしています。Webでは、
deviceScaleFactorは録画ビデオのサイズを拡大しません(録画を参照)。オーバーサンプリングを得るには、オンステージカードより大きいviewport/recordVideo.sizeで録画します(例:幅1920でキャプチャし、約1456のカードに表示する)。DPRを上げるのではなく、これを行います。 - レコーダーはインタラクショントラック(
emit_track.py)を出力できるため、track_to_effectsはクリックごとにズーム+リングを自動的に導出します。インラインのfocusは正確なパスです。同じ矩形+単語時間を使用してcursor/spotlightオーバーレイ用の構造が開かれています。
デザインノート(なぜAPI側のキューマーカーではなくフレーズ→要素なのか): 単語のタイムスタンプはすでに位置情報を持つリストであるため、コンポジターが「どの要素 / どの出現箇所」を所有します。Studio APIは、あらゆる製品のデモに使用できるクリーンなプリミティブ(オーディオ+単語時間)を維持します。映像は、その瞬間に指定された要素(スクロールされていない/静的)を実際に表示している必要があります。そうなるようにナレーションを記述してください。
タイムライン計算(ビデオとオーディオの一貫性を維持)
- シーン長さ
d_i = narration_i + pad_i(pad≈ ステップ2 / ヒーロー3.4)。 - マスター上のシーン開始時間はトランジションごとに累積されます:
start_0 = 0、start_i = start_(i−1) + d_(i−1) − T_i。ここでT_iはシーンiへのxfade時間(シーンごとのxfade_dur、デフォルトはxfade。隣接する両方のクリップより短くなるようにクランプされます)。すべてのT_i = Tの場合、Σ d_(<i) − i·Tに簡略化されます。 - ナレーション
iをstart_i + lead(リード ≈ 0.8、着信クロスフェード後)に配置します。これは同じ再計算されたstart_iであるため、オーディオは同期されたままになります。tin_i + d_i ≤ソースクリップ長であることを確認します。