Communitygithub.com

FlowLeev/bilibili-audio-subtitles

yutto で Bilibili 音声、yt-dlp で YouTube 音声をダウンロードし、Qwen3-ASR と ForcedAligner でタイムスタンプ付き SRT 字幕を生成、品質チェックも行います。Whisper も選択可能です。B 站や YouTube のリンクから字幕を作成したり、既存音声を文字起こししたりできます。ダウンロード失敗時は対応パッケージの更新を優先チェックします。

bilibili-audio-subtitles とは?

このスキルは、Bilibili や YouTube の動画や音声から、高精度なタイムスタンプ付き SRT 字幕ファイルを生成するために設計されています。`codex` という conda 環境を使用し、デフォルトの文字起こしエンジンは **Qwen3-ASR (1.7B)** と **Qwen3-ForcedAligner (0.6B)** の組み合わせで、これらは公式の `qwen-asr` ツールキットを介して呼び出され、単語/文字レベルのタイムスタンプを提供します。`--engine whisper` オプションを使用すると、`openai/whisper-large-v3-turbo` のネイティブな長音声モードも利用可能で、主に Qwen が時間情報をサポートしない言語や比較目的で使用します。 Bilibili の音声ダウンロードには **yutto**、YouTube の音声ダウンロードには **yt-dlp** を使用し、それぞれ M4A 形式で保存します。ダウンロードが失敗した場合、スクリプトは自動的に対応するダウンロードパッケージ(yutto または yt-dlp)の安定版アップデートを確認し、見つかればそれをアップグレードして再試行します。このスキルは、構造チェック(字幕の完全性)と品質チェック(字幕の長さや密度の異常、重複など)を実施し、結果に応じて異なる終了コード(0: 正常、2: 要確認、1: エラー)を返します。最終的に、タイムスタンプと字幕テキストを含む単一の SRT ファイルのみが成果物として生成されます。

対応✓Claude Code✓Codex CLI~Cursor
npx skills add FlowLeev/bilibili-audio-subtitles

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

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

ドキュメント

Bilibili / YouTube 音声を字幕に変換

codex という名前の conda 環境を使用し、元の言語で文字起こしを行います。デフォルトのモデルは Qwen/Qwen3-ASR-1.7B + Qwen/Qwen3-ForcedAligner-0.6B で、公式の qwen-asr ツールキットを介して return_time_stamps=True を指定して呼び出されます。ASR モデル自体はテキストのみを生成し、ForcedAligner が単語/文字レベルのタイムスタンプを提供します。句読点、ポーズ、約 6 秒および 42 文字に基づいて SRT を構成し、境界は実際のアライメント結果から取得されます。時間を均等に分割したり、テキストを削除したりすることはありません。

--engine whisper オプションは、openai/whisper-large-v3-turbo のネイティブな長音声モードを維持し、パイプラインは return_timestamps=True を使用し、chunk_length_s は渡しません。Whisper の実験的な外部チャンク分割は、かつて 5 分間の字幕セグメントと連続した重複を生成したため、デフォルトで有効にすべきではありません。Qwen の公式 SDK は、アライメントのために低エネルギー境界で最大 180 秒のセグメントを処理し、グローバルタイムを自動的に復元します。これは Whisper の実験的な 30 秒パイプライン分割とは異なる実装です。

Qwen のタイムスタンプは、中国語、英語、広東語、フランス語、ドイツ語、イタリア語、日本語、韓国語、ポルトガル語、ロシア語、スペイン語をサポートしています。他の言語の場合は明示的に Whisper を選択してください。ASR がその言語をサポートしているからといって、アライメントもサポートしているとは限りません。デフォルトでは自動検出されます。言語が既知の場合は --language chinese または --language english を渡します。上記言語の一般的なコード(zh、en など)も受け付けます。

実行と出力

まず、ユーザーの現在のプロジェクトの絶対パスを記録します。スキルのインストールディレクトリをプロジェクトディレクトリと見なさないでください。<skill_dir> をこの SKILL.md が存在するディレクトリに置き換え、<project_dir> を呼び出し時のプロジェクトパスに置き換えます。URL は引用符で囲まれた単一のパラメータとして渡します。

conda run --no-capture-output -n codex python "<skill_dir>/scripts/bilibili_audio_subtitles.py" \
  'https://www.bilibili.com/video/BV1w88n6uE1X/' \
  --project-dir '<project_dir>'

同じコマンドで YouTube リンクも受け付けます(例:'https://youtu.be/jNQXAC9IVRw')。元のスキル名とスクリプト名を維持し、既存の $bilibili-audio-subtitles 呼び出しも引き続き使用できます。

Bilibili の音声は yutto によってダウンロードされ、~/Downloads/<BV 番号または av 番号>-p<N>.m4a に保存されます。YouTube の音声は yt-dlp によってダウンロードされ、~/Downloads/youtube-<動画 ID>.m4a に保存されます。プロジェクトディレクトリには、タイムスタンプと字幕テキストを含む 1 つの SRT ファイルのみが出力され、最終的にこの推奨字幕のみが提供されます。 VTT、TXT、JSON、またはモデル比較ファイルは別途提供されません。必要な品質警告は簡単な説明で確認を促すために表示され、追加の配信ファイルは生成されません。元のモデル text/chunks と再現診断は、~/.cache/bilibili-audio-subtitles/runs/ の個別の JSON に保存されます。実行ログにパスが提供されます。これは内部診断記録であり、追加の字幕配信ファイルではありません。

既存の音声ファイルは再利用されます。既存の SRT ファイルと同じ名前の場合、新しい結果は自動的にモード、スクリプトバージョン、実行番号を含む一意のファイル名を使用し、旧バージョンを保持します。古い字幕を上書きまたは削除することはありません。再試行後は、すべてのパスをリストするだけでなく、使用が推奨される SRT バージョンをユーザーに明確に示します。

よく使われるオプション:

  • --audio '/絶対パス/音声.m4a':ローカル音声を文字起こし。URL は同時に渡しません。
  • --language chinese:言語が既知の場合は明示的に指定。デフォルトは自動認識。
  • --engine qwen|whisper:デフォルトは Qwen。Whisper は比較、速度優先、または Qwen がアライメントをサポートしない言語に使用。
  • --project-dir / --download-dir:プロジェクト出力ディレクトリまたは Downloads ディレクトリを上書き。
  • --device auto|cpu|cuda:0:デフォルトでは CUDA を優先。システムドライバを自動的に変更しないでください。
  • --download-only:ダウンロードのみ実行し、後で --audio を使用して続行。
  • --output-name 'ファイル名':SRT ファイル名をカスタマイズ。パスや拡張子を含めないでください。
  • --diagnostics-dir '/絶対パス':内部の生の結果と診断ディレクトリを上書き。
  • --auth-file '/絶対パス':ユーザーが既に提供している Bilibili/yutto 認証ファイルにのみ使用。
  • --cookies-file '/絶対パス':ユーザーが既に提供している YouTube Netscape Cookie ファイルにのみ使用。ブラウザをスキャンしません。
  • --max-cue-seconds 12:非常に長い字幕の警告しきい値。デフォルトは 12 秒。
  • --limit-seconds 30:ユーザーが要求したセグメントまたはスモークテスト。ファイル名に "sample" とマークされ、レポートで完全な文字起こしではないことが明確に示されます。
  • --threads 8 / --batch-size 1:スレッド数と推論バッチサイズを制御。
  • --engine whisper --chunk-length-seconds 30:明確な理由があり、実験的リスクを説明した場合にのみ有効にします。Qwen はこのパラメータを受け付けません。

Bilibili の標準的な /video/BV…、/video/av… リンク、および直接の BV/av 番号をサポートします。?p=N で指定された P を保持し、トラッキングパラメータは削除します。デフォルトでは 1 つの P のみを処理します。複数の P が要求された場合は、P ごとに呼び出します。B 站の短縮リンクは最初に標準リンクに解決されます。

YouTube は youtube.com/watch?v=…、youtu.be/…、shorts/…、live/…、embed/…(www、m、music サブドメインを含む)をサポートします。単一動画の標準リンクに統一し、トラッキング、開始時間、プレイリストパラメータを削除し、明示的に --no-playlist を使用します。プレイリストのみのリンクは直接拒否します。bestaudio をダウンロードし、FFmpeg で M4A に抽出します。プラットフォームの字幕、サムネイル、動画を配信ファイルとしてダウンロードしません。ブラウザをスキャンせず、Cookie を出力せず、独断でコレクション全体に拡張しません。

ダウンロード失敗時は更新を優先チェック

このルールは両方のプラットフォームに適用されます。実際のダウンロードが失敗した場合、またはダウンローダーが成功を返したが有効な音声がない場合、スクリプトは最初に対応するダウンロードパッケージの互換性のある安定バージョンを確認します。Bilibili は yutto、YouTube は yt-dlp を確認します。現在の codex Python の pip index versions <パッケージ> --json を使用して、ローカルとパッケージインデックスのバージョンを比較し、既存の pip ミラー設定を尊重します。

新しいバージョンがある場合、スクリプトはその環境でのみこのダウンロードパッケージとその必要な依存関係をアップグレードし、ダウンロードを1 回だけ再試行します。yt-dlp は yt-dlp[default] を使用し、YouTube EJS 依存関係のマッチングを維持します。新しいバージョンがない場合、クエリが失敗した場合、アップグレードが失敗した場合、または 2 回目のダウンロードも失敗した場合、元のエラーと更新イベントを保存して停止します。無限に再試行したり、自動的に nightly/master に切り替えたりしないでください。パッケージの更新をチェックした後、実際のエラーに基づいてネットワーク、ログイン、動画の削除、地域制限、JS ランタイムを確認します。

更新にはネットワークと環境への書き込み権限が必要です。権限が制限されている場合は、今回必要な権限を申請します。システム Python を変更したり、ダウンロードの問題で文字起こしモデルや PyTorch を更新したりしないでください。更新クエリの失敗は、最新バージョンであることを意味しません。既存の破損した音声は明確に報告して保持し、直接上書きしないでください。失敗後に再試行で生成された無効な音声も、独立した名前で保持します。

構造チェックと品質チェック

2 種類のチェックは別々に報告する必要があります。

  • 構造チェック:完全な音声デコード時間のマッチング、空でない字幕、制限付きで順序付けられ、有効な開始/終了を持つタイムスタンプ、文字起こし時間を超えないこと。失敗した場合は、元の診断を保持し、SRT を生成しません。
  • 品質チェック:字幕が 12 秒を超える、単一の字幕が 120 文字を超える、テキスト密度が 25 文字/秒を超える、少なくとも 8 秒間続くが 0.5 文字/秒未満、単一の字幕で同じ単語やフレーズが少なくとも 5 回連続する、少なくとも 3 つの連続した字幕が同じテキスト。タイムスタンプの修正が必要な場合も、確認のためにフラグが立てられます。しきい値と警告の詳細は診断に書き込まれます。

終了コード 0 は、構造チェックに合格し、明らかな品質異常が見つからなかったことを意味します。終了コード 2 は、SRT が生成されたが確認が必要であることを意味します。終了コード 1 は、実行または構造の失敗を意味します。終了コード 2 をチェック成功と宣伝しないでください。品質ルールは発見的なヒントであり、音声コンテンツの正確性の証明ではありません。誤検出については、音声と照らし合わせて判断する必要があります。警告をなくすために、しきい値を恣意的に引き上げたり、テキストを削除したり、時間を均等に分割して再分割したり、無限に再試行したりしないでください。

品質異常が発生した場合は、警告時間枠と診断パスを提供します。異常が明示的な Whisper 外部チャンク分割からのものである場合は、--engine whisper ネイティブモードで 1 回再試行し、両方のラウンドの出力を保持します。それでも異常がある場合は、確認が必要であることを説明し、自動的にモデルを切り替えたり、無限に再試行したりしないでください。用語の修正は個別に処理します。推測に基づいて「注文フロー」や「マウス」などの単語をグローバルに置き換えないでください。警告がない場合でも、これは機械による文字起こしのドラフトに過ぎず、文単位で校正された字幕と呼ぶことはできません。

診断 JSON は、元の text/chunks、正規化された segments、構造ステータス、品質ステータスと警告、修正記録、推奨ステータス、スクリプトバージョン、文字起こしモード、生成パラメータ、モデル GenerationConfig と revision、ライブラリバージョン、デバイス、所要時間、推論時間を保持します。また、ソースプラットフォーム、ダウンロードパッケージバージョン、更新チェックと再試行イベントも記録します。Qwen はさらに、SDK 後処理前の元の ASR 文字列、完全なアライメントユニット、検出された言語、持続時間ゼロのユニット数、アライメントモデル revision、セグメンテーション設定を保持します。生の出力の重複や生成長さの上限に近い場合も確認がトリガーされ、SDK の重複フィルタリングで異常を隠蔽させないようにします。量子化されたタイムスタンプ内の持続時間ゼロの単語は隣接する字幕にマージされ、テキストは保持されます。単語レベルの持続時間を偽造しないでください。有効な持続時間がない、またはテキストが一致しないセグメント全体については、元の結果を保存して失敗します。ダウンロードまたは文字起こしの失敗も独立した診断として保存され、再現と比較に使用できます。

環境

codex 環境の Python、対応するプラットフォームのダウンロードパッケージ、torch、transformers、accelerate、numpy、qwen-asr、および PATH 内の ffmpeg と ffprobe を確認します。不足している依存関係のみをその環境にインストールします。

conda run --no-capture-output -n codex python -m pip install yutto 'yt-dlp[default]' 'qwen-asr==0.0.6' numpy

Qwen ツールキットは Transformers 4.57.6 と accelerate 1.12.0 を固定します。このタスクのために Transformers 5 にアップグレードしたり、vLLM をインストールしたりしないでください。既存の利用可能な CUDA PyTorch は保持します。検証済みのローカル環境:Python 3.12、qwen-asr 0.0.6、yutto 2.3.1、Transformers 4.57.6、PyTorch 2.14.1+cu130。CUDA では、Qwen は bfloat16 と SDPA を使用します。FlashAttention のコンパイルは必要ありません。ローカル GPU 環境を再構築する必要がある場合:

conda run --no-capture-output -n codex python -m pip install 'torch==2.14.1+cu130' --index-url https://download.pytorch.org/whl/cu130

シェルが conda を見つけられない場合は、その絶対パスを特定します。ローカルでは /home/leev/miniforge3/bin/conda または /home/leev/miniforge3/envs/codex/bin/python を使用できます。制限されたサンドボックス内で GPU 検出が失敗した場合は、まず NVIDIA デバイスへのアクセスが許可された環境で再検出し、ドライバの破損を即座に判断したり、CPU バージョンに切り替えたりしないでください。実際に GPU がないマシンでのみ、一致する CPU PyTorch を使用します。

YouTube では、yt-dlp のデフォルトの EJS サポート依存関係とサポートされている JS ランタイムも必要です。スクリプトは PATH 内の Deno、Node、Bun、または QuickJS を検索し、明示的に yt-dlp に渡します。ローカルでは、Node 24 と yt-dlp 2026.08.19 が検証されています。ランタイムが見つからない場合やバージョンの互換性がない場合は明確に報告し、ダウンロードの失敗を理由に他のパッケージを繰り返し再インストールしないでください。

初回実行時は、モデルが Hugging Face 標準キャッシュにダウンロードされます。HF_HOME / HF_HUB_CACHE を尊重します。完全なキャッシュが既にあり、ネットワークが不安定な場合は、HF_HUB_OFFLINE=1 を設定できます。B 站は yutto を使用してダウンロードするのみで、動画、弾幕、プラットフォーム字幕、サムネイル、チャプター情報は無効にします。YouTube は yt-dlp を使用して音声のみをダウンロードします。ダウンロードが失敗した場合は、最初に更新ルールに従って処理してから、実際のエラーを報告します。文字起こしが失敗した場合は、音声を保持します。権限が制限されている場合は、今回必要なディレクトリと GPU 実行権限を申請します。

回帰検証

固定サンプル:BV1w88n6uE1X。同じ音声を使用してデフォルトの Qwen で完全な文字起こしを実行します。比較が必要な場合は、--engine whisper を使用し、両方のラウンドの診断を保持して以下を呼び出します。

python -m unittest discover -s '<skill_dir>/scripts' -p 'test_*.py'
python '<skill_dir>/scripts/check_regression.py' \
  --candidate '<新バージョンキャッシュ診断JSON>' --baseline '<旧バージョンJSON>'

重要な時間枠は 00:43.240–05:46.060 と 08:10–08:33 です。実測では、Qwen は 282 セグメント、最長 5.76 秒、Whisper ネイティブは 438 セグメント、最長 5.18 秒で、両方のウィンドウで長すぎるセグメントや重複の警告はありませんでした。固定のセグメント数を他の環境の合格条件としないでください。旧バージョンの 117 セグメント結果にある 302.82 秒の字幕と連続した 23 個の「好」は、新しいバージョンの品質チェックで確認が必要とマークされるはずです。回帰合格は、既知のセグメンテーションと重複の問題が再現しなかったことのみを証明し、セマンティクスと用語は引き続き音声と照らし合わせる必要があります。

YouTube の回帰には、watch/短縮リンク/Shorts ルート、単一動画の音声のみのダウンロード、失敗時の優先更新チェック、アップグレード後の最大 1 回の再試行、更新がない場合またはクエリ失敗時の停止が含まれます。実測では、jNQXAC9IVRw の約 19 秒の音声が完全にダウンロードされ、Qwen は 7 セグメントの SRT を生成しました(Whisper は 4 セグメント)。利用できなくなったテスト動画でも、更新チェックと失敗診断パスが検証されました。

モデルの選択、実測所要時間、制限事項については references/model-evaluation.md を参照してください。モデルの比較や再評価の際に読み取ってください。現在のデフォルトは中国語の用語認識品質に重点を置いていますが、すべての言語やすべての音声で Whisper より優れていると主張することはできません。

実装の根拠:yutto 公式プロジェクト、yt-dlp 公式プロジェクト、Qwen3-ASR 公式プロジェクト、Whisper モデル説明。

関連スキル