shortcut-clips は何をしますか？
ローカルパイプラインが機械的な作業（文字起こし、候補ウィンドウの検出、フレーム再構成、キャプション、レンダリング）を行います。あなたの役割は判断ステップです。候補となる瞬間をテキストとして読み、最適なものを選び、clips.jsonを作成します。動画フレームを見たり処理したりする必要は一切ありません。
0. 入力
- 動画: ローカルファイルのパス。ユーザーが代わりにURLを提供した場合は、shortcut-clipsはユーザー自身が提供するファイル（ユーザーが所有しているか、権利を持つコンテンツ）にのみ対応していることを説明し、ファイルを提供するよう依頼してください。ダウンロードは行わないでください。
- クリップ数: ユーザーが指定した数を使用します。指定がない場合は3です。
- オプション（ユーザーが要求した場合のみ）:
--language hi|kn|en|…、--min-len/--max-len（デフォルト20～60秒）、スタイルbold-pop（デフォルト）、minimal、karaoke-highlight。
1. 準備（文字起こし＋候補抽出）
shortcut-clips prepare "<動画ファイル>"
- コマンドは出力フォルダを出力し、その後チャンクファイルごとに1行ずつ出力します。両方をメモしてください。
- 初回実行時は音声モデルをダウンロードします。1時間の動画の場合、CPUで約15～25分、GPUで5～10分かかります。約10分より長い動画の場合は、コマンドをバックグラウンドで実行し、終了するのを待ってください。ユーザーに処理中であることを伝えてください。再実行は安全です。完了したステージはキャッシュされます。
- 失敗した場合は、ユーザーにエラーの修正アドバイスを表示してください。
shortcut-clips doctorでインストール状態を確認できます。
2. 瞬間を選ぶ
<出力フォルダ>/work/candidates.txtを読み込み、次にそれがリストするすべてのチャンクファイルを順番に読み込んでください。各チャンクには文（s0012 [68.3] text）と候補（c004 s0012-s0021 68.2-108.6 (40s)）が含まれており、各候補は文の範囲です。transcript.jsonやcandidates.jsonは読まないでください。チャンクには必要な情報がすべて含まれており、トークン数もはるかに少なくなります。- reference/rubric.mdを参照して各候補をスコアリングします。進めながら、要求された数の約3倍の候補をショートリストに残します。候補ID、5つの基準スコア、1行のメモを記録し、残りは破棄します。
- 勝者候補を改善します。クリップのエッジを他の文の境界に移動できます。たとえば、最も強いフックがある文から開始したり、見せ場の直後で終了したりします。
start= 選択した最初の文の時刻。end= 保持する最後の文の次の文の時刻。または、最後の文を保持する場合は候補の終了時刻。- 長さの範囲内に収めてください。バリデーターはエッジを単語単位にスナップします。
- 最終セットを選択します。全体的なスコアが最も高く、2つのクリップが数秒以上重複せず、可能な限り異なるトピックを選びます。
3. clips.jsonを書く
reference/clips-format.mdに従って<出力フォルダ>/clips.jsonを作成します。hook_text、title、captionは、ユーザーから特に指定がない限り、文字起こしの言語と文字体系で記述してください。クリップは最良のものから順に並べてください。次に、以下を実行します。
shortcut-clips validate "<出力フォルダ>/clips.json" --write
すべてのerrorを修正し、✓が表示されるまで再実行してください。簡単に修正できるwarningは修正してください。info行は自動調整（エッジのスナップ）を報告するもので、アクションは不要です。
4. レンダリング
shortcut-clips render "<出力フォルダ>/clips.json"
その後、ユーザーに報告します。各クリップについて、番号、タイトル、長さ、スコア、動画パス、およびギャラリー<出力フォルダ>/index.htmlを伝えます。トップクリップがなぜ機能するかを一文追加してください。変更を依頼できることも伝えてください。
編集と再実行
- 「クリップ2を短くして」「新しいタイトル」「カラオケスタイルを使って」など:
clips.jsonを編集し（クリップごとにstyle/layoutでdefaultsを上書き）、--write付きで検証し、再度レンダリングします。変更されていないクリップはキャッシュから再利用されます。 - 「別の瞬間を見つけて」: ステップ2に戻り、同じチャンクを使用します。prepareを再実行しないでください。
- 検出された言語が間違っている場合:
--language <コード>を指定してprepareを再実行します。文字起こしとそれ以降のステージのみがやり直されます。 No candidate windows（候補ウィンドウなし）: 動画が短いか、音声がほとんどありません。より小さな--min-len（例：10）を指定してprepareを再実行してください。