KyaniteLabs/kinocut

kinocut は何をしますか？

エージェントが FFmpeg コマンドを手書きする代わりに、構造化されたビデオ編集インターフェースが必要な場合に Kinocut を使用します。MCP ツール、Python クライアント、CLI を公開し、編集、分析、字幕、オーディオ、Hyperframes、レイヤー合成、ローカルでの再利用ワークフローを提供します。

デフォルトパス（最初に行うこと）

1. kino doctor を実行し、次に kino --format json info <file> を実行します。
2. 不慣れなタスクの場合は、ユーザーのタスク（例：「フィラーワードを削除」や「顔をフレーム内にキープ」）を指定して search_tools を呼び出し、返されたツールの必須入力を確認します。サポートされているインテントについては video_intent で計画を立てます（goal= を指定するとカットファイルがコンパイルされます。360/desk/table/x4 の goal は 360_assembly_plan も提案します）。提案が実際にリクエストを満たしていることを確認してからレンダリングします。
3. レンダリング（video_cutfile_render、video_edit、ワークフロー、または単一のエンジンツール）。360 の場合：その計画に対して video_review_decide で承認/却下を行ってからレンダリングします — proposed 状態の計画をレンダリングしないでください。.insv は拒否されます。ステッチ済みの 360 MP4 が必要です。ガイド：docs/360_ASSEMBLY.md。
4. video-quality-check / assert_quality。repurpose と shorts-package は、スキップまたは allow_fail が指定されない限り、スコア 80 で失敗クローズします。
5. 人間による視覚/聴覚レビュー。レシートを公開済みとして扱わないでください。

詳細（レスキュー、救済、合成、Hyperframes、Thin Sound S12）：docs/TOOLS.md、docs/RESCUE.md、docs/WORKFLOWS.md。ワークフロー許可リスト：probe、trim、resize、convert、crop、add_text、merge、composite_layers、burn_in。

必要に応じて関連ガイドを読み込んでください。編集の選択にはソースの証拠を使用し、名前、数字、否定、限定詞を保持します。不足している証拠やサポートされていないアクションについては、ソースの主張、タイムスタンプ、または機能をでっち上げる代わりに報告します。計画ツールは編集を提案しますが、その存在が必要な検出器やモデルが実行されたことを意味するわけではありません。コードがタイミング、変換、検証、実行を所有し、人間によるレビューはモデルの判断とは別に残ります。

Revideo ローカルコードビデオフロー（開発のヒント）

呼び出し側が検査可能なステージングプロジェクトを必要とする場合は、revideo_materialize、revideo_install、revideo_render を使用します。同じガード付きの手順を1回の呼び出しで行うには revideo_render_job を使用します。提供されたシーンは信頼された実行可能な TypeScript です。使用前に検査し、信頼できないシーンコードを決して実行しないでください。依存関係のインストールは npm にアクセスする可能性があります。レンダリングは Kinocut の固定テンプレートに対してローカルで実行されます。レンダーレシートは、観測されたメディアと出力バイトを、正確な境界を持つディスク上のジョブファイルダイジェストにバインドします。.mp4、.webm、.mov は、固定された MP4、WebM、ProRes 4444 エクスポーターモードを選択し、公開前に検証されます。レシートを出力バイトに対して検証し、video_quality_check と video_release_checkpoint を実行してから、人間による視覚レビューを要求します。

開始するには

• ../../README.md を読んで、インストール手順と安全契約を確認します。
• FFmpeg / Hyperframes / AI 拡張機能の前に kino doctor を実行します。

インターフェースを選択

• MCP：Claude Code、Cursor、Codex スタイルのクライアント、およびその他のエージェントホストに最適です。uvx --from kinocut kino で設定します。
• CLI：直接的なローカル編集、クイック診断、composite-layers --dry-run、バッチジョブ、CI 対応の JSON 出力に最適です。
• Python クライアント：構造化された結果、出力パス、保存されたレイヤープランレシートを必要とする反復可能なパイプラインに最適です。

360 デュアルカメラアセンブリ（バージョン 1.14.0 で公開）

ソースが任意のカメラ（Insta360、Ricoh Theta、GoPro MAX、DJI Osmo 360 など）からのステッチ済み equirect 360 MP4 であり、要求が分割/スイッチ/PiP/単一の2つの仮想カメラである場合に使用します。

1. video_intent(verb="reformat_vertical", goal="desk 360 split 9:16", source=ABS_PATH) または Client.propose_360_assembly(...)。
2. カメラ、レイアウト、ストーリーボードの静止画を表示します。yaw/pitch をでっち上げないでください。
3. video_review_decide / Client.decide_360_assembly で approve または reject。
4. 承認された計画のみをレンダリングします（Client.render_360_assembly または video_review_decide + output_path）。

video_360_* という MCP ツールや kino 360 コマンドはありません。CLI の intent と review-decide はこのコンパイラを実行しません。ディレクターフックは注入された JSON プロポーザーを受け入れます。設定されたモデル名だけではモデルを実行しません。クラウドプロポーザルには allow_cloud が必要です。ディレクターは決してピクセルを書き込みません。

製品 / オブジェクトマット（バージョン 1.15.1 で公開、現在は 1.15.3）

オプションのオブジェクトマット拡張機能は、公開されたバージョン 1.15.3 で利用可能です。既存の hyperframes-remove-background / hyperframes_remove_background コマンドを使用します。デフォルトのモデルは人物です。カタログ SKU、ジュエリー、ボトル、靴、パッケージ、または人物以外のものの場合：

1. hyperframes_remove_background(info=true) — モデルをリストします。ダウンロードはありません。
2. pip install "kinocut[object-matte]" してから model="birefnet-general" を設定します。
3. 製品ビデオにはオプションで --mask-interval 3。残ったターンテーブル/スタンド/三脚/スイープ用のオプションの機器オーバーレイ。
4. composite-layers を使用してショッププレートに合成します。すべての src を仕様ディレクトリ内に保持します。

video_product_matte をでっち上げないでください。これは新しい MCP ツールではありません。オブジェクト拡張機能がない場合に人物モデルにフォールバックしないでください。ガイド：docs/PRODUCT_MATTE.md。例：examples/product-matte/。

専用ビデオレスキュー

リクエストがローカルクリップ1つを修正することであり、そのソース、ストーリー、タイムラインを保持する場合は、video_rescue_*、rescue-*、または Client.rescue_* を使用します。

必須のシーケンス：

1. 計画を呼び出し、計画アーティファクトを保存します。
2. safe_repairs、recommendations、unavailable_repairs、blocked_repairs、プレビュー、パッケージインテント、機能、見積もりをユーザーに提示します。
3. レンダリング前に計画を検査します。safe_repairs 内の ID についてのみ明示的な承認を取得または推論します。ID リストを省略すると、レビューされた計画内のすべての安全な ID を意味します。
4. 承認された安全な ID のみを指定してレンダリングを呼び出します。
5. レンダーレシートを検査し、パッケージパス、利用できないサイドカー、整合性、ゲーティング検証、プライバシー、再開、クリーンアップ状態を報告します。

未レビューの計画から直接レンダリングしないでください。承認に recommendation ID、unavailable ID、blocked ID を追加しないでください。クラウドツールを使用したり、レスキューキャプションを書き込んだり、ソースを書き換えたり、unavailable を自動的な失敗として扱ったりしないでください。キャンセルまたは検証の失敗は、プロモートされないか、隔離されたままにする必要があります。

決定論的 AI ビデオ検査

生成された映像が編集の決定前に証拠を必要とする場合は、video_ingest、video_preflight、video_inspect_temporal（またはフラットな CLI および Python の同等品）を使用します。最初に取り込み（インジェスト）し、その後、返されたハッシュでアセットを参照します。そのアセット ID をホストパスに置き換えたり、パブリック境界で AssetRecord を構築したりしないでください。時間的検査は、完全なサンプルフレームとモーションストリップパッケージ、決定論的所見、および明示的に利用できないプロバイダー機能を返します。プロバイダーの不在は予期されており、ダウンロードやネットワークフォールバックをトリガーしてはいけません。

ガバナンス付き AI ビデオレビューと救済

正確なアセットの編集判断と派生物の回復には、video_verdict、video_acceptance_eval、video_body_swap、video_salvage（またはフラットな CLI および Python の同等品）を使用します。承認されていない評決はエージェント分析をキャプチャする可能性がありますが、承認された処分は、アクティブで正確な人間の決定を、明示的な要件、役割、およびアーティファクトの証拠とともにバインドする必要があります。受入評価は承認アクションではなく派生であり、すべての救済出力は新しい未承認のレビュースロットから始まります。

決定 ID をでっち上げたり、保存されていない承認を渡したり、強制/オーバーライドルートを探したりしないでください。呼び出し側が明示的なポリシーを選択しない限り、ボディスワップは期間の不一致を拒否します。救済には、既存のプライベートプロジェクト、保存されたソースアセット、境界のあるレシピポリシー、正確な受入仕様 ID が必要です。

受入評価は、アクティブに保存された acceptance_spec_id と verdict_ids を取ります。呼び出し側が構築した証拠オブジェクトは決して使用しません。パブリックボディスワップは常に最初に project_dir を取り、両方のソースパスがその正確なプロジェクト内のアクティブなアセットに解決される必要があります。

このワークフローを操作する前に docs/AI_VIDEO_REVIEW_AND_SALVAGE.md を読んでください。すべての派生物を新しい未承認の作業として扱い、公開前に明示的な人間の視覚/聴覚ゲートを維持してください。

レスキュー後の計画

リクエストが意味的検索、通常のクリーンアップ編集、被写体認識変換、復元、合成、クリエイティブコーディネーション、またはリモート出力を必要とする場合は、対応する video_* MCP ツール、フラット CLI コマンド、または Client メソッドを使用します。JSON 互換の証拠と意図を渡します。返された計画と差分を、別個のレンダリングステップの前に提示します。

ソースの説明をでっち上げたり、不確実性を隠したり、計画から承認を推論したり、ローカル実行基盤がないことをクラウドプロバイダーを使用する許可として扱ったりしないでください。リモートワークには、別個の出力マニフェストと承認が必要です。証拠や機能が不足しているプランナーは棄権しなければなりません。

レイヤー合成

編集が画像、ビデオ、またはソリッドレイヤーの順序付きスタックである場合、特にローワーサード、ピクチャーインピクチャーバリアント、ブラーバックプレート、マスク/マット、またはプラットフォーム固有のレイアウトバリアントの場合は、composite-layers / video_composite_layers を使用します。

エージェントが変換、不透明度、開始/継続時間ウィンドウ、マスク/マットアルファソース、または公開前にレビューできるレシートを必要とする場合は、生の FFmpeg フィルターグラフよりもこのパスを優先します。

計画優先フロー：

1. canvas、順序付けられた layers、明示的な output を持つ JSON 仕様を記述します。
2. kino composite-layers --spec layers.json --dry-run --save-layer-plan layer-plan.json を実行します。
3. レイヤープランを検査します（ソースハッシュ、フィルターグラフハッシュ、変換、回転/ピボット、ブレンドモード、タイミングウィンドウ、マスク）。
4. 計画が正しいように見えた後にのみレンダリングします。
5. video-quality-check、storyboard または thumbnail、video_release_checkpoint を実行します。

コンポジターは、許可リストに登録された全キャンバスおよび配置されたブレンドモード（multiply、screen、overlay、darken、lighten）を、不透明度とタイミングウィンドウとともにサポートします。レシートは layer_plan v2 のままです。normal 以外のブレンドは、2つのジオメトリで不透明度と start/duration ウィンドウをサポートします。明示的なサイズ設定なしで {0,0} にある全キャンバス、または正の整数 width と height および非負の整数のキャンバス内位置を持つ配置された矩形です。RGB ブレンディングは、サブサンプリングされたクロマプレーンに色演算を適用することを回避します。スケール、回転/ピボット、マスク/マット、小数位置、キャンバス外矩形は延期され、unsupported_blend_geometry で失敗クローズします。ビデオレイヤーとビデオマスクは、宣言された開始時に再生を開始します。すべてのソースとマスクを仕様ディレクトリ内に保持します。出力はビデオのみです。anchor は pivot とは異なる位置のエイリアスです。回転 + マスク、オーディオ合成、フル NLE アダプターは延期されたままです。人間のレビューの前にレシートを検査します。これをフル NLE の代替として扱わないでください。

エージェントワークフローエンジン

編集が単一のツール呼び出しではなくマルチステップジョブである場合は、ワークフローエンジンを使用して、1つの JSON ジョブ仕様から計画、検証、レンダリング、回復、証明を行います。video_workflow_*（MCP）、workflow-*（CLI）、または Client.workflow_*（Python）を通じて実行します。操作は小さな許可リスト（probe | trim | resize | convert | crop | add_text | merge | composite_layers | burn_in）であり、検証済みのエンジンにバインドされています。メディア参照はシンボリック（@sources.*、@work/*、@outputs.*）であり、ワークスペースに制限されています。すべてが失敗クローズします。../../docs/WORKFLOWS.md を参照してください。

計画 → 検証 → レンダリング → 検査 → 再開：

1. workflow-validate --spec job.json — 安価な構造的ゲート。何もレンダリングしません。
2. workflow-plan --spec job.json --save-plan plan.json — ドライラン操作グラフ + ソースプローブ/ハッシュ。メディアをゼロレンダリングします。
3. workflow-render --spec job.json --save-receipt receipt.json — 順次実行。来歴レシート（ステップごとのハッシュ、クリーンアップマニフェスト、決定論の注意書き）を出力します。バッチバリアントには --all-variants を追加します。
4. workflow-inspect --receipt receipt.json — 読み取り専用の整合性再チェック + レシートを信頼する前の人間レビューへのポインタ。
5. workflow-render --spec job.json --resume receipt.json — 中間ファイルを保持したまま失敗したジョブを再開します（変更された仕様では失敗クローズ）。

レシートはワークスペース相対パスのみを保存します。仕様とサンプルレシートには、ホームパス、ユーザー名、トークンを含めないでください。

ワークフロー

1. 最初に入力を検査します：kino info <file> または MCP/Python の同等品。
2. リスクの低い計画を立てます：トリム、リサイズ、オーディオ正規化、字幕、オーバーレイ、エフェクト、または Hyperframes レンダリング。
3. 高価または破壊的なエクスポートの前に、プレビューまたはドライランマニフェストを優先します：
   • クイックな視覚レビューには preview。
   • repurpose の前には repurpose-plan。
   • フルレンダリングの前には Hyperframes の inspect、snapshot、または still。
   • 保存されたショートプランの場合：shorts-plan-show → shorts-review → shorts-render → shorts-package。
   • Thin Sound の場合：sound-capabilities の後に sound-plan-validate / sound-voice-batch / sound-mix-render / sound-qa-loudness / sound-qa-asr（または kino sound <action>）。
   • サウンドの継続時間、ゲイン、ラウドネス、プロファイルバージョンには数値を指定します。ブール値は強制変換前に拒否されます。明示的に無効なプランは、サンプルプランを選択できません。型指定されたプランは再検証されます。フィールド固有の互換性ルールについては docs/SOUND_INPUT_VALIDATION.md を参照してください。
   • 実際の ASR はハッシュ化されたオーディオ/リファレンスリクエストと明示的なルートを使用します。そのトランスクリプト ZIP を保持し、不一致を正直に報告します。キャッシュされたローカル Whisper のみ。自動ダウンロードはありません。レガシーハッシュのみの呼び出しはシミュレーションです。docs/SOUND_ASR_REQUESTS.md を参照してください。
   • 実際のモノラル/ステレオ PCM16 ラウドネス QA の場合、SoundLoudnessRequest とプロジェクトルートを指定し、within_tolerance を検査します。成功した測定でも非準拠になる可能性があります。FFmpeg が必要であり、入力なしのフィクスチャはデモとしてラベル付けされます。docs/SOUND_LOUDNESS_REQUESTS.md を参照してください。
   • 保持されたモノラル/ステレオマスタリングの場合、SoundMasterRequest と明示的なルートを sound-master-render に指定します。docs/SOUND_MASTER_REQUESTS.md を参照してください。確認された ZIP、実際の正規化モード、測定された最終ポリシー準拠を検査し、リリース前に聴取します。入力チャンネルは保持されます。既存の出力は決して置き換えられません。
   • 実際のローカル EN/ES の場合...

...（翻訳のため省略）