CutCraft は何をしますか？
生の映像素材と会話から、明確な最終ビデオを1つ作成します。すべてのプロジェクトは名前の付いた CutCraft ワークスペース内に保持し、編集前に視覚的な字幕の選択肢を表示し、クリエイティブな質問は一度だけ行い、書き起こしの修正は即座に元に戻せるようにします。
譲れない契約
- 最初に準備ゲートを実行すること。 初回使用時および環境変更後は、
python3 helpers/check_environment.pyを実行します。必須または要求された条件付き依存関係が欠けている場合は、編集を一時停止し、ユーザーにスクリプトの公式URLと正確なセットアップ手順を示し、不足している承認または認証情報のみを求めます。キー管理とプラットフォームのガイダンスについては references/onboarding.md を参照してください。 - このパッケージまたはプロジェクトにシークレットを保存しないこと。 ElevenLabsキーは
~/.config/cutcraft/.envにモード600で保存するか、ローカルのWhisperを使用してキーや書き起こしのアップロードが不要にします。キーをコマンド引数、ログ、書き起こし、スクリーンショット、リポジトリ、プラグインキャッシュ、プロジェクトフォルダに決して配置しないでください。 - 何かを生成する前にワークスペースを作成すること。 ユーザーの説明と検査した映像から短いプロジェクト名を推測します。2つの実質的に異なる名前が考えられる場合のみ確認します。
helpers/project_workspace.py --name "<name>"を実行し、返されたパスを使用します。 - 最初に検査し、一度だけ質問し、承認後に編集すること。 ソースのインベントリと書き起こしを作成し、代表的なビジュアルを検査し、実際の字幕プレビュー画像を作成した後、残りのすべてのクリエイティブな質問を1つの統合チェックポイントで行います。ユーザーが推奨デフォルトを選択または承認する前に、カットを開始しないでください。
- 選択肢を視覚的に表示すること。 3つの素材に適した字幕プレビュー画像（推奨、クリーン/ナラティブ、大胆/ソーシャル。ただし映像が異なる選択肢を求める場合は除く）を生成します。各画像の下にフォント、サイズ、配置、背景、言語、キューリズムを記載します。ユーザーはオプション番号または
往下 4%や字大 15%などの調整で回答できます。 - 最終成果物を明確にすること。 納品物のみを
成品/に配置します。プライマリビデオは<project>_final.mp4と命名する必要があります。プレビュー、クリップ、書き起こし、EDL、ダウンロード、生成アセット、レポートは過程/に配置します。 - 字幕付きの納品物ごとに編集可能なテキストをエクスポートすること。 最終ビデオの隣に
<project>_逐字稿.mdと<project>.srtを納品します。安定したキューIDとタイムスタンプを使用することで、ユーザーが例えば第 18 句改成……と言えるようにします。 - 書き起こしの修正を即座に適用すること。 要求されたキューを解決し、
helpers/apply_transcript_corrections.pyを過程/master.srtに対して実行し、検証を再実行し、修正されたSRTで最終ビデオを再レンダリングし、書き起こしを再生成し、納品物を置き換えます。ユーザーが同期の問題を報告しない限り、タイミングは保持します。変更されていないソースメディアの再書き起こしは行いません。 - レビュー用のフロントエンドは不要。 サーバーを起動したり、ブラウザUIファイルを作成したりしないでください。すべてのレビューは、納品されたビデオ/画像ファイルと会話による修正を通じて行われます。
- 作業を再開可能にすること。 すべてのチェックポイントで
cutcraft.project.jsonを更新します。ソースのシグネチャ、承認状態、リビジョン、最終パス、アセットの来歴を保持します。検査にはプロキシのみを使用し、常にオリジナルからレンダリングします。 - 納品前に検証すること。 決定論的なプリフライトと
quality_report.pyを実行し、レンダリング出力をカット境界と代表的な字幕瞬間で検査し、最終ミックスを聞き、出力の長さ/ストリームを確認します。カットで吃音や誤った開始が除去された場合は、レンダリングされたセクションを再書き起こしして除去されたことを証明します。
プロジェクトレイアウト
デフォルトルート: ~/Documents/Codex/CutCraft/（Finderで表示可能；インストール可能なスキル自体は ~/.codex 以下に保持）。
CutCraft/
└── <project>/
├── cutcraft.project.json
├── 成品/
│ ├── <project>_final.mp4
│ ├── <project>_逐字稿.md
│ └── <project>.srt
└── 過程/
├── project.md
├── creative_brief.json
├── inventory.json
├── takes_packed.md
├── edl.json
├── master.srt
├── transcript_corrections.json
├── asset_registry.json
├── transcripts/
├── clips/ and clips_*/
├── assets/
├── animations/
├── proxies/
├── downloads/
└── verify/
ユーザーが要求しない限り、ユーザーのソース映像をプロジェクトに複製しないでください。絶対ソースパスを edl.json に記録し、オリジナルはそのままにしておきます。
ひとつの統合チェックポイント
推奨を行うのに十分な素材を検査し、字幕比較画像をレンダリングし、次に該当するすべての項目をまとめて質問します。
- 目標、対象視聴者、プラットフォーム、アスペクト比、解像度、目標長さ、納期に敏感なフォーマット。
- ストーリー/順序、必須のセリフ、必ずカットする素材、ASRが正確にスペルすべき名前/用語。
- ペース、クロップ/リフレーム、カラームード、トランジション、エフェクト、オーバーレイ、Bロール、検閲/プライバシーの必要性。
- 字幕：焼き込み/サイドカー/両方、言語またはバイリンガルモード、逐語/クリーン、フォント、サイズ、位置、背景、キューリズム、画面上UIセーフゾーン。
- オーディオ：クリーンアップ、ラウドネス、提供された音楽/SFX/ナレーション、または希望するムードと強度。
- アセットソース：ユーザー提供ファイル、生成アセット、または特定の無料ライブラリ。無料素材が要求された場合、references/free-assets.md から適切な選択肢を提供し、ユーザーに選択を促し、
asset_registry.pyでアイテム、作成者、URL、ライセンス、帰属、チェックサムを登録します。 - 書き起こしのプライバシー：プライバシーが重要な場合はローカルWhisperを推奨し、それ以外の場合は管理されたダイアライゼーションのためにElevenLabsを提供します。メディアをクラウドプロバイダーに送信する前に、アップロード動作を説明します。
- 編集の自律性と明示的に禁止されていること。
このチェックポイントにプレビュー画像を添付します。すべての選択肢に推奨デフォルトを提供し、全部用建議値 を有効な回答として含めます。回答を 過程/creative_brief.json に永続化し、編集途中で決定した質問を再開しないでください。
ワークフロー
- 準備チェックを実行し、不足している要件のみを解決します。
- ファイル名とユーザーの説明を検査し、プロジェクト名を推測してワークスペースを作成します。
inventory.py --work-dir <過程> <sources_dir>を実行します。長時間または4Kソースの場合は、検査用にキャッシュされたプロキシを作成します。analyze_media.pyを実行して、ショットチェンジ、無音、黒フレーム、フリーズフレームの区間を特定します。- 承認されたクラウド/ローカルプロバイダーを使用して
<過程>/transcripts/に書き起こし、その後パックします。パックされた書き起こしを読み、初期/中間/後期のフレームと曖昧な編集ポイントをサンプリングし、ASRスペルのリスクに注意します。 - 代表的なフレームから3つの字幕スタイルプレビューを生成します。統合チェックポイントを質問し、承認されたブリーフを保存します。
edl.jsonを構築し、承認されたアセットをソースまたは生成し、通常の味覚に関する質問を小出しにせずに編集します。- キャプションを構築します。中国語の場合は
build_cn_subtitles.pyを使用し、その他の言語の場合はrender.py --build-subtitlesを使用します。references/subtitles.md に従います。 validate_project.pyを実行し、評価可能なプレビューを過程/verify/にレンダリングし、自己レビューします。修正/再レンダリングのループは3回までに制限し、その後は頑固な問題を報告します。- オリジナルソースから
<成品>/<project>_final.mp4をレンダリングし、最終SRTを<成品>/<project>.srtにコピーし、export_transcript.pyで<成品>/<project>_逐字稿.mdを生成します。 quality_report.pyを実行し、すべてのエラーを解決し、警告を視覚的および聴覚的にレビューし、project_state.pyでマニフェストが納品されたことをマークします。- 3つの明示的なパス、QCレポート、簡潔な編集サマリー、アセットの来歴を納品します。ユーザーに中間ファイルの中から
finalを探させないでください。
プロダクションの正確さ
- 字幕は最後に、すべてのオーバーレイとクロップの後に適用します。
- カット候補は単語境界と無音から導出し、単語の途中でカットしないでください。ペースに合わせて30～200ミリ秒のパディングを使用します。
- セグメント境界に短いオーディオフェードを適用して、クリックノイズを防止します。
- クリップを結合する前に、キャンバス、フレームレート、ピクセルフォーマット、色空間、サンプルレート、チャンネルレイアウトを正規化します。
- 書き起こしとプロキシをソースパス、サイズ、変更時刻でキャッシュし、そのシグネチャが変更された場合にのみ再実行します。
- 字幕タイムスタンプはソースタイムラインではなく、出力タイムラインで計算します。
- シングルラインが承認された場合は、ピクセルセーフなシングルラインキューを保証し、実際のフォントとキャンバスに対して検証します。
- ユーザー提供、生成、パブリックドメイン、またはライセンス互換性のあるアセットのみを使用します。タイトル、作成者、ソースURL、ライセンス、ダウンロード日、必要な帰属を記録します。
- まずダイアログをミックスします。音楽を発話の下にダッキングして聴きます；ラウドネス正規化では貧弱なミックスを救えません。
- メインエージェントがクリエイティブブリーフ、EDL、キャプションタイミング、最終タイムライン、ミックス、QCの所有者であり続けます。並列化は、不変の入力に対して一意のパスを書き込む処理のみ許可します。
プロジェクトがマルチテイク選択、トランジション、グレーディング、アニメーション、スピードランプ、または音楽主導の編集を必要とする場合は、references/editorial-craft.md を参照してください。EDLを作成または拡張する前に、references/edl.md を参照してください。
ヘルパー
check_environment.py— 必須/条件付き依存関係と認証情報の準備状態を公式セットアップURLとともに確認。project_workspace.py— 名前付きの成品/+過程/プロジェクトを作成または再利用。project_state.py— 再開可能なチェックポイント、承認、リビジョン、出力パスをアトミックに記録。inventory.py— ソースフォーマットと正規化リスクを調査。analyze_media.py— シーンチェンジ、無音、黒フレーム、フリーズフレームを検出。create_proxy.py— 不変のオリジナルにマッピングされたキャッシュ済み軽量検査プロキシ。transcribe.py,transcribe_batch.py— キャッシュされた単語レベルのElevenLabsまたはローカルWhisper書き起こし。pack_transcripts.py— コンパクトなフレーズレベルの編集ビュー。timeline_view.py— フィルムストリップ、波形、単語、カットポイントの検査。subtitle_style_preview.py— 実際のフレーム上での正確なlibassスタイル/配置プレビュー。build_cn_subtitles.py— 中国語対応のピクセル幅キュー構築。render.py— 正規化、カット、結合、オーバーレイ、ミックス、そして最後に字幕。validate_project.py— フェイルファストなEDL、アセット、タイミング、キャプションチェック。asset_registry.py— フェイルクローズドなアセットライセンス、帰属、チェックサムレジストリ。quality_report.py— 最終ストリーム、長さ、黒/フリーズ/無音、QCエビデンスレポート。build_cut_report.py— カテゴリ別カットサマリー。apply_transcript_corrections.py— 監査ログとバックアップ付きのフェイルクローズドなキュー/テキスト修正。export_transcript.py— 読みやすく、キューでアドレス指定可能な書き起こしを納品用に出力。cleanup_session.py— ユーザーが明示的にプロセスファイルの削除を要求した場合のみオプションのクリーンアップ；完成を削除と解釈しないこと。
すべてのヘルパーと参照は、この SKILL.md を含むディレクトリからの相対パスで解決します。
リビジョン動作
ユーザーが修正した後の納品済み書き起こしを、文言のソースとしての真実の情報源として扱います。文言のみの修正の場合は、キュー時間と編集決定を保持し、SRTにパッチを当て、検証し、再レンダリングします。同期の報告の場合は、影響を受けるレンダリングウィンドウを検査し、そのキューの境界のみを調整します。編集上の変更の場合は、EDLとカットレポートを更新し、影響を受けるレンダリング/QCパス全体を実行します。
各セッションを 過程/project.md に、戦略、承認された決定、アセットの来歴、リビジョン、QCエビデンス、未解決の問題とともに追記します。デフォルトで 過程/ を保持し、将来のリビジョンを安価で追跡可能にします。