kinetograph-render

確認、チェック、レンダリング

コマンドにはエントリーを指定します。エントリーはプロジェクトファイル（.tsx、.ts、.jsx、.js）、.json シーン、または HTML ページ（その index.html、もしくはそれを格納するディレクトリ）です。--comp <id> でコンポジションを選択し（compositions <entry> で一覧表示できます）、--props '{"title":"Hi"}' または JSON ファイルのパスで props を渡します。-o を指定しない場合、出力先は out/stills/、out/sheets/、out/renders/ となり、パスが表示されます。

1. 確認する

PNG を開いて確認します。以下の Main はコンポジション ID です。

• kinetograph strip src/index.tsx -n 12：ラベル付きフレームを一度に 12 枚生成し、out/sheets/Main-strip.png に出力します。まずこれを実行してください。アニメーション全体を確認できます。--range 10..40、--cols N。
• kinetograph still src/index.tsx 45：1 フレームを生成し、out/stills/Main-f45.png に出力します。
• kinetograph onion src/index.tsx 0..60 -n 6：フレームを重ね合わせてモーションパスを表示し、out/sheets/Main-onion.png に出力します。

--scale N は、N 倍のサイズで描画します。範囲 a..b は a から b-1 まで、a..=b は b を含みます。

2. ピクセルを使わずにチェックする

• lint <entry>（--frames 0,45,89、デフォルトでは 8 フレームを間隔を空けて選択）：ボックスやキャンバスからはみ出すテキスト、キャンバス外のレイヤー、テキストの重なり、フォントやアセットの不足、型エラーを、それぞれフレームとレイヤー ID とともに報告します。すべての lint エラーを修正してください。フレームに表示される可能性のあるものだけをチェックします。不透明度が 0 のレイヤー（または不透明度が 0 のグループ内にあるレイヤー）と、クリップによって完全に隠されるレイヤーは、そのフレームではスキップされます。
• inspect <entry> --frame 45：すべてのレイヤーについて、解決後の位置、サイズ、bounds、matrix（キャンバスのピクセル単位）、エフェクト、テキスト行を表示します。画像を見て推測する代わりに使ってください。
• check <entry>：プロジェクトの（最も近い tsconfig.json を使って）tsc --noEmit を実行します。レンダリングでは型チェックされないため、prop のスペルミス（opactiy={0.5}）があっても、エラーなしで不透明度 100％で描画されます。lint は同じ問題を type-error として報告します。
• audio analyze <entry>：integratedLufs（null は無音を意味します。オンライン動画では約 -14 を目安にしてください）、truePeakDb（-1 未満に保ってください）、clippedSamples（0 が望ましい）、silences を表示します。--range、--scenes 0..90,90..180。
• snapshot <entry> --update：フレームを承認します（デフォルトは最初、中央、最後。--frames 0,30）。その後に snapshot <entry> を実行すると、__snapshots__/ と比較し、ピクセルが 2 レベルを超えて変化している箇所を報告します。
• bench <entry>：各ステージの所要時間を計測します（--frame、--runs、--range）。effects はエフェクトとそのフィールドを一覧表示します。

手順：strip の前に lint、render の前に strip を実行します。コマンドが失敗した場合は原因が表示されます。何かを変更する前に error.message と error.code を確認してください。

3. 診断する

doctor のみを実行すると、このインストール環境でできること、すなわちレンダラー、アドオン、CLI、スキルの各バージョンが表示されます。doctor <entry>（--range）は GPU を使わずにすべてのフレームで JS ステージを実行し、エンジンが描画できない内容を報告します（互換モード。描画可能な内容は kinetograph-markup に記載されています）。

• 正常なフレーム数（cleanFrames、unsupportedFrames、cleanShare）。
• 要素、プロパティ、理由ごとにまとめられた各問題。最も多くのフレームで発生したものが先頭です。問題が確認された values、要素の paths（$0.2 <div>、ホストツリー内の位置）、包括的なフレーム ranges が表示されます。property がある問題は、その要素の CSS プロパティに関するものです。null の場合は要素自体に関するものです。ページスクリプト独自の console.error や捕捉されないエラーも問題として扱われます。

上位の問題として示された内容を削除または置き換えてから、もう一度実行してください。100％正常なら、除外されたものはありません。still、strip、render も同じ内容を stderr に警告として表示します（--json では compat.leftOut）。--strict を指定すると、該当する最初のフレームで UNSUPPORTED_CONTENT により失敗します。DOM 要素や CSS を使うプロジェクトを長時間レンダリングする前に doctor を実行してください。

4. レンダリング

kinetograph render src/index.tsx は、音声付きの out/renders/Main.mp4 を書き出します。主なオプションは次のとおりです。

• --draft（半分のサイズ。--scale 0.5 と同じ）、--range 0..90、--concurrency 4（一度に描画するフレーム数。ファイルの内容は同じです）。
• 1080p から 4K にするには --scale 2 を指定します。このサイズで描画され、拡大処理は行われません。
• --codec h264|h265|prores|vp9|gif（出力拡張子は形式に合わせてください。prores は .mov、vp9 は .webm、gif は .gif）。
• --crf 20 または --video-bitrate 8M のいずれかを指定します。両方は指定できません。--prores-profile 4444、--pixel-format yuv444p、--audio-codec opus。
• --sequence を指定すると、動画の代わりに -o フォルダーへフレームごとに画像を書き出します。

不正な組み合わせを指定すると、変更すべき内容が表示されます。React は本番モード（高速）で実行されます。--dev-react を指定すると、React の警告が表示される開発ビルドを使用します。すべてのフラグ、アルファ、コーデックとエンコーダーのルール、および --sequence の詳細については、references/export.md を参照してください。

5. レンダリングを確認する

• 表示される概要で、サイズ、コーデック、エンコーダー、ピクセル形式、フレーム数、repeated、および renderer: の行を確認します。Skia GPU (...) は高速で、Skia CPU (...) は低速です。
• 長い映像の場合は、まず範囲を strip するか、--draft --range を指定してレンダリングし、タイミングを確認します。
• --json を指定した場合は、output と、除外された項目がわかる compat リストを確認します。
• 音声は audio analyze で確認します。透過レンダリングは、最初のフレームを PNG（--sequence）として開くか、アルファを表示できるプレーヤーで開いて確認します。