エクスポート(完成品)
これはチェーンの最後のセグメントであり、製品全体で唯一実際にピクセルを描画する場所です。
それ以前はすべてアノテーションです。台本には「どの単語を再生するか」、字幕には「画面に何を表示するか」、ビジュアルには「どのレイヤーを重ねるか」が記録され、 プレビューはこれら3つをリアルタイムで合成して人間に見せますが、ディスクには書き込みません。エクスポートはそれらを1つのファイルに焼き付けます。
必要 edit-list.json(必須)、subtitles.json、visuals.json + modules/
出力 完成品.mp4
前提ツール:マシンに Google Chrome が必要です(字幕とアニメーションを画像としてレンダリングするため)。デスクトップインストール元の
FFmpeg / FFprobe はアプリと共に Product 管理ディレクトリに含まれています。純粋な CLI インストールの場合は、システムに
ffmpeg ≥ 6 が必要です。Chrome がない場合は明確にエラーが報告されるため、回避しようとしないでください。Chrome がなければ字幕レイヤーとアニメーションレイヤーは存在しません。
最初に ビジネススキルのフェーズ契約 の「結論レベル」セクションを読み、実行します。エクスポートは編集ステートマシンには入りません。プロジェクトファイルを変更せず、CAS 書き込みも行わず、ステージを進めず、出力は新しいファイルであり、再実行すれば上書きされます。したがって、確認カードは必要ありません。
0. 準備
最初に 更新確認 の「準備確認」を実行します。スキルが最新か、ランタイムが対応しているか、プラグインルートもそこで特定されます(この記事のコマンド内の <プラグインルート> はすべてそのリテラルパスを代入します)。「準備完了」の場合のみ続行します。「新しいセッションが必要」または「停止」の場合は、その指示に従って処理します(「自作の代替インターフェースの禁止」禁令を含む)。ビジネススキル自体に環境ロジックは含まれません。
準備結果が runtime.kind=desktop-managed の場合、デスクトップアプリに既にインストールされている安定した CLI、メディアツール、および同じ launchd/windows-task サービスを直接再利用します。Electron パスを解決したり、FFmpeg/Bun を追加インストールしたり、2番目のランタイムを起動したりしないでください。
コマンド
node "<プラグインルート>/scripts/ensure-running.cjs" --json
node "<プラグインルート>/scripts/videocut-cli.cjs" export <プロジェクト> --dry-run --json # 計画を確認、エンコードしない
node "<プラグインルート>/scripts/videocut-cli.cjs" export <プロジェクト> --json # 完成品を出力(デフォルト2倍、ソースフレームレート)
node "<プラグインルート>/scripts/videocut-cli.cjs" export <プロジェクト> --out /パス/完成品.mp4 --json
node "<プラグインルート>/scripts/videocut-cli.cjs" export <プロジェクト> --scale 1 --json # ソースサイズのみ
node "<プラグインルート>/scripts/videocut-cli.cjs" export <プロジェクト> --keep-work --json # 中間ファイルとフレームPNGを残して調査用
ensure-running の身元が一致しない、ポート競合が発生する、またはサービスが正常でない場合は直ちに停止します。フォアグラウンドで一時的に代用してエクスポートを続行することは許可されていません。
2ステップ、2番目のステップだけを実行しない
① --dry-run で計画を報告 長さ、フレーム数、字幕画面数、ビジュアルレイヤー数、ズームインセグメント数、出力サイズ
ユーザーに読み上げます。数字が間違っていれば上流が間違っている証拠であり、10分のエンコードでは修正できません
② 実際に実行 アセンブル → オーバーレイ → コンポーズ → 検証の4段階の進捗
--dry-run 内の warnings はそのまま伝える必要があります。報告されるのは1種類の問題だけです:一部の字幕画面やビジュアルレイヤーの単語が既にカットされているため、完成品には表示されません。これは上流が決定すべきことであり、エクスポートが代わりに飲み込むべき問題ではありません。
解像度:ソースファイルが上限、まずソースを確認してから拡大
エクスポート前にソース解像度を確認します(--dry-run の source フィールドにあります):
ソース幅 ≥2560(Retina ネイティブ録画) → --scale 1、出力はネイティブピクセル、これが最良のケース
ソース幅 <1920(例:960×720) → 一旦停止:ユーザーに同じ録画の高解像度エクスポートがないか確認します。
録画ツールは同じ録画を3倍の解像度で再エクスポートできることが多く、
ソースを置き換える方が後処理よりも効果的です(次のセクション参照)。本当にない場合 → --scale 2
--scale 2 が低解像度ソースで有効な理由:ベース画像を拡大しても鮮明にはなりませんが、字幕とアニメーションは出力サイズに合わせて再描画されます。視聴者が実際に読むのはこれら2つです。プラットフォームで再度圧縮する際、大きな画像にはより多くのビットレートが割り当てられます。
「より鮮明にする」ために --fps を調整しないでください。 フレームレートはソースファイルに従います。変更すると、アニメーションのサンプリングと録画が一致しなくなります。
ソースの置き換え:ユーザーが同じ録画の高解像度版を提供した場合
これはエクスポートフローの一部ではありません。エクスポート自体は常に読み取り専用です。ソースの置き換えは、ユーザーが明確に承諾した後の独立した素材操作であり、完了後に通常のエクスポートに戻ります。
まず同じ録画かどうかを判定します(最初の2つで十分です):
ffprobe -v error -show_entries format=duration -of csv=p=0 <2つのファイル> # 長さがミリ秒単位で一致
ffmpeg -v error -i <ファイル> -map 0:a:0 -c copy -f md5 - # オーディオストリームがビット単位で一致
# さらに2~3フレームを抽出して画面内容を比較、目視確認
オーディオがビット単位で一致 = タイムラインが一致:ワード単位の台本、台帳、字幕、ビジュアルレイヤーはすべて単語IDにバインドされており、変更する必要はありません。これこそが「単語にバインドし、秒にバインドしない」という原則がソース置き換えで実現される点です。
ソース置き換えの4ステップ(2026-07-29 に実際に1回経験。③のステップを当時見落とし、クリッププレビューが即座に「生成失敗」と報告。フィンガープリント記録は1か所だけでなく、古いフィンガープリントを grep ですべて見つけてから対処):
① ファイルを置き換え input/source.mp4 と uploads/source.mp4 はハードリンクペア ——
両方を削除し、新しいファイルを input/ にコピーし、再び uploads/ にハードリンクを作成
(macOS は ln、Windows は New-Item -ItemType HardLink)
② フィンガープリントを更新 project.json の source.sha256 を新しいファイルのものに変更
③ 別の場所を確認 workbench.json の sourceSha256 もソースファイルのフィンガープリントを記録しており、
クリッププレビューパイプラインが検証するのはまさにこれ —— これを見落とすと、プレビューが生成を拒否
(これは製品の正しい動作です:フィンガープリントが一致しない場合は失敗し、古いプレビューを偽装しません)
④ 再エクスポート --scale 1 —— ソースを置き換えたのはネイティブピクセルのためであり、拡大しない
保険的な方法:検索ツールを使用して <プロジェクトディレクトリ> 内のすべての *.json で古いフィンガープリントの最初の8文字を検索し、 リストアップされたすべての場所を処理します(preview-edited/current.json などのキャッシュレコードは自動的に再計算されるため、手動で変更する必要はありません)。
オーディオが異なる場合(再録音、カット、長さの変更)はソースの置き換えではなく、新しいプロジェクトです: ワード単位の台本を再トランスクリプトし、すべてのアノテーションは無効になります。無理に適用しないでください。
検収:3つの項目、1つでも欠ければエクスポート完了とは見なさない
① コマンドが正常終了 製品自体が完成品のサイズ、フレーム数、オーディオトラックをカウントし、計画と項目ごとに比較。
一致しない場合は readback_mismatch エラーが報告され、ファイルはディスクに証拠として残り、
エクスポート完了とは見なされない
② フレームを抽出してピクセルを確認 完成品からフレームを抽出し、目視で確認。少なくとも以下をカバー:1つのズームインセグメント、
1つの全画面アニメーションセグメント、1つの字幕のみのセグメント、1つのレイヤー境界
③ 人間の聴覚チェック 実際に聞いた人はいないため、一律 human listening UNVERIFIED と記録
② はプレビュー画面で代用してはいけません。プレビューと完成品は2つの異なるレンダリングパスであり、検収で確認すべきはそれらが一致するかどうかです。 プレビューの画像を完成品の証拠として使用することは、確認すべきことを前提としてしまうことになります。
ズームインの判定には判別可能なランドマークを探し、全体的な印象に惑わされないでください(2026-07-29 に実際に踏みました):1.6倍ズームイン後の 画面ページはまだ「1ページ」のように見え、サムネイルでは全景とほとんど差がありません。正しいズームインフレームを「ズームインが失われた」と誤判定し、30分無駄に追跡し、2回再エクスポートしました。正しい判定方法は、トリミングによってのみ生じる証拠を探すことです: 半分にカットされた要素(バブルが中央で途切れる)、消えたエッジ要素(サイドバー、タイトルバー)。 ソースファイルの同じ時間のフレームと比較すれば、一目で確定します。
フレーム抽出には ffmpeg を使用:
ffmpeg -v error -ss 8.84 -i 完成品.mp4 -frames:v 1 -y frame.png
問題が発生した場合の確認場所
--keep-work を使用すると、プロジェクトの .chengfeng-videocut/export/ に3つのものが残り、
「どの半分が間違っているか」を直接分離します:
assembled.mkv 編集のみ、オーバーレイなし。これが間違っている = 台本またはカットが間違っている
overlay/*.png オーバーレイのみ、透明な背景。これが間違っている = 字幕スタイルまたはモジュールが間違っている
spans/*.mp4 合成後のセグメント。これが間違っている = ズームインまたはアライメントが間違っている
対照表:
完成品に字幕/アニメーションがない overlay PNG がすべて透明?モジュールが seek に応答していない?
アニメーションが最初のフレームで停止 モジュールが seek を実装していない、または GSAP タイムラインが paused されていない
画面全体が白 モジュールに `:root { color-scheme: dark }` がない
ズームインのフレームが歪んでいる モジュールの viewBox とレイヤーの zoom が同じ数値セットではない
完成品が計画より短い 特定のスパンのフレーム数が不足、コンポーズ段階のエラーを確認
レイヤー境界に一瞬元の映像が表示される overlay スクリーンショットが古い(フレームマーカー検証が機能していない)。製品はページ上部の
フレームマーカーバーで各スクリーンショットがどのフレームに属するかを証明します。再発時は、overlay
PNG の上部にマーカーバーがあり、コンポーズでそれをクロップしているか確認
Chrome が見つからない Google Chrome をインストール。別のレンダリングパスに変更しない
やってはいけないこと
- 「エクスポート成功」を「検収通過」と言ってはいけない。コマンドが正常終了したのは製品自身が一致しただけであって、映像が正しいことではない
- プレビュー画面、DOM、ログを完成品のフレーム抽出の代わりに使用してはいけない
- 誰も聞いていないのに human listening PASS と報告してはいけない
- エクスポートを通すためにプロジェクトファイルを変更してはいけない(字幕を変更、レイヤーを削除、台本を変更)。エクスポートは読み取り専用であり、書き込みはしない
- エクスポートで上流の作業を補完してはいけない:字幕が不足していれば字幕を作成し、ビジュアルが不足していればビジュアルを作成し、このセグメントで一時的にごまかしてはいけない