Communitygithub.com

EdgeSpeak カラオケ字幕

EdgeSpeak の 1 回の文字起こしリクエストとインライン単語レベルの強制アライメントを使用して、単語ハイライト付きのカラオケ ASS 字幕を作成し、オプションで翻訳された 2 行目のバイリンガル字幕を生成し、ローカル動画にハードサブとして書き込みます。ユーザーがカラオケキャプション、単語ごとのハイライト、ASS ファイル、バイリンガルまたは二重言語字幕、字幕スタイルの選択やプレビュー、または最終的な参照トランスクリプトを提供せずにハードサブ動画を要求した場合に使用します。

EdgeSpeak カラオケ字幕 とは?

EdgeSpeak カラオケスキルは、開発者や AI エージェントユーザー向けに設計された、高度な字幕生成機能を提供します。このスキルの核心は、EdgeSpeak の単語レベルのタイムスタンプ機能を利用して、1 回の文字起こしリクエストから完全なカラオケスタイルの ASS(Advanced SubStation Alpha)字幕ファイルを生成することです。さらに、文字起こし結果に翻訳が含まれている場合は、元の言語と翻訳の 2 行からなるバイリンガル字幕を自動作成します。これにより、クロードコード、Cursor、Codex などの AI エージェントは、ユーザーが手動で複雑な字幕編集を行うことなく、プロフェッショナルな字幕を動画に追加できます。 このスキルは、Node.js スクリプトを使用して ASS ファイルの生成、リアルタイムフレームベースのスタイルプレビュー、FFmpeg を使ったハードサブ(字幕焼き付け)レンダリングを実行します。ユーザーは `classic`、`minimal`、`boxed`、`high-contrast` の 4 つのプリセットスタイルから選択でき、フォント、色、マージンなどの詳細設定もカスタマイズ可能です。自動モードでは、ソース映像の代表的なフレームを分析して最適なスタイルを提案し、プレビュー機能では実際の動画フレームに各スタイルを適用した PNG 画像を生成してユーザーに選択肢を視覚的に提示します。 重要な特徴として、文字間隔や単語間のスペースは、強制アライメントの結果に基づいて正確に処理されます。ハイフンでつながれた単語や、CJK(中国語・日本語・韓国語)のようなスペースのない言語でも、自然な表示が保証されます。また、バイリンガルモードでは、翻訳行と原語言語行が適切なフォントサイズでレイアウトされ、libass によるフォント自動選択機能により、ラテン文字以外のスクリプトでも文字化けを防ぎます。 MCP(Model Context Protocol)ツールが使用できない場合や、EdgeSpeak デスクトップアプリが実行されていない場合は、自動的に `edgespeak-cli` にフォールバックします。これにより、常に信頼性の高い文字起こしとアライメントが保証されます。出力ビットレートはソース動画のビットレートに基づいて自動調整され、不要なファイルサイズの増加を防ぎます。このスキルは macOS Apple Silicon、Linux x86_64、Windows x64 で動作し、Cuda 対応の GPU アクセラレーションもサポートしています。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/lattifai/EdgeSpeak-Skills/tree/HEAD/skills/edgespeak-karaoke

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

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

ドキュメント

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 カラー、マージン、出力形式、品質などがあります。

文字起こしとアライメントを一度に行う

  1. ソースが存在することを確認し、ffprobe でその長さ、寸法、コンテナを検査します。

  2. edgespeak_transcribe_file を一度呼び出します。

    {
      "path": "/絶対パス/ソースメディア",
      "timestamps": "word",
      "start_margin": 0,
      "end_margin": 0
    }
    

    ユーザーが異なるキャプション長を要求した場合にのみ min_chars / max_chars を追加します。ユーザーがモデルを指定した場合にのみ model を追加します。地域性が重要な場合は、edgespeak_list_models を検査し、同意なしにリモートモデルを選択しないでください。

  3. 単語タイムスタンプの文字起こしが成功した後は、edgespeak_align を呼び出さないでください。このリクエストは既に EdgeSpeak のインラインローカル強制アライメントパスを実行し、segments[].words[] を返します。

  4. 長い MCP 応答の場合は artifact_json_path を使用します。インライン応答の場合は、result オブジェクトを JSON として保存します。コンバーターは、直接のトランスクリプト JSON または result ラッパーの両方を受け入れます。

  5. すべてのタイミング付きセグメントに空でない単語タイミングが必要です。単語タイミングを捏造したり、無音でセグメントタイミングにフォールバックしたりしないでください。

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_... を保持します。

関連スキル