Communitygithub.com

カラオケ字幕

英単語をスペル単位で白→緑に色変え&拡大するカラオケ字幕を動画に焼き付けます。中国語学習者向けにCET-6レベルの難単語・句動詞・イディオムに青字で簡体字註釈を追加することもできます。

カラオケ字幕 とは?

このスキルは、英語動画に単語単位で同期するカラオケ字幕を焼き付けるためのパイプラインです。発話中の単語が白から緑に変わるとともに一瞬拡大する視覚効果を持ち、ユーザーが指定した動画ファイルやYouTube・XなどのURLを入力として処理します。オプションで、中国語学習者(CET-6程度)向けに専門用語・難単語・句動詞・イディオムに対して青色の簡体字註釈を追加でき、学習ツールとしても活用可能です。パイプラインは、動画から16kHz音声を抽出→DashScope ASRで単語タイムスタンプ取得→LLMが註釈対象語句を選定し中国語訳を生成→ASS形式のカラオケ字幕作成→ffmpeg + libassで動画に焼き付け、という手順を1つの非対話型CLI(scripts/pipeline.py)で実行します。Alibaba Cloud Model Studio(DashScope)のAPIキーが必要ですが、ストレージバケットは不要で、ASRが読み込む音声ファイルはDashScopeの無料一時ストレージに自動アップロードされます。中断後の再開やステップごとの再実行にも対応し、進行状況はstderrに、出力ファイルパスはstdoutに出力されるため、CI/CDツールとの連携も容易です。

対応~Claude Code~Codex CLI~Cursor
npx skills add zgyk4167/karaoke-subtitles

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

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

ドキュメント

カラオケ字幕 は何をしますか?

パイプライン: 動画 → 16 kHz 音声 → 単語タイムスタンプ付き DashScope ASR → LLM が用語を選定し中国語註釈を生成 → ASS カラオケ字幕 → ffmpeg と libass で焼き込み。

全ての作業は1つの非対話型CLI scripts/pipeline.py で行います。このファイル内のパスはスキルディレクトリからの相対パスです。任意のディレクトリからスキルパスを前に付けてコマンドを実行してください(例: python3 /path/to/karaoke-subtitles/scripts/pipeline.py doctor)。

初回実行前

  1. python3 scripts/pipeline.py doctor を実行します。終了コード0で準備完了です。キーが設定されている場合、DASHSCOPE_BASE がキーのリージョンと一致するかを確認するため無料リクエストを1回送信します。アップロードや課金は発生しません。そのリクエストをスキップするには --offline を追加します。
  2. 終了コード3で終了した場合、bash scripts/install.sh を実行し、出力される FAIL 行を1つずつ修正します。スクリプトがsudoにパスワードが必要と表示した場合、またはAPIキーが見つからない場合は、処理を停止してユーザーに確認します。ユーザーにキーをチャットに貼り付けさせるのではなく、.env(.env.example 参照)に記載するよう依頼します。
  3. セットアップの詳細と設定: references/prerequisites.md。

ユーザーへの確認事項

  • 動画: ローカルファイルまたはURL。ユーザーが処理する権限を持っている必要があります。
  • 註釈: 有効(デフォルト)または無効(--no-annotate)。
  • 結果の出力先。デフォルト: 出力ファイルパスを返します。

ユーザーから変更の依頼がない限り、視覚スタイルはそのまま維持します。スタイル値: references/ass-style.md。

実行

1つのコマンドで全てを実行し、中断後も再開できます:

python3 scripts/pipeline.py all "<url-or-file>" --work ./job [--no-annotate]

またはステップを1つずつ実行します。各ステップはジョブディレクトリに固定ファイル名を書き込み、既に出力が存在する作業はスキップします。--force を追加すると1つのステップをやり直します。すべてのサブコマンドに --help があります。

ステップ書き出し有料API
fetch <url-or-file>src.mp4いいえ
transcribe [--audio-url URL]audio.mp3, asr_task.json, transcription.jsonはい
annotateannotations.jsonはい
ass [--no-pop] [--no-annotate]subs.assいいえ
render [--segment 1200] [--out FILE]karaoke.mp4いいえ

ASR APIは音声をURLから読み取ります。デフォルトでは、transcribe が job/audio.mp3 をDashScopeの無料一時ストレージにアップロードします。このストレージはファイルを48時間保持し、このアカウントのASRモデルのみが読み取れます。バケットや追加設定は不要です。ユーザーが独自のストレージを希望する場合は、.env 内の AUDIO_URL_CMD でファイルをアップロードしてURLを出力するか、--audio-url URL を渡します。

進行状況はstderrに出力されます。各ステップは出力ファイルのパスをstdoutに出力します。

終了コード

コード意味対応
0完了続行します。
2使用法エラーサブコマンドの --help を読んでください。
3環境未準備next: 行に従うか、doctor を実行します。ユーザーにキーやsudoの入力を依頼するか、リージョン設定を修正します。
4リモートサービス障害next: 行に従います。同じコマンドを再実行すると、完了した作業は保持されます。
5前ステップの入力がないnext: 行に記載されたステップを実行します。
1予期しない障害エラーより上のツール出力を読んでください。

長時間ジョブ

文字起こしとレンダリングはシェルツールの許容時間を超える可能性があります。コマンドをバックグラウンドでログファイルとともに実行してください(例: nohup python3 scripts/pipeline.py all "<src>" --work ./job > job.log 2>&1 &)。その後、ログが終了するまで読み取ります。プロセスが停止した場合は、同じコマンドを再度実行します。文字起こしは保存されたASRタスクを再開するため、再度課金されません。レンダリングは完了済みのセグメントを再利用します。

納品前の確認

出力の中央付近から1フレームを抽出します(ffmpeg -ss <秒> -i job/karaoke.mp4 -frames:v 1 check.jpg)。画像を表示できる場合は確認します。ソースに既に焼き込み字幕がある場合、ユーザーにその旨を伝え、2つのオプションを提示します: ぼかし帯で覆うか、新しい字幕を上部に移動します。

ルール

  • DASHSCOPE_API_KEY を決して出力、ログ、コミットしないでください。doctor は設定されているかどうかのみを報告します。
  • transcribe と annotate はユーザーのアカウントに課金されます。ユーザーが同意しない限り、--force を使用しないでください。
  • 註釈は簡体字中国語のみです。中国語を読まない視聴者には --no-annotate を使用します。
  • ASRは固有名詞や専門用語を聞き間違えたり、小文字で返すことがあります。動画を共有する前に字幕を確認するようユーザーに伝えてください。

関連スキル