render-video

name	render-video
description	Use when the user wants a final packaged video from an approved project and the project satisfies Gate 10 packaging prerequisites.
metadata	{"filePattern":["**/07_package/video/final.mp4","**/07_package/audio/final_mix.wav","**/07_package/package_manifest.json"],"bashPattern":[]}

render-video

いつ使うか

• 「レンダーして」「動画を書き出して」と言われたとき。
• rough cut ではなく package 済み deliverable を作る段階のとき。

前提条件

• 最終 package/render は scripts/package.ts を使う。
• npm run package -- projects/<project> [options] と npx tsx scripts/package.ts projects/<project> [options] は同じ入口。
• Gate 10 を満たしていること。 current_state: approved approval_record.status: clean または creative_override handoff_resolution.status: decided handoff_resolution.source_of_truth_decision: engine_render または nle_finishing gates.review_gate: open
• F-0023 の review_report.visual_qa が verified で min score 以上、または明示 waiver が必要。
• engine_render の場合、CLI は timeline.json の renderer ownership を解決し、 通常案件は既存 FFmpeg assembly を維持する。Remotion-owned overlay がある場合だけ Remotion、HyperFrames-owned element がある場合だけ透過 HyperFrames composite を使う。 05_timeline/render-report.json に freshness metadata を書く。
• caption が有効なら 07_package/caption_approval.json、BGM が有効なら 07_package/music_cues.json が必要。
• 通常のBGM bedは検証済みBGM Pack／レビュー済みライブラリ音源から選ぶ。Packが空でも案件内スクリプトで代替BGMを生成しない。
• 手続き生成音を使えるのは、provenanceで usage_class=simple_sound と明示された短い単純音だけ。通常BGMの代替にはしない。

やること（ステップ）

1. 高コストなassembly/renderより前に、最終描画と同じ字幕・固定フォント・章タイトルで 短尺レビュー・パックを作る。まず計画だけを表示し、対象区間と合計尺を確認する。

npm run final-render-review-pack -- plan \
  --project projects/<project>

--source はtimelineと時刻が一致する、字幕・Video OS章タイトルを焼く前の assembly/NLE完成映像を指定する。元カメラ素材や、すでに同じ字幕・章タイトルを 焼いた映像を指定しない。ffprobe実測の解像度、rational FPS、総尺、音声streamが timelineと一致しない入力はfail closedする。

npm run final-render-review-pack -- build \
  --project projects/<project> \
  --source projects/<project>/05_timeline/assembly.mp4

冒頭・中盤・終盤、代表的な問いかけ、最長/2行字幕、全章タイトルが自動選択される。 選択区間は一回のFFmpeg連結、HyperFrames描画一回、ASS字幕焼き一回で 06_review/final-render-review-pack/review-reel.mp4 にまとまる。同じ映像・視覚timeline projection・caption approval・固定フォントなら再利用する。音声方針だけの変更では 視覚レビューを無効化しない。 2. レビュー・リールをユーザーと確認する。Cockpitではside panelで動画を開き、 字幕本文、字幕ウェイト、章タイトルの大きさ、問いかけ/発話の同期を確認する。 dialogue-clean または loudness-only を選ぶ場合は、代表区間の未処理/処理後A/Bも 同じAskに添付し、試聴承認を得るまで最終承認しない。 3. 視覚レビューmanifestと音声判断をSHA-256へ拘束して最終レンダーを承認する。

npm run final-render-checklist -- approve \
  --project projects/<project> \
  --approved-by "<human>" \
  --captions approved \
  --typography approved \
  --sections approved \
  --visual-preview 06_review/final-render-review-pack/manifest.json \
  --audio dialogue-clean \
  --audio-preview 06_review/audio-finish-preview/manifest.json \
  --audio-preview-sha256 sha256:<hash> \
  --bgm none \
  --output-spec approved

creative brief、timeline、caption approval、music cues、視覚レビュー、音声試聴の どれかが変われば承認は自動的にstaleとなる。statusがreadyになるまで進まない。

npm run final-render-checklist -- status --project projects/<project>

4. Gate 10 と package 前提を読み取り専用preflightで確認する。Studioも同じJSON oracleを使う。

npm run package -- projects/<project> --preflight-only --json

終了コード0かつJSONのok: trueでない場合はpackageへ進まない。このコマンドはproject artifactを書き換えない。 5. engine_render path なら先に読み取り専用 preflight を行う。

npm run render-route -- projects/<project>

6. 表示された route が timeline.json の登録済み要素と一致することを確認して package CLI を呼ぶ。SNS / interview / event / longform というジャンル名だけを engine 選択に使わない。

npm run package -- projects/<project> --source-of-truth engine_render

7. nle_finishing path なら supplied final を検証用に渡す。

npm run package -- projects/<project> --source-of-truth nle_finishing --supplied-final projects/<project>/07_package/video/final.mp4

8. assembly.mp4 を手動管理する場合だけ --no-assembly または --assembly-path <path> を使う。 通常は自動生成に任せる。
9. Studio確認やNLE handoffを行う場合、最終timeline更新後に playback contract を確認する。

swift run --package-path apps/macos-studio videoos-studio-cli playback-contract-status <project-id>

status: exact でない場合は、古いpreviewを採用せずrender/packageを再実行する。manifestのhashだけを手編集して整合したことにしない。 10. speech-led / interview の場合は 07_package/qa-report.json で総尺差だけでなく dialogue_timeline_alignment_valid も確認する。raw_dialogue.wav の実信号が timelineのdialogue window外へ1フレーム以上出ていれば公開候補へ昇格しない。 11. VFR素材で口の同期を調整した場合は、選んだ映像フレームを固定し、映像・音声の source offsetを別々に実測する。残差は音声側で補正し、別プレイヤー／診断proxyの 見え方だけを根拠に演出尺を変更しない。 12. 字幕・章タイトルの映像が承認済みで、MAだけを変更する場合はフル映像を再エンコード しない。承認済みcaption-finalize receiptを入力にし、映像stream hashを不変のまま 2-pass MA音声だけを再muxする。

npm run audio-finish-remux -- \
  --project projects/<project> \
  --source-receipt projects/<project>/07_package/caption-finalize/generations/<id>/caption-finalize-receipt.json \
  --finalize

source generationが現在の最終承認にすでに拘束済みなら、二重MA防止のためfail closedする。 13. YouTube等への外部公開はrender/packageとは別gateとする。対象hashにcreative・rights・ privacy承認と公開先を束ねた07_package/publication_approval.yamlを作り、外部write直前に 次を通す。

npm run publication-preflight -- projects/<project> --platform youtube --visibility unlisted

出力 artifact

• 07_package/video/final.mp4
• 07_package/video/raw_video.mp4
• 07_package/audio/raw_dialogue.wav
• 07_package/audio/final_mix.wav
• 07_package/captions/*.srt / *.vtt 必要な場合のみ
• 07_package/qa-report.json
• 07_package/package_manifest.json
• 09_output/final.mp4
• 05_timeline/assembly.mp4 と 05_timeline/render-report.json (engine_render 自動生成時)
• 07_package/logs/render-route.json
• 07_package/logs/audio-mix-report.json

注意事項

• --skip-render は検証/テスト用途。通常の deliverable 作成では付けない。
• --no-assembly は自動生成を止めるため、05_timeline/assembly.mp4 が無い場合は packaging が失敗する。
• --assembly-path は Remotion-owned element を含む timeline では使わない。描画済みか 証明できない prebuilt assembly は fail closed になる。
• project artifact に任意 JSX / HTML を生成しない。Remotion / HyperFrames は allow-list 済み content-element/v1 template からだけ起動する。
• music_cues.json がなくても final_mix.wav は生成される。no-BGM path もraw dialogueを2-pass MAし、失敗時は未処理音声へ黙ってフォールバックしない。
• ライブラリ候補が未レビュー／未インストールなら、no-BGMまたは人間レビューで停止する。品質未確認の手続き生成BGMへフォールバックしない。
• caption_burn と audio_mix の実行ログは 07_package/logs/*.log に出る。
• 字幕有効時は final映像だけでなく 07_package/captions/*.srt / *.vtt と caption_approval.json の存在も確認する。
• BGMありではBGMを基準 -23 LUFSへ正規化してからeditorial gainを適用し、A1 clipの占有区間ではなく実際のdialogue waveformでsidechain duckingする。
• audio-mix-report.json の audio_mix_policy_valid と、実測の loudness_target_valid が両方passして初めてMA完了とみなす。
• FFmpeg graphではsource atrimをadelayより前に置く。同一input branchの adelay=...,atrim=start=0は禁止。全体尺のtrimはamix後だけに置く。
• 外部公開／共有に使うのはQAを通過して09_output/final.mp4へ昇格した1本だけ。 preview-v*や診断proxyをアップロード対象にしない。
• publication-preflightは承認後のfile差し替え、QA未通過、manifest hash不一致、未承認の visibilityをfail closedにする。upload成功、remote processing完了、Slack投稿成功は preflightとは別にremote側で検証して記録する。