カラオケ字幕 は何をしますか?
パイプライン: 動画 → 16 kHz 音声 → 単語タイムスタンプ付き DashScope ASR → LLM が用語を選定し中国語註釈を生成 → ASS カラオケ字幕 → ffmpeg と libass で焼き込み。
全ての作業は1つの非対話型CLI scripts/pipeline.py で行います。このファイル内のパスはスキルディレクトリからの相対パスです。任意のディレクトリからスキルパスを前に付けてコマンドを実行してください(例: python3 /path/to/karaoke-subtitles/scripts/pipeline.py doctor)。
初回実行前
python3 scripts/pipeline.py doctorを実行します。終了コード0で準備完了です。キーが設定されている場合、DASHSCOPE_BASEがキーのリージョンと一致するかを確認するため無料リクエストを1回送信します。アップロードや課金は発生しません。そのリクエストをスキップするには--offlineを追加します。- 終了コード3で終了した場合、
bash scripts/install.shを実行し、出力されるFAIL行を1つずつ修正します。スクリプトがsudoにパスワードが必要と表示した場合、またはAPIキーが見つからない場合は、処理を停止してユーザーに確認します。ユーザーにキーをチャットに貼り付けさせるのではなく、.env(.env.example参照)に記載するよう依頼します。 - セットアップの詳細と設定:
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 | はい |
annotate | annotations.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は固有名詞や専門用語を聞き間違えたり、小文字で返すことがあります。動画を共有する前に字幕を確認するようユーザーに伝えてください。