Communitygithub.com

Chengfeng Subtitle — カット台帳から字幕タイミングを算出、再文字起こし不要

既存の単語単位文字起こしとカット台帳から、編集済みトーキングヘッド動画に字幕を付ける。カット後のタイミングを計算し、聞き間違えた固有名詞を辞書と台本で修正、文ごとに画面分割し、Studio で1画面ずつ確認。

Chengfeng Subtitle — カット台帳から字幕タイミングを算出、再文字起こし不要 とは?

ショート動画編集レシピ Step 2(字幕):video-skill-ku-chengfeng-subtitle。字幕は単語 ID と表示テキストだけを保存し秒数は持たないため、タイミングは毎回台帳から再計算され、古くなった画面も正確に特定できる。さらに削ったら再実行し、書き出しへ渡す。

対応✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/2789927464king-jpg/video-skill-ku/tree/HEAD/chengfeng-videocut-skills/plugins/chengfeng-videocut/skills/chengfeng-subtitle

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

字幕

これは一つのタスクであり、ワークフローの一部ではありません。 ユーザーが呼び出したときに実行されます——編集が終わった直後でも、また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の出力は原料であり、成果物ではありません。

Individual skills in this repo

This repo contains 8 individual skills — each has its own dedicated page.

2789927464king-jpg/video-skill-ku

剪辑环境的唯一管理者:就绪检查(skills 是否最新 → Runtime 是否配套)、Skills 更新激活、Runtime 安装与体检。用户说检查更新、安装剪辑环境、装播放器、检查剪辑环境、剪辑环境就绪了吗、配置转录凭证时使用;业务 Skill(剪口播/字幕/画面/导出)第 0 步也引用本 Skill 的就绪检查。不用于剪辑、字幕、画面、导出本身或项目数据迁移。

2789927464king-jpg/video-skill-ku

剪辑中文口播原素材:逐词转录、词典修字出修字表、五轮扫描找口误与重复、汇总表与重复句子表、打开 Studio 让用户复核、复盘沉淀用户偏好与词典。只产出一份已复核的删词账本,不切媒体、不做字幕、不做分镜动画。用户说剪口播、处理口误、生成口播基础素材、继续剪口播,或确认卡回传 action=return_cut_review 时使用。不要用于执行物理剪切、导出剪后视频、单独安装、单独打开工作台或口播分镜成片。

2789927464king-jpg/video-skill-ku

把剪好的口播烧成一个成片文件:账本切片段、推近、字幕、HTML 画面层,一次全部烧进 mp4。用户说导出、出成片、烧字幕、渲染、导出视频、生成最终文件时使用。不要用于生成删词候选、写字幕、做画面动画。

2789927464king-jpg/video-skill-ku

整理、脱敏并上报 chengfeng-videocut 的 GitHub Bug。用户说上报 Bug、反馈剪口播问题、提交 GitHub Issue、这个问题告诉开发者,或要求继续提交已预览的 Bug 草稿时使用。不要用于功能建议、普通排错、代码提交或未获用户确认的自动上报。

2789927464king-jpg/video-skill-ku

操作 chengfeng-videocut 剪辑工作台的已有工程,通过 Runtime CLI 查工程与词句位置、添加或替换画面覆盖层、移除画面、删除明确指定的词句或片段、拆分裁剪移动已有片段、调整画布比例并回读核验。用户说插入片段、删掉这句、移除动画、换个画面、调整顺序或管理时间线时使用;先区分画面覆盖与主轨顺延插入,不负责自动判断口误、创作动画、制作字幕、导出或排查安装故障。

2789927464king-jpg/video-skill-ku

Create Ian Xiaohei-style HTML/SVG motion illustrations for Chinese articles, scripts, storyboard scenes, workflow explanations, concept metaphors, and short video visual aids. Use when the user asks for 小黑 SVG、漫画感 HTML、分层 SVG 动效、把小黑生图做成 HTML/SVG、可编辑矢量动效、口播流程动画、手绘漫画动效、正文配图动画, or wants a Xiaohei illustration style adapted into controllable HTML/SVG/GSAP output instead of raster image generation.

2789927464king-jpg/video-skill-ku

给剪好的口播配画面:在录屏上盖 HTML 层(圈重点标注 / 小黑整屏动画 / 推近),层绑字幕屏、由播放器逐帧驱动、直接在预览里看。用户说做分镜、配画面、加动画、圈重点、B-roll、做 storyboard 时使用。不要用于删词剪辑、字幕、物理剪切或成片渲染。

2789927464king-jpg/video-skill-ku

剪映 (JianYing) AI自动化剪辑的高级封装 API (JyWrapper),提供开箱即用的 Python 接口,支持录屏、素材导入、字幕生成、Web 动效合成及项目导出。全面适配 MacOS (Apple Silicon/Intel) 与 Windows,支持 v5.9+ (draft_info.json) 架构、工程自修复、智能配音字幕及录屏变焦。

関連スキル