chengfeng-subtitle

字幕

これは工程の一部ではなく、独立した作業です。 ユーザーに呼ばれたときに実行します。編集直後でも、作成後に二文削除したあとでも、再度実行できます。

前提はひとつだけです。台帳がすでに存在することです。編集の後に並んでいるからではなく、台帳がなければ、どの文が残っているのか、完成動画の何秒目にそれぞれ配置されるのかがわからないためです。

需要   edit-list.json（账本）、transcript.json（逐词稿）
产出   subtitles.json

作業が終わったら停止し、ユーザーに次の手順を指示しません。

最初に業務 Skill の段階契約を読み、実行します。判定基準は字幕校正ルール、固有名詞の表記はAI 用語辞書を参照してください。

それぞれ何を基準にするか

これがこの工程の土台であり、ほかのすべてはここから導かれます。

剪口播   说了算「留哪些话、在什么时候」    ← 时间的唯一真相
字幕     说了算「屏幕上显示什么字」        ← 显示的唯一真相

各字幕画面には、単語 ID のリストと表示テキストを保存し、秒数は保存しません。時間は毎回台帳から計算します。こうすれば、二つの台帳で時間が食い違うことはありません。また、無効になった場合も画面単位で正確に特定でき、「第 7 画面と第 12 画面の単語が削除されました」と示せます。「字幕が古くなっている可能性があります」のような、誰も対処できない表示にはなりません。

字幕が独自のテキストを保存するのは意図的です。 文字起こしが答えるのは「何と言ったか」、字幕が答えるのは「何を見せるか」です。句読点や削除した口癖、固有名詞の正式表記などが異なるのは当然です。一つの文字列で両方を兼ねさせると、字幕に読点を追加することすらできません。

0. 準備完了の確認

まず更新の確認の「準備完了の確認」を実行します。skills が最新か、Runtime が対応しているかを確認します。プラグインルートもそこで特定してください（この記事のコマンドにある <プラグイン根> には、その文字どおりのパスを指定します）。結果が「準備完了」の場合のみ続行します。「新しいセッションが必要」または「停止」の場合は、同項目の指示に従ってください（「独自の代替インターフェースを作成しない」という禁止事項も含みます）。業務 Skill に環境関連のロジックはありません。

準備完了の結果が runtime.kind=desktop-managed の場合は、デスクトップ App にインストール済みの安定版 CLI と、同じ launchd/windows-task サービスをそのまま使用します。Electron のパスを解析したり、依存関係を別途インストールしたり、二つ目の 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 方式に変更したことで、この問題は解消しています。字幕作成には使用しないでください。）

異なる二つのツールを、どちらも使用します。

# 词典：这个说话人的固定写法，不需要证据
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」です。

辞書は一つだけで、プラグインレベルの references/ai-term-dictionary.md にあります。辞書が修正するのは文字起こしであり、「口播を編集」と字幕は同じ文字起こしを使用します。この skill の下に別の辞書を作成しないでください。

修正したら、その一覧を確認してください。 辞書は文脈を考慮しないため、誤修正することもあります。たとえば、話者が実際に発話した「Skills」（Claude Skills という複数形の固有名詞）が「Skill」に normalize されることがあります。誤りを見つけたら辞書を修正してください。コマンド側に場当たり的な修正を追加してはいけません。

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 つのルールを、順番に適用します。

① 这里删掉过话    删掉的两边在时间轴上挨着，意思上毫无关系。
                 删掉的是「静音」不算 —— 把句子中间的停顿剪掉，不能把句子劈开。
② 任何标点        火山给的，句号和逗号都算 —— **和剪口播分段是同一个粒度**，
                 两边断在同一处。标点比任何时间证据都强：说话人可以两句连着
                 说不喘气，也可以在一句中间停顿。
③ 段落边界 + 停顿  **只在这个词没有标点时才用**。它是「没标点时靠段落猜句子结束了」，
                 有标点就该由②和逗号那条管 —— 它们会考虑屏够不够长，③ 不会。
                 （在带标点的边界上也触发③，真实项目从 40 屏变 43 屏，切出更多碎屏）
④ 观众听到长停顿   句子内部要断，得有更长的静音才够格。

「口播を編集」と字幕では、同じ句読点を使い、区切る単位も同じです：読点ひとつにつき、クリップひとつ／字幕画面ひとつです。

細かすぎる断片（1～2 文字）は前の画面にまとめますが、句点をまたいでまとめてはいけません。「你看」は新しい文の始まりであり、前の文の終わりではありません。前にまとめると「…调用Grok CLI你看」となり、二つの文がひとつにつながってしまいます。

話者の話す速度が速い短い文はそのまま残します（実際のプロジェクトでは「每天早上」「执行任务」がそれぞれ 0.6 秒でした）。実際にそのように話しているので、警告は出しません。 読点ひとつにつき字幕画面ひとつにすれば、このような画面は必然的に発生します。これに警告を出すのは、正常な発話に警告を出すのと同じです。警告が多すぎると、誰も確認しなくなります。

残った画面が一つ分より長い場合は、均等に分割して、一画面一行にします。1～2 文字の断片ができた場合は、②の境界が実際には句点ではないということなので、その断片を前の画面にまとめます。

コマンドの結果には 4 つの項目が表示されます。すべて確認してください。

stale              被剪辑改动的屏 —— 精确到第几屏、丢了哪几个字
tooFast            字太多、时间不够读
transcriptMoved    转录已经不是当初那一份了

すでに字幕がある場合 —— ここで停止して確認します

--replace を付けないと、処理は拒否されます。この skill でユーザーの同意が必要なのは、ここだけです。--replace を指定すると、人が時間をかけて作成した画面分割と文言が消去され、製品側では復元できないためです。

用户想改几个字     不要 build。让他在 Studio 里直接改，或者告诉你改哪几屏。
用户要推倒重来     确认过了再加 --replace。

4. 確認：Studio で画面ごとに見る

node "<插件根>/scripts/videocut-cli.cjs" open "<项目目录>" --json

開いたら、左側の**「字幕」タブ**に切り替えます。一行が一画面です。左側に番号と時間、右側に文字が表示され、クリックして直接編集できます。

• Enter ＝ カーソル位置で新しい画面に分割
• 行頭で Backspace ＝ 前の画面にまとめる
• 右側の「パラメーター → 字幕」から 4 つのプリセットのいずれかを選択します。動画全体で同じスタイルが適用されます
• 字幕は画面上に直接表示され、位置とフォントサイズは画面に比例します。プレビューと完成動画には同じ数値が使われます

確認時は、少なくとも固有名詞が正しいか、文字が抜けていないか、文の区切りが読みやすいか、一画面を読み終えるのに十分な表示時間があるかをユーザーに確認してもらいます。

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 が「must not change any word id, time or gap flag」と報告する：文字修正の提案に、時間を変更する内容が混入しています。文字の修正では、文字だけを変更してください。
• runtime_unhealthy：再インストールを繰り返さないでください。
• 失敗した場合も、「文字起こしが完了しました」を「字幕ができました」と言い換えてはいけません。ASR の出力は素材であり、成果物ではありません。