字幕
これは一つのタスクであり、ワークフローの一部ではありません。 ユーザーが呼び出したときに実行されます——編集が終わった直後でも、また2つのセリフを削除した後でも、もう一度実行できます。
前提条件はただ一つ:台帳がすでに存在すること。編集の後に順番があるからではなく、台帳がなければ、どのセリフを残すか、それぞれが完成作品の何秒目に位置するかを判断できないからです。
必要なもの edit-list.json(台帳)、transcript.json(逐語テキスト)
出力 subtitles.json
完了したら停止し、ユーザーに次のステップを指示しません。
まず 業務Skillのフェーズ契約 を読み取り実行し、判断基準は 字幕校正ルール を参照、固有名詞の表記は AI用語辞書 に従います。
誰が何を決定するか
これがこのセクションの基盤であり、他のすべてはここから導き出されます。
編集 「どのセリフを、いつ残すか」を決定 ← 時間の唯一の真実
字幕 「画面に何の文字を表示するか」を決定 ← 表示の唯一の真実
1画面の字幕は単語IDのリスト + 表示テキストを保存し、秒数は保存しません。時間は毎回台帳から計算します。 これにより、2つの台帳にずれた時間情報が生じることはなく、無効になった場合でも画面単位で正確に特定できます:「第7画面、第12画面の単語が削除されました」——「字幕は期限切れかもしれません」という曖昧な表現は不要です。
字幕が自分のテキストを保存するのは意図的です。 文字起こしは「彼が言ったこと」を答え、字幕は「人に見せるもの」を答えます——句読点、削除された間投詞、固有名詞の正式表記は、そもそも異なるべきです。1つの文字列で両方の役割を強制すると、字幕にコンマを追加することが永遠にできなくなります。
0. 準備
まず チェック&更新 の「準備確認」を実行します——skillsが最新か、Runtimeが対応しているか;プラグインルートもここで特定されます(このドキュメントのコマンド内の <プラグインルート> はすべてそのリテラルパスを代入します)。「準備完了」の場合のみ続行します;「新しいセッションが必要」または「停止」の場合は、その指示に従って処理します(「自作の代替インターフェース禁止」の禁止事項を含みます)、業務Skillは環境ロジックを内包しません。
準備結果が runtime.kind=desktop-managed の場合、デスクトップアプリにインストールされた安定版CLIと同一の launchd/windows-task サービスを直接再利用します;Electronパスを解析したり、依存関係を別途インストールしたり、2つ目のRuntimeを起動したりしないでください。
1. エントリ前提条件
node "<プラグインルート>/scripts/ensure-running.cjs" --json
node "<プラグインルート>/scripts/videocut-cli.cjs" inspect "<プロジェクトディレクトリ>" --json
| 前提条件 | 成立しない場合 |
|---|---|
edit-list.json が存在し、セグメントがある | 台帳がないことを明確に説明し、ユーザーに編集を呼び出させる。自分で編集しないこと。 |
transcript.json が存在する | プロジェクトの準備ができていないため停止。自分で作成しないこと。 |
source_cut.mp4 を前提条件とせず、文字起こしもしないこと。 字幕にはどちらも不要です——次のセクションを参照。
2. 文字の修正:辞書、次に原稿
再文字起こしは不要です。 元の逐語テキストにはすでにタイムスタンプがあり、台帳はどのセグメントが残っているかを把握しています——各単語が完成作品の何秒目に位置するかは計算で求められ、再聞き取りでは導き出されません:
単語が元の動画の何秒目か 文字起こしに含まれている
どのセグメントが残っているか 台帳に含まれている
単語が完成作品の何秒目か 両方から計算できる
ASRを再度実行すると、同じ発話を再び聞くことになり、時間とコストがかかり、精度も低下します——固有名詞を再修正する必要があります。(transcript retranscribe は以前の設計の名残であり、字幕が編集後の動画を書き起こしてタイムラインを取得することを前提としていました。字幕が単語IDに固定された後、この問題は解消されました。字幕作成に使用しないでください。)
2つの異なるツールがあり、両方を使用します。
# 辞書:この話者の固定表記、証拠不要
node "<プラグインルート>/scripts/videocut-cli.cjs" transcript dictionary "<プロジェクトディレクトリ>" --dictionary "<プラグインルート>/references/ai-term-dictionary.md" --json
# 原稿:作成者が原稿を持っている場合のみ、箇所ごとに証拠が必要
node "<プラグインルート>/scripts/videocut-cli.cjs" transcript align "<プロジェクトディレクトリ>" --script "<原稿ファイル>" --json
辞書 常にこのように書く 文脈を考慮せず、直接修正し、修正箇所を列挙する
原稿 文脈が一致する場合のみこのように書く 箇所ごとに証拠が必要、一致しない場合は「確定できず」と報告し、推測しない
なぜ辞書が必要で、原稿だけでは不十分なのか:口述は再録音される可能性があります。実際のプロジェクトでは同じセリフが4回録音され、その結果「接続フォーク」「フォークは」などの文脈が複数回出現し、alignは「確定できず」と報告せざるを得ません——ルールに従って推測しないからです。名前の書き間違いは聞き間違いよりも悪影響です。 「フォーク」の3箇所中、alignは1箇所しか修正できません。辞書にはこの問題はありません:この話者の作品では、「フォーク」は**「X」**です。
辞書は1つだけで、プラグインレベルの references/ai-term-dictionary.md にあります:これは文字起こしを修正し、編集と字幕は同じ文字起こしを使用します。このスキルの下に別の辞書を作成しないでください。
修正後はそのリストを確認すること。 辞書は文脈を考慮しないため、間違って修正する可能性があります——例えば、話者が実際に言った「Skills」(Claude Skills、複数形の固有名詞)を「Skill」に正規化するなど。間違いを見つけたら辞書を修正し、コマンド側でパッチを当てないでください。
transcript align は報告のみで、修正は行いません。その提案を適用するには、corrections を [{wordId, text}] に変換してから実行します:
node "<プラグインルート>/scripts/videocut-cli.cjs" transcript correct "<プロジェクトディレクトリ>" --file "<修正ファイル>" --json
文字起こしを修正すると、これらの単語を参照している字幕画面は同じステップで自動的に更新され、subtitles.updated が返されます。修正できないもの(その行が手動で書き換えられたもの)は needsAttention に入り、報告されてユーザーが確認し、推測はしません。
辞書にも原稿にも正しいと確認できる表記がない場合、推測は禁止です。 報告してユーザーに辞書を補完させます——辞書に追加すれば、次の動画では自動的に正しくなり、推測が成功しても次回も再推測が必要になります。
3. 画面分割
node "<プラグインルート>/scripts/videocut-cli.cjs" subtitle build "<プロジェクトディレクトリ>" --json
4つのルール、順序に従って:
① ここでセリフが削除された場合 削除された両側がタイムライン上で隣接し、意味的に関係がない。
削除された「無音」は含まない——文の途中の間を削除しても、文を分割できない。
② 任意の句読点 火山が付与したもの、句点と読点の両方を含む——**編集のセグメント分割と同じ粒度**、
両方が同じ場所で分割される。句読点は時間の証拠よりも強い:話者は2つの文を
続けて息継ぎなしで言うことも、1つの文の途中で間を置くこともできる。
③ 段落境界 + 間 **この単語に句読点がない場合のみ使用**。「句読点がない場合、段落で文の終わりを推測する」という意味で、
句読点がある場合は②と読点のルールが優先される——それらは画面の長さを考慮するが、③は考慮しない。
(句読点のある境界でも③を発動すると、実際のプロジェクトで40画面が43画面に増え、より細かい画面が生成される)
④ 視聴者が長い間を感じる場合 文の途中で分割するには、より長い無音が必要。
編集と字幕は同じ句読点を、同じ粒度で使用する:1つの読点が1セグメント/1画面。
断片(1-2文字)は結合されますが、句点をまたいで結合しない—— 「見て」は新しい文の始まりであり、前の文の末尾ではありません。前に結合すると「…Grok CLIを呼び出して見て」となり、2つの文が混ざります。
話者が速く話す短い文はそのまま残ります(実際のプロジェクトでは「毎朝」「タスクを実行」が各0.6秒)。それは本当にそのように話しているため、警告を出さない。 1つの読点が1画面になると必然的にこのような画面が発生し、警告を出すことは正常な発話に対する警告になり、警告が多すぎると誰も見なくなります。
残りの1画面より長いものは均等に分割して複数の画面にし、1画面1行。1-2文字の断片が生成された場合、②の境界が実際には句点ではなかったことを示すため、断片を前の画面に結合します。
コマンドは4つの項目を返すため、すべて確認する必要があります:
stale 編集によって変更された画面——どの画面で、どの文字が失われたかを正確に示す
tooFast 文字が多すぎて、読む時間が足りない
transcriptMoved 文字起こしがもはや元のものではない
すでに字幕が存在する場合——ここで停止して確認する
--replace を付けなければ、直接拒否されます。これはこのスキルで唯一、ユーザーの同意を必要とする箇所です、なぜなら --replace は人が時間をかけて行った画面分割や表現を上書きし、製品自体では復元できないからです。
ユーザーが数文字を修正したい場合 buildを実行しない。Studioで直接修正させるか、どの画面を修正するかを指示させる。
ユーザーが最初からやり直したい場合 確認後に `--replace` を追加する。
4. 確認:Studioで画面ごとに確認
node "<プラグインルート>/scripts/videocut-cli.cjs" open "<プロジェクトディレクトリ>" --json
開いたら左ペインの 「字幕」タブに切り替えます。1行1画面:左側に番号と時間、右側にテキストがあり、クリックして直接編集します。
- Enter = カーソル位置から新しい画面を開始
- 行頭でBackspace = 前の画面に結合
- 右ペイン「パラメータ → 字幕」の4つのプリセットから1つ選択、動画全体で1つのスタイル
- 画面上で字幕を直接確認でき、位置とフォントサイズは画面に比例——プレビューと出力は同じ数値
確認時には少なくともユーザーに以下を確認させる:固有名詞が正しいか、文字の欠落がないか、区切りが読みやすいか、1画面の表示時間が十分か。
5. subtitles.json まで
このセクションは完了です。 物理的なカット、シーン分割、アニメーション、レンダリング出力は行いません。また、ユーザーに次のステップを促しません。
レポートは分けて記述する必要があります:製品構造化リードバックは API/readback PASS;実際の同じプロジェクトのブラウザフレーム確認は visual frame PASS;誰も実際に字幕と画面が合っているか確認していない場合は常に human listening UNVERIFIED とし、DOM、スクリーンショット、ファイル検出で代用してはなりません。
境界:画面に焼き付けるのはこのセクションの範囲外
出力方式は画面に焼き付けることですが、画面は出力時に描画されます。字幕の出力は subtitles.json です——その中のサイズはすべて画面のパーセンテージであり、出力は出力解像度に応じてピクセルに変換するだけで、両方で同じ数値を使用します。
今日出力されたmp4には字幕は含まれていません、そのステップはまだ行われていません。レポートにはこの結果を明確に記載し、「字幕は完了しました」と言って終わらせないでください——ユーザーは出力に字幕が含まれていると誤解する可能性があります。
復元と失敗
subtitles_exist:すでに字幕が存在する。最初に確認し、直接--replaceしないこと。revision_conflict:別の場所でも書き込み中。再読み込みし、自動的に上書きしない。- 辞書が「N行目が読み取れません」と報告:それはフォーマットが壊れたテーブル行です。ルールはテーブル行(
| 正しい表記 | よくある誤認識 |)のみを認識し、散文やリストは無視されます。 transcript correctが「must not change any word id, time or gap flag」と報告:文字の修正提案に時間を変更するものが混ざっています。文字だけを修正します。runtime_unhealthy:再インストールをループしない。- いかなる失敗でも、「文字起こしが完了した」ことを「字幕は完了しました」と言い換えてはなりません。ASRの出力は原料であり、成果物ではありません。