EdgeSpeak カラオケ
EdgeSpeak の 1 回の文字起こしリクエストからカラオケ字幕を作成します。同梱の依存関係不要の Node.js スクリプトを使用して、決定論的な ASS 生成、リアルフレームスタイルプレビュー、FFmpeg レンダリングを実行します。
ユーザーに見た目を選んでもらう
ソースパス、出力場所、ユーザーが ASS、ハード字幕、またはその両方を希望するかを収集します。スタイルは、ユーザーが見て同意または不同意を表明できる唯一の決定事項であるため、デフォルトでユーザーの選択を優先します。
- 明示的: 名前付きプリセットまたはオーバーライドを尊重します。利用可能なプリセットは
classic、minimal、boxed、high-contrastです。 - 自動: ユーザーが実際に決定を委ねた場合のみ —「あなたが選んで」「どれでもいい」「手早くやって」「デフォルトで」。以下の表から選択し、ブロックせずに続行します。
- プレビューしてから質問 — ユーザーがスタイルの好みを述べなかった場合のデフォルト。実際のソースフレームですべてのプリセットをレンダリングし、ランタイムの画像表示機能で PNG を表示し、1 つの簡潔な質問をします。ターミナルではパスと説明をリスト表示できますが、ANSI テキストは忠実な視覚的プレビューではありません。
沈黙は委任ではありません。スタイルについて言及しなかったユーザーは、通常、スキップすることを決定したのではなく、オプションを見たことがないだけです。質問することは短いやり取りで済みますが、間違った推測は動画全体の再レンダリングを招き、ハード字幕の場合は高コストになります。
バイリンガル出力の場合、どの言語を上に配置するかも同様の可視的な選択です — 2 回質問するのではなく、その 1 つの質問に組み込みます。
プレビューを表示せずにレンダリングしないでください。 --preview-media はすべての実行で 4 つのプリセットすべてをレンダリングするため、そのコマンドが完了した瞬間にディスク上に完全な比較が存在します。1 つの PNG を開き、黙って選択し、勝者のみを報告することは、ユーザーが見る権利があったトレードオフを隠すことになります。
自動モード — およびプレビューと一緒に提供する推奨事項のシード用 — では、代表的なソースフレームを検査し、以下のデフォルトを使用します。
| 映像の種類 | プリセット |
|---|---|
| 一般的な風景または混合コンテンツ | classic |
| クリーンでほとんど暗い背景 | minimal |
| 込み入った明るい背景、スライド、画面録画 | boxed |
| 縦型/モバイルまたは一貫して難しい背景 | high-contrast |
ソース全体で明るさが変動する場合 — 同じ動画内に暗いシーンと明るいシーンがある場合 — 単一のフレームでは選択を確定できません。2 つの異なるタイムスタンプでプレビューをレンダリングし、両方を比較します。明るいフレームで有効なプリセットが暗いフレームでは見えなくなる可能性があるためです。
現在のリクエストの指示が優先されます。存在する場合は、.edgespeak-skills/edgespeak-karaoke/EXTEND.md からオプションの設定を読み取り、次に ~/.edgespeak-skills/edgespeak-karaoke/EXTEND.md を読み取ります。プロジェクト設定がユーザー設定より優先されます。便利な設定には、プリセット、フォント、フォントサイズ、ASS カラー、マージン、出力形式、品質などがあります。
文字起こしとアライメントを一度に行う
-
ソースが存在することを確認し、
ffprobeでその長さ、寸法、コンテナを検査します。 -
edgespeak_transcribe_fileを一度呼び出します。{ "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 テキストを実質的に編集した場合にのみ使用します。アライメントは最終的な単語シーケンスを使用する必要があります。編集後に古いタイムスタンプを保持しないでください。
必要条件
- 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 では、curl -fsSL https://edgespeak.com/install.sh | shを使用します(自己完結型、デスクトップアプリは不要。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 /パス/トランスクリプト.json \
-o /出力/ソース.karaoke.ass \
--style classic \
--title "ソースタイトル"
選択肢を提示するには、実際のソースからアクティブなキューにすべてのプリセットをレンダリングします。これは特別なケースではなくデフォルトのパスであり、生成されるすべての PNG は表示されることを意図しています。
node <スキルディレクトリ>/scripts/karaoke-ass.mjs /パス/トランスクリプト.json \
-o /出力/ソース.karaoke.ass \
--style classic \
--preview-media /パス/ソース動画 \
--preview-dir /出力/ソース.karaoke-プレビュー
別のフレームの方が代表的な場合は --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 /パス/トランスクリプト.zh.json \
-o /出力/ソース.karaoke.ass --style boxed
両方の行は \N で区切られた1 つの Dialogue イベントに存在するため、ASS はそれらを共有マージンから単一のブロックとして積み重ねます。2 つの別々のイベントはそれぞれそのマージンに固定され、重なります。
--layout translation-top(デフォルト)は翻訳をソースの上に配置します。source-topはそれを反転させ、ソース言語で読み進める視聴者向けです。上の行はプリセットサイズでレンダリングされ、下の行は 72% でレンダリングされるため、どちらの場合も目は主要言語に留まります。--layout source-onlyは翻訳を無視し、単一言語ファイルを生成します。- ソース行のみがスイープします。単語タイミングはソースオーディオを説明するため、翻訳には
\kタグがありません — キュー全体に対してプレーンフィルを保持します。キューの持続時間を翻訳の文字に分散することは捏造されたタイミングになります。追加しないでください。実際のターゲット言語の単語タイミングが必要な場合は、edgespeak-broadcastで合成し、そのオーディオをアライメントします。
フォントはオプションではありません — どちらの行でも
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 \
/パス/ソース動画 \
/出力/ソース.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 サーバーは意図的に独自のエンジンを起動しません(エンジンを保持する常駐サーバーは、ユーザーが次に開くアプリと競合します)。CLI にはそのような制約はありません — オンデバイスエンジンを自分で起動します。したがって、任意の EdgeSpeak MCP ツールからの could not reach gateway を、報告する障害としてではなく、「今すぐ CLI を使用する」として扱います。
edgespeak-cli コマンドが見つからない場合は、Windows x64 では EdgeSpeak デスクトップアプリをインストールするか、macOS Apple Silicon および Linux x86_64 では curl -fsSL https://edgespeak.com/install.sh | sh を使用します(自己完結型、デスクトップアプリは不要。Linux では CUDA が自動検出されます)。
edgespeak-cli transcribe /パス/ソースメディア -o /出力/トランスクリプト.json \
--start-margin 0 --end-margin 0
CLI トランスクリプト JSON には既に segments[].words[] が含まれています。同じ transcribe コマンドが生成したテキストに対して edgespeak-cli align を実行しないでください。同梱のスクリプト(--overwrite なしでは既存の出力を置き換えることを拒否します)とは異なり、edgespeak-cli -o は既存のファイルを黙って上書きします — トランスクリプトパスが既に存在する場合は、上書きする前にユーザーに確認するか、新しいパスを選択します。
検証と報告
- MCP と FFmpeg に現実的なウォールクロック予算を与えます。正常な無音処理を中断しないでください。
start_... を保持します。