EdgeSpeak カラオケ字幕
EdgeSpeak の1回の文字起こしリクエストからカラオケ字幕を作成します。同梱の依存関係不要なNode.jsスクリプトを使用して、決定論的なASS生成、リアルフレームのスタイルプレビュー、FFmpegによるレンダリングを実現します。
見た目をユーザーに選んでもらう
ソースパス、出力先、そしてユーザーがASS / ハードサブ / 両方のどれを希望するかを収集します。スタイルは、ユーザーが唯一目にして意見を言うことができる決定事項であるため、デフォルトではユーザーに決定権があるものとして扱います。
- 明示指定: 名前付きプリセットまたは上書き設定を尊重します。利用可能なプリセットは
classic、minimal、boxed、high-contrastです。 - 自動選択: ユーザーが実際に決定を委ねた場合のみ — 「あなたが選んで」「適当でいいよ」「さっさとやって」「デフォルトでいいよ」など。以下の表から選択し、ブロックせずに続行します。
- プレビューしてから確認 — ユーザーがスタイルの好みを一切述べなかった場合のデフォルトです。実際のソースフレームですべてのプリセットをレンダリングし、ランタイムの画像表示機能でPNGを表示し、簡潔な1つの質問をします。ターミナルではパスと説明を一覧表示できますが、ANSIテキストは正確なビジュアルプレビューにはなりません。
沈黙は委任ではありません。スタイルについて一度も言及しなかったユーザーは、通常、選択肢をスキップすることを決めたのではなく、単に選択肢を見たことがないのです。質問することは短いやり取り1つで済みますが、間違った推測をすると動画全体の再レンダリングが必要になり、ハードサブの場合は特にコストがかかります。
バイリンガル出力の場合、どの言語を上にするかも同様に見える選択肢です — 2回質問するのではなく、その1つの質問に組み込みます。
プレビューを表示せずにレンダリングしてはいけません。 --preview-media は毎回4つのプリセットすべてをレンダリングするため、そのコマンドが完了した時点で完全な比較結果がすでにディスク上に存在します。1つのPNGだけを開き、黙って選択し、勝者のみを報告するのは、ユーザーが見る権利のあるトレードオフを隠すことになります。
自動モード用 — およびプレビューと一緒に提供する推奨事項の種まき用 — に、代表的なソースフレームを検査し、以下のデフォルトを使用します。
| 映像の種類 | プリセット |
|---|---|
| 一般的な風景または混合コンテンツ | classic |
| クリーンでほぼ暗い背景 | minimal |
| 込み入った明るい背景、スライド、画面録画 | boxed |
| 縦長/モバイル、または一貫して難しい背景 | high-contrast |
ソース全体で明るさが変動する場合 — 同じ動画内に暗いシーンと明るいシーンがある場合 — 1つのフレームでは選択は決まりません。対照的な2つのタイムスタンプでプレビューをレンダリングし、両方を比較します。なぜなら、明るいフレームで勝ったプリセットが暗いフレームでは見えなくなる可能性があるからです。
現在のリクエストの指示が優先されます。存在する場合は、オプションの設定を .edgespeak-skills/edgespeak-karaoke/EXTEND.md から、次に ~/.edgespeak-skills/edgespeak-karaoke/EXTEND.md から読み込みます。プロジェクトの設定がユーザーの設定より優先されます。便利な設定項目には、プリセット、フォント、フォントサイズ、ASSの色、マージン、出力形式、品質があります。
文字起こしとアライメントを1回で行う
-
ソースが存在することを確認し、
ffprobeでその長さ、寸法、コンテナを検査します。 -
edgespeak_transcribe_fileを1回呼び出します。{ "path": "/絶対パス/ソースメディア", "timestamps": "word", "start_margin": 0, "end_margin": 0 }min_chars/max_charsは、ユーザーが異なるキャプション長を要求した場合のみ追加します。modelは、ユーザーが特定のモデルを指定した場合のみ追加します。地域が重要な場合は、edgespeak_list_modelsを検査し、同意なくリモートモデルを選択しないでください。 -
ワードタイムスタンプ付きの文字起こしが成功した後に、
edgespeak_alignを呼び出さないでください。このリクエストは既にEdgeSpeakのインラインローカル強制アライメントパスを実行し、segments[].words[]を返します。 -
長いMCP応答の場合は、
artifact_json_pathを使用します。インライン応答の場合は、resultオブジェクトをJSONとして保存します。コンバーターは、直接の文字起こしJSONまたはresultでラップされたものの両方を受け入れます。 -
すべてのタイミング付きセグメントで空でないワードタイミングが必要です。ワードタイミングをでっち上げたり、黙ってセグメントタイミングにフォールバックしたりしないでください。
edgespeak_align は、ユーザーが外部の最終文字起こしテキストを提供した場合、またはASRテキストを実質的に編集した場合にのみ使用します。アライメントは最終的な単語シーケンスを使用する必要があります。編集後に古いタイムスタンプを保持しないでください。
テキストを配置できないアライメントは、空の結果ではなくエラーです。 edgespeak_align は isError: true とともにJSON {"code": "alignment_failed" | "alignment_search_budget_exceeded", ..., "alignment": {...}} を返し、単語はありません(CLIは同じコードとオブジェクトを、error: alignment_failed: または error: alignment_search_budget_exceeded: で始まるstderr行に出力し、非ゼロで終了します)。alignment オブジェクトのみから判断します。
alignment.retry_recommended: true→edgespeak_alignを"search_effort": "extended"で(CLI:--search-effort extended)もう一度呼び出します。より広く検索し、低速で、追加メモリを使用します。ユーザーに伝える際にalignment.estimated_extra_bytesを引用します。- それ以外の場合、または
alignment_search_budget_exceededの場合は、同じ呼び出しを再試行しません。このメディアに文字起こしテキストが一致するか確認するか、より短いクリップをアライメントします。コードとフィールドの完全なリストについては、edgespeak-alignを参照してください。
失敗したアライメントからカラオケキューを構築してはいけません。等間隔の単語、セグメントタイミングへのフォールバック、編集前の文字起こしからのタイミングの継承は禁止です。
要件
- Node.js 18 以降(同梱のスクリプト用)。
libassでビルドされたFFmpeg、およびffprobe— 別の実行可能ファイルであり、PATH上に存在する必要があります。すべてのプレビューとすべての焼き付けはassフィルターを通過するため、libassなしのFFmpegは、選択されたプリセットに関係なくNo such filter: 'ass'で失敗します。MP4/MOV/MKV/TSへの焼き付けにはさらにlibx264が必要です。WebMにはlibvpxとlibopusが必要です。Homebrewおよび主要なディストリビューションパッケージにはこれらのすべてが含まれています。edgespeak-cli(またはEdgeSpeakアプリ)が文字起こし用に必要で、macOS Apple Silicon、Linux x86_64、Windows x64 で動作します。Windowsでは、CLIを同梱するEdgeSpeakデスクトップアプリをインストールします。macOSとLinuxでは、ユーザーに https://edgespeak.com/docs/cli#install の自己完結型インストーラーを案内します(デスクトップアプリは不要。LinuxではNVIDIA GPUを自動検出し、CUDA対応ランタイムをインストールします)。ユーザーがインストーラーを実行します。自分で実行しないでください。フロントマターのminCliVersionは、このスキルが対象とする最古のCLIバージョンです。edgespeak-cli --versionがそれより古い場合、または文書化されたフラグが--helpにない場合は、edgespeak-cli updateを実行します。
依存関係が不足して実行が失敗した場合は、再試行する代わりに、どのチェックに失敗したかを報告します。
node --version # v18以上
ffprobe -version # ffmpegと共に存在する必要あり
ffmpeg -filters | grep -w ass # ASSレンダラー (libass)
ffmpeg -encoders | grep -w libx264 # H.264出力
ASSとプレビューを生成する
選択されたプリセットを生成します。
node <スキルディレクトリ>/scripts/karaoke-ass.mjs /path/to/transcript.json \
-o /出力先/source.karaoke.ass \
--style classic \
--title "ソースタイトル"
選択肢を提示するために、実際のソースからアクティブなキューの1つですべてのプリセットをレンダリングします。これは特別なケースではなくデフォルトのパスであり、生成されるすべてのPNGは表示されることを意図しています。
node <スキルディレクトリ>/scripts/karaoke-ass.mjs /path/to/transcript.json \
-o /出力先/source.karaoke.ass \
--style classic \
--preview-media /path/to/source-video \
--preview-dir /出力先/source.karaoke-previews
別のフレームの方が代表的である場合は --preview-at <秒> を使用し、ソースが明るいシーンと暗いシーンを混在させている場合は、異なるタイムスタンプで2回実行します。--list-styles でプリセットを一覧表示します。--font、--font-size、--margin-v、--primary、--secondary、--outline、--back で微調整します。ASSの色は &HAABBGGRR を使用します。このスクリプトはEdgeSpeakのセグメント境界を保持し、アライメントされた継続時間/ギャップのみを \kf / \k タグにマッピングします。
単語間のスペースは、キュー自体の text から来ており、単語ごとのスペースから来ているわけではありません。強制アライメントは句読点をそれが続く単語に付加するため、すべての words[] エントリは text の部分文字列であり、それらの位置は前方にのみ移動します — ジェネレーターは text を1回ウォークスルーし、2つの単語の間に実際にあるものを再利用します。これにより、high-performance がハイフン付きのまま維持され(アライメントは high と performance に分割し、ハイフンはどちらにも属さない)、CJKが 本地转录 を 本 地 转 录 とレンダリングする代わりにスペースなしのまま維持されます。単語が text に見つからない場合、ジェネレーターは推測する代わりに単一スペースにフォールバックします。
バイリンガルカラオケ
文字起こしがすべてのセグメントに translation を含んでいる場合 — edgespeak-translate が書き込むもの — ジェネレーターはキューごとに2行を出力し、追加のフラグは必要ありません。
node <スキルディレクトリ>/scripts/karaoke-ass.mjs /path/to/transcript.zh.json \
-o /出力先/source.karaoke.ass --style boxed
両方の行は \N で区切られた1つのDialogueイベント内に存在するため、ASSはそれらを共有マージンから1つのブロックとして積み重ねます。2つの別々のイベントはそれぞれそのマージンにアンカーされ、重なります。
--layout translation-top(デフォルト)は翻訳をソースの上に配置します。source-topはそれを反転し、ソース言語で読み進める視聴者向けです。上の行はプリセットサイズでレンダリングされ、下の行は72% でレンダリングされるため、どちらの場合でも視線は主要言語に留まります。--layout source-onlyは翻訳を無視し、単一言語ファイルを生成します。- ソース行のみがスイープします。単語タイミングはソースオーディオを記述しているため、翻訳は
\kタグを受け取りません — キュー全体に対してプレーンフィルを保持します。キューの継続時間を翻訳の文字に分配することは、タイミングをでっち上げることになります。追加しないでください。実際のターゲット言語のワードタイミングが必要な場合は、音声合成スキル(インストールされていれば)で翻訳を音声化し、その音声をアライメントします。
フォントはオプションではありません — 両方の行で
libass はブラウザのようにグリフごとにフォントを代替しません。ラテン文字スタイルのフォントのCJKテキストは、空のボックスとしてレンダリングされます — 焼き付け全体を通して、黙って。すべてのプリセットはラテンフォントを同梱しているため、ジェネレーターはプリセットのフォントを継承する代わりにスクリプトに基づいて選択します。これはソース行にも適用され、翻訳行だけではありません。--font なしの中国語の文字起こしは、そうでなければボックスの列として焼き付けられます。
- スクリプトは行自体のテキストから検出され、
fc-match :lang=<タグ>を介して照合され、単一のASCIIファミリーエイリアスを取得します(エイリアスリストはカンマ区切りのASSスタイル行を壊します)。 --font <名前>(ソース)と--translation-font <名前>(翻訳)はそれを上書きしますが、fc-listがそのフォントが検出された言語をカバーしていないと言った場合、拒否されます。別のラテンフォントを選んでエラーを回避しようとしないでください —fc-list :lang=zh-cn familyでそのスクリプトをカバーするものを確認してください。- ラテンテキストはプリセットのフォントをそのまま維持します。フォントの交換は、プリセットがスクリプトをカバーしない場合にのみ発生します。
- fontconfigがない場合、自動選択は大きなエラーで失敗します。フォントを明示的に渡してください。実行時に
source_font_verified: false/translation_font_verified: falseが報告され、カバレッジを確認できなかった場合は、フォントは問題ないと主張するのではなく、その注意事項を報告します。 - ソースがラテン文字でない場合、実行は
source_font/source_scriptを報告します。
部分的に翻訳された文字起こしは即座に拒否されます — これは翻訳ステップが途中で停止したことを意味し、残りの部分にソースのみのキューを出力すると、不完全なファイルを完成品として渡すことになります。
ハードサブを焼き付ける
ソースに動画があり、ユーザーがハードサブを希望する場合:
node <スキルディレクトリ>/scripts/render-hardsub.mjs \
/path/to/source-video \
/出力先/source.karaoke.ass
デフォルトの --format source は、可能な場合、ソースコンテナを保持します:
- MP4/M4V/MOV -> H.264/AACで同じ拡張子。
- MKV -> H.264とコピーされた音声でMKV。
- WebM -> VP9/OpusでWebM。
- TS/M2TS -> H.264/AACで同じ拡張子。
- サポートされていない/曖昧なソース拡張子 -> MKVにフォールバックし、
container_fallback: trueとして報告。
ハードサブは常に動画の再エンコードが必要です。コンテナを保持することは、ソースの動画コーデックをコピーすることを意味しません。--format mp4|mov|mkv|webm または明示的な -o は、ユーザーが異なる配信形式を要求した場合にのみ使用します。--overwrite は許可がある場合のみ使用します。
ソースのビットレートに合わせる
固定品質での再エンコードは、ソースが元々持っていたものを無視し、その差は大きくなる可能性があります:CRF 21でリーンな1.5 MbpsのAV1ファイルを焼き付けると、4.2 MbpsのH.264コピーが生成されます — ソースビットレートの2.8倍、ファイルサイズはほぼ3倍で、目に見える利点はありません。そこで、スクリプトはソースをプローブし、そのビットレートから、出力コーデックがどれだけ非効率的かによってスケーリングされた -maxrate / -bufsize の上限を導き出します(H.264は同等の品質を得るためにAV1の約1.6倍のビットレートが必要です)。品質は依然としてCRFから来ており、上限はソースを超えないようにするだけです。
これはx264ターゲットでは自動です。VP9/WebMはそのままにしておきます。.webm プロファイルが固定品質モードで -b:v 0 を固定するためです。レポートには source_video_bitrate、video_bitrate、bitrate_cap の決定が含まれます — 結果を報告するときに最初の2つを比較します。
ユーザーが特定のビットレートや品質レベルを要求した場合にのみ上書きします:
--crf <n>は品質目標を設定します(低いほど良い、H.264のデフォルトは21)。--maxrate <レート>は導出された上限を置き換えます(例:--maxrate 4M)。--maxrate noneは上限を完全に無効にし、プレーンなCRF動作に戻します。
ビットレートはファイルサイズのためのレバーでもあります。ユーザーが出力サイズに異議を唱えた場合、変更を提案する前にソースビットレートと出力ビットレートを引用し、フラットなイラストや画面録画の映像は実写よりもはるかに圧縮が効き、字幕テキスト自体はCRF 28でも鮮明さを保つため、それが制約になることは決してないことを覚えておいてください。
CLIフォールバック
MCPで作業ができない場合は常に edgespeak-cli にフォールバックします — MCPサーバー自体が稼働していてもそのツールが失敗する場合を含みます。最も一般的なケース:デスクトップアプリが実行されていないため、すべてのEdgeSpeak MCPツールは runtime_error: could not reach gateway を返します。これは壊れたインストールではなく、再試行すべきものでもありません。長時間実行されるMCPサーバーは、意図的に独自のエンジンを起動することはありません(常駐サーバーはエンジンを保持しません)。
キャプションの言語
edgespeak_transcribe_file からのすべての Segment は、認識された言語を示す language フィールドを持っています。これを karaoke-ass.mjs の --source-lang として渡すことで、レンダラーの内部フォント選択が改善されます(デフォルトの代わりに)。--source-lang を省略すると、ジェネレーターは各キューを個別に検査します。
バイリンガル出力の場合、翻訳言語を指定する方法がスクリプトに必要です。現在のスクリプトは --translation-lang を受け取りますが、これはオプションです。このフラグが設定されていて、かつ fc-match によってフォントが確認された場合、source-lang と translation-lang の両方が自動フォント選択に使用されます。
エラーとリトライ
エラーは3つのカテゴリに分類されます:
- 回復可能 — リソースの競合、ファイルシステムの一時的な問題。最大2回、3秒のバックオフで再試行します。
- 回復不可能 — 無効な入力、サポートされていない形式、存在しないファイル。すぐにユーザーに報告します。
- 依存関係の欠落 — Node.js、FFmpeg/libass、
edgespeak-cliの最小バージョン要件が満たされていません。正確にどのチェックに失敗したかを報告します。
回復不可能なエラーに対しては、同じ入力を再試行しないでください。代わりに、問題を診断し、具体的な修正手順をユーザーに提供します。
ユーザー設定
スキルは、優先設定のために最大2つの場所をチェックします:
<cwd>/.edgespeak-skills/edgespeak-karaoke/EXTEND.md— プロジェクトレベルの設定。~/.edgespeak-skills/edgespeak-karaoke/EXTEND.md— ユーザー全体の設定。
プロジェクトの設定はユーザーの設定より優先されます。サポートされているキーは次のとおりです:preset、font、font-size、primary、secondary、outline、back、margin-v、format、quality。
設定ファイルにはYAMLフロントマターが含まれています:
---
preset: boxed
font: Noto Sans JP
font-size: 18
---
これらの設定は、コマンドラインの引数によって上書きされます。
スキルが処理するプロンプトの例
- 「この動画にカラオケスタイルの字幕をつけて」
- 「単語ごとにハイライトされるASS字幕ファイルを作成して」
- 「バイリンガル字幕(英語/日本語)で、英語を上にして」
- 「この動画に字幕を焼き付けて、スタイルはclassicで」
- 「字幕をカラオケっぽくして、ただしスタイルはあなたに任せる」
- 「同じことを、今度は中国語の文字起こしで」
スキルは常に1つのEdgeSpeak文字起こしリクエストを使用することを好みます。ユーザーが外部の文字起こしテキストを提供した場合にのみ edgespeak_align を使用します。