export-premiere

いつ使うか

• 「Premiere に出して」「XML を書き出して」と言われたとき。
• 05_timeline/timeline.json を外部 NLE で詰めたいとき。

前提条件

• timeline.json と asset ごとの media path が必要。
• 実務上は XML単体ではなく、XML・注釈・review・preview/final mediaを束ねた editor packet を既定にする。
• Studioで見えている完成状態を渡す場合、先に playback contract が exact であることを確認する。

やること（ステップ）

1. playback contract と packet readiness を確認する。

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

2. asset_id -> absolute file path の source map JSON を用意する。自動解決できない場合だけ明示mapを使う。

{
  "AST_31A9CDC2": "/absolute/path/to/file.MOV"
}

3. editor packet をエクスポートし、manifestを検証する。

swift run --package-path apps/macos-studio videoos-studio-cli handoff-export-packet <project-id>
swift run --package-path apps/macos-studio videoos-studio-cli handoff-packet-verify <project-id>

4. XML単体が必要な場合だけ従来CLIを使う。

npx tsx scripts/export-premiere-xml.ts projects/<project> --source-map /absolute/path/to/source-map.json

video clip に metadata.zoom / crop / position / render.effects が宣言されている場合、まず非破壊 preflight を行う。

node_modules/.bin/tsx scripts/export-premiere-xml.ts projects/<project> --preflight --json

bake_required は exit 2 であり、元映像を未処理のまま書き出してはならない。rights が operator_declared_ok|licensed、privacy が operator_declared_ok で、source-ledger / source-map / source-media-manifest / live file が一意に一致する場合だけ、明示 consent で video-only bake を生成する。

node_modules/.bin/tsx scripts/export-premiere-xml.ts projects/<project> --bake-visual-effects --json

固定 cache は 09_output/premiere-bakes、export authority は 09_output/premiere-exports/CURRENT.json。bake は H.264 CRF 14 near-lossless、BT.709 limited、single-thread、bframes=0 で、effect_editable:false の非編集可能な derived media。output-root override はない。canonical audio は元 source の独立 clipitem を維持する。

timeline.tracks.overlay の全クリップはXML生成前に検査する。現在登録済みのcanonical presetはmotion/font/layout/shadow/stroke/accent/panel/background/safe-area等の必須semanticsを持ち、Outline Textでは正確に表現できないため、構造化style errorでXML/receipt書込み前に停止する。登録済みplain-title exact routeは現在ない。caption trackはtitleに変換しない。

simple transition は crossfade を正確な Cross Dissolve、match_cut_bridge / match_cut を正確な Dip to Color としてのみ出力する。fade_to_black を Cross Dissolve に置換しない。transition ID と track 上の隣接 endpoint は一意、duration は明示的な正の整数、alignment は center、window は両隣 clip のtimeline区間内でなければ、XML/receipt書込み前に構造化エラーで停止する。source handle authority は生成せず、profile は report_only のままにする。

5. packet内の XML を Premiere Pro で File -> Import する。字幕が有効な案件では caption sidecar と承認artifactも編集者へ渡す。

出力 artifact

• 09_output/<project_id>_premiere.xml
• 09_output/<project_id>_premiere.roundtrip.json（XMLと同時生成されるapply用receipt）
• 09_output/editor_packet/manifest.json
• 09_output/editor_packet/media/*

注意事項

• script の auto-resolve は 03_analysis/ 内の top-level JSON にある asset_id と source_path を探す。canonical な assets.json.items[] は直接見ないので、assets.json だけでは足りないことが多い。
• source map が 0 件だと export は失敗する。
• 形式は Premiere 向け FCP7 XML。
• XMLをPremiereへ渡すときは、同時生成された.roundtrip.jsonも保持する。同じraw timeline.jsonからの再exportでは同じroundtrip_idになる。
• canonical overlayがある場合、legacy --titles / --auto-titles は重複titleを避けるため、解決結果が空でも書込み前に失敗する。
• canonical titleは全required semanticsがOutline Text parametersで表現できるpresetだけが対象であり、現在は該当presetがない。警告劣化やlegacy titleへの置換は行わない。
• packet verifyが通っても playback contractがstaleなら完成状態の保証にはならない。両方を確認する。
• 字幕有効時は packet manifest に caption_sidecar と caption_approval が含まれることを確認する。欠けていればpackage後にpacketを再exportする。
• synthetic fixture の成功は Premiere hardware proof ではなく、simple transition profile を昇格させない。
• bake manifest/index/receipt v2/READY が全て一致しても hardware_verified:false のままであり、editable effect、human approval、rights clearance、Premiere実機証明を主張しない。