chengfeng-videocut-skills（字幕）

字幕

これは1つの仕事であり、ワークフローの一部ではありません。 ユーザーが呼んだときにいつでも実行します——編集直後でも、2ワード削除した後でももう一度実行できます。

前提条件は1つだけです：会計帳簿が存在すること。編集の後に行うからではありません。会計帳簿がなければ、どのセンテンスが残っていて、それぞれが最終動画の何秒目に位置するのかがわからないからです。

必要なもの  edit-list.json（会計帳簿）、transcript.json（逐語原稿）
生成するもの subtitles.json

完了したらそこで停止し、ユーザーに次のステップを指示しません。

最初に「業務スキルのフェーズ契約」を読み込んで実行し、判定基準は「字幕校正ルール」、固有名詞の表記は「AI用語辞書」を参照します。

何が何を決定するか

これがこのセクションの基盤であり、その他すべてはここから導き出されます。

口述編集  決定する「どのセリフを残すか、どのタイミングか」    ← 時間に関する唯一の真実
字幕      決定する「画面上に何の文字を表示するか」            ← 表示に関する唯一の真実

1画面の字幕は単語IDリスト + 表示テキストを保存し、秒数は保存しません。時間は毎回会計帳簿から計算します。これにより、2つの帳簿に食い違いが生じることはなく、無効になった場合も「画面7と画面12の単語が削除されました」と正確に報告できます。「字幕が期限切れかもしれません」という曖昧な表現にはなりません。

字幕が自身の文字を保持するのは意図的です。 文字起こしは「彼が何を言ったか」を答え、字幕は「人に何を見せるか」を答えます——句読点、取り除かれた口癖、固有名詞の正式表記など、これらはそもそも異なっているべきです。1つのテキストで2つの役割を強制すれば、字幕にカンマを追加することは永遠にできなくなります。

0. 準備

まず「アップデートチェック」の「準備チェック」を実行します——スキルが最新か、Runtimeが互換かどうか。プラグインのルートディレクトリもそこで特定されます（このドキュメント内の <プラグインルート> はすべてその実際のパスに置き換えてください）。「準備完了」の場合のみ続行します。「新たなセッションが必要」または「停止」の場合は、その指示に従ってください（「自作の代替UIの禁止」を含む）。業務スキルは環境ロジックを持ちません。

準備結果が 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箇所の「フォーク」の中で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つのルールを順に適用します：

① ここでセリフが削除された    削除された両側がタイムライン上で隣接しているが、意味的に関連性がない。
                       「無音」の削除は含まない——文の途中の一時停止を削除しても、文を分割できない。
② 任意の句読点              火山（ASR）が提供するもの。句点と読点の両方を扱う——**口述編集の区切りと同じ粒度**で、
                       両方とも同じ場所で区切られる。句読点は時間の証拠よりも強い：話者は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つ選択、全編に同じスタイルを適用
• 画面上で字幕が直接表示され、位置とフォントサイズは画面に比例します——プレビューと最終出力は同じ数値を使用

確認時には最低限以下の点をユーザーに確認させてください：固有名詞が正しいか、文字落ちがないか、区切りが自然に読めるか、各画面の表示時間が十分か。

5. subtitles.json までで完了

このセクションは完了です。 物理的なカット、ストーリーボード、アニメーション、レンダリングは行いません。また、ユーザーに次のステップを促しません。

レポートは分けて書く必要があります：Product 構造化 readback は API/readback PASS とします。実際の同一プロジェクトのブラウザフレームレビューは visual frame PASS とします。実際に誰も字幕と映像の同期を確認していない場合は、常に human listening UNVERIFIED とし、DOM、スクリーンショット、ファイルスキャンで代替してはいけません。

境界：映像に焼き付けることはこのセクションの範囲外

出力方法として「映像に焼き付ける」ことが決まっていますが、映像の描画は書き出しの段階で行われます。字幕の出力は subtitles.json です——その中の寸法はすべて画面のパーセンテージであり、書き出し時に出力解像度に基づいてピクセルに換算すればよいため、両方で同じ数値を使用します。

現在のエクスポートされたMP4には字幕は含まれていません。そのステップはまだ実装されていません。レポートにはこの結果を明確に記載し、「字幕が完成しました」とだけ言ってはいけません——ユーザーは最終動画に字幕が含まれていると思ってしまいます。

リカバリと失敗

• subtitles_exist：既に字幕が存在します。まず確認し、直接 --replace しないでください。
• revision_conflict：別の場所でも書き込み中です。再読み込みし、自動的に上書きしないでください。
• 辞書が「N行目を読み取れません」と報告：それはフォーマットが壊れたテーブル行です。ルールはテーブル行（| 正しい表記 | よくある誤認識 |）のみを認識し、散文やリストは無視されます。
• transcript correct が「word id、time、またはgapフラグを変更してはいけません」と報告：修正提案に時間に関する変更が混ざっています。修正は文字のみに限定してください。
• runtime_unhealthy：ループして再インストールしないでください。
• どのような失敗でも、「文字起こしが完了した」ことを「字幕が完成した」と言ってはいけません。ASRの出力は原材料であり、成果物ではありません。