dsh-bilibili-subtitles は何をしますか？

Bilibili のビデオリンクを、読みやすく、検索可能で、配布可能な字幕文書に変換します。

核となる原則：まず既存の字幕を取得し、その後で音声書き起こしや OCR を検討する。最初から動画/音声をダウンロードして Whisper を実行しないでください。B 站のプラットフォーム字幕（AI 字幕を含む）は通常、品質が高く、処理も高速です。

使用タイミング

適しているケース：

ユーザーが Bilibili のビデオリンク、BV 番号、av 番号、アニメの ep/ss リンク、または b23.tv の短縮 URL を提供し、「字幕の抽出/原稿への整理/Word や Markdown へのエクスポート」を要求する場合。
ユーザーがローカルビデオと外部字幕ファイルを持っており、それらを一括で文書に変換したい場合。
ユーザーがタイムスタンプ付き、二ヶ国語対訳、複数パートを結合した字幕原稿を必要としている場合。
ユーザーが字幕の品質レポートを必要としており、人手による校正が必要かどうかを判断したい場合。

適さないケース：

「字幕の翻訳」が必要な場合：このスキルは二ヶ国語のアライメントのみを行い、機械翻訳は行いません。
正確な話者分離が必要な場合：自動ダイアライゼーションはまだ有効になっていません。字幕内の既存の [話者] タグのみが保持されます。
Bilibili のログイン/課金/地域制限をバイパスする必要がある場合：ユーザーに使用権限のある Cookie を提供してもらうか、代わりにローカルファイルを使用するようにしてください。

インストールと呼び出し

プラグインとして： https://github.com/Chenfan2/dsh-bilibili-subtitles（DSH デスクトップ版の「プラグイン → プラグインを追加」で URL を貼り付けるか、dsh plugin --profile web add github:Chenfan2/dsh-bilibili-subtitles を実行）。
単体スキルとして： ディレクトリ全体を DSH の skills ディレクトリにコピーします（または install.ps1 を実行）。

インストール後、ディレクトリ内で以下を実行します：

python main.py "https://www.bilibili.com/video/BV1xx411c7mD" --format md,docx

一時的に使用するだけなら、インストールせずにスキルディレクトリで直接 main.py を実行することもできます。

ワンコマンド

python main.py "https://www.bilibili.com/video/BV1xx411c7mD" --format md,docx

出力は output/ ディレクトリに生成されます：

タイトル_BV番号.md
タイトル_BV番号.docx
タイトル_BV番号.quality.json（品質レポート）
タイトル_BV番号.segments.json（洗浄された構造化字幕）
_manifest.json（今回の実行の集約リスト）

入出力契約

入力

タイプ	例
Bilibili ビデオ	`https://www.bilibili.com/video/BV1xx411c7mD?p=2`
BV / av 番号	`BV1xx411c7mD`、`av80433022`
アニメ	`https://www.bilibili.com/bangumi/play/ep123456`、`.../ss28747`
短縮 URL	`https://b23.tv/xxxxxx`
ローカルビデオ	`input.mp4`、`input.mkv`
外部字幕ファイル	`--subtitle input.srt`（`.ass/.vtt/.json/.txt` も対応）
ディレクトリ/一括	`python main.py ./videos --format md,docx`

出力

文書ファイルのパス（Markdown/Word/PDF/TXT/SRT）。
構造化字幕：[{start, end, text, speaker?, lang?, confidence?, translation?}]。
品質レポート：字幕のソース、言語、カバレッジ、低信頼度セグメント、警告、先頭/中間/末尾のサンプル。
処理試行記録：各プロバイダーの成功/失敗/スキップとその理由。

字幕ソースの優先順位

以下の順序で試行し、明示的に無効化されていない限り、失敗した場合は自動的にダウングレードします：

ユーザーの外部字幕ファイル（--subtitle）：最高品質で、完全に制御可能。
Bilibili プラットフォーム字幕 / AI 字幕：x/player/v2 API 経由で読み取り、SESSDATA が必要。
ローカルビデオの埋め込み字幕：ffprobe で検出し、ffmpeg で SRT に抽出。
ハードコード字幕の OCR：ローカルビデオのみ、--ocr で有効化。実験的機能。
Whisper 音声書き起こし：--asr で有効化、または自動フォールバック。初回はモデルをダウンロードします。

ログインしていない場合、Bilibili は通常字幕リストを返しません。この場合、LOGIN_REQUIRED が表示され、Cookie の提供または ASR の有効化を促すメッセージが表示されます。これはプラットフォームの制限であり、リンクエラーではありません。

Bilibili ログイン（プラットフォーム字幕に必須）

プラットフォーム字幕 API は、ログインセッションに対してのみ subtitle_url を返します。環境変数を使用することを推奨します。これにより、コマンド履歴に残るのを防げます：

$env:BILIBILI_SESSDATA = "あなたのSESSDATA"
python main.py "https://www.bilibili.com/video/BV1xx411c7mD" --format md,docx

取得方法：ブラウザで bilibili.com にログイン → デベロッパーツール → Application/アプリケーション → Cookies → bilibili.com → SESSDATA の値をコピー。

以下の方法もサポートしています：

python main.py URL --sessdata "SESSDATAの値"
python main.py URL --cookie "SESSDATA=...; bili_jct=..."
python main.py URL --cookies cookies.txt

Cookie はアカウント資格情報と同等です。リポジトリ、文書、公開チャンネルに書き込まないでください。
このスキルはメモリ上でのみ Cookie を使用し、ログやレポートではマスクされます。
Cookie の有効期限が切れた場合は、再度コピーしてください。

よく使うパラメータ

パラメータ	機能
`--format md,docx,pdf,txt,srt,json`	出力フォーマット（カンマ区切り）。デフォルトは `md`
`-o, --output PATH`	単一入力＋単一フォーマット時に出力ファイルを指定
`--out-dir DIR`	出力ディレクトリ。デフォルトは `output`
`--title TEXT`	文書のタイトルを上書き（デフォルトはビデオタイトル/ファイル名）
`--subtitle PATH`	外部字幕ファイルまたはディレクトリ（最優先）
`--language zh`	優先する字幕/書き起こし言語。プラットフォーム字幕は言語でマッチング
`--bilingual`	二ヶ国語対訳。2 つの字幕トラックがある場合は時間でアライメント、1 トラックの場合は行で分割を試行
`--timestamps` / `--no-timestamps`	本文に `[00:12]` を表示するかどうか。デフォルトは表示
`--merge-sentences` / `--no-merge-sentences`	強制的に分割された短文を結合するかどうか。デフォルトは結合
`--no-auto-punctuation`	ASR/OCR の自動句読点補完を無効化（デフォルトは有効）
`--pages auto/all/1,3-5`	パート（P）の選択。デフォルトはリンクで指定された P のみ、未指定の場合は P1
`--template default/minimal/ファイル.md`	Markdown テンプレート
`--quality-report PATH`	品質レポート JSON の出力パス
`--no-quality`	品質レポートを生成せず、文書にも処理情報を付加しない
`--glossary terms.json`	用語置換（例：`{"DeepSeek":"深度求索"}`）
`--json-summary`	stdout に機械可読な要約を出力（エージェントが読み取るため）
`--asr` / `--no-asr`	Whisper フォールバックを許可/禁止。デフォルトは自動（インストールされていれば試行）
`--asr-model small`	`tiny/base/small/medium`。デフォルトは `small`
`--model-dir DIR`	Whisper モデルキャッシュディレクトリ（デフォルトは `./.vsub-models-cache`）
`--ocr`	ローカルビデオのハードコード字幕を OCR（実験的）
`--ffmpeg PATH`	ffmpeg/ffprobe のパスを指定
`--strict`	いずれかの入力が失敗した場合、または品質が `fail` の場合に非ゼロ終了コードを返す

完全なパラメータ一覧：python main.py --help。

推奨ワークフロー（エージェント向け）

入力を判別する：
- Bilibili リンク/BV/av → 直接実行。
- ローカルビデオ → 同名の .srt/.vtt/.ass ファイルがないか確認。あれば --subtitle を優先。なければ埋め込み字幕を試行。
- 字幕ファイルのみ → そのまま入力として使用可能。
まずデフォルト出力で実行する。品質レポートを確認せずに ASR を有効にしない：
```
python main.py "<リンク>" --format md,docx --out-dir output
```
LOGIN_REQUIRED が発生した場合：
- プラットフォーム字幕には SESSDATA が必要であることをユーザーに伝え、設定方法を案内する。再試行は行わない。
- ユーザーが Cookie を持っていない場合は、--asr を提案する（初回のモデルダウンロード、処理時間、認識エラーの可能性があることを説明する）。
<stem>.quality.json を確認する：
- status=ok：そのまま納品する。
- status=warn：warnings を確認する。特にカバレッジ、重複、低信頼度セグメントに注意。納品時の説明に注意書きを追加する。
- status=fail：成功したふりをしない。失敗理由を報告し、外部字幕/ASR/OCR を提案する。
present ツールを使って .md / .docx を最終ファイルとして納品する。品質レポートはユーザーが要求した場合のみ添付する。

実行環境：

load_workspace_dependencies が返す Python を優先的に使用する（python-docx が含まれている）。

Windows PowerShell での呼び出し例：

& "C:\...\python.exe" main.py "<リンク>" --format md,docx --out-dir output

すべての出力と一時ファイルはセッションワークスペース内に配置する。システムの一時ディレクトリは使用しない（サンドボックスによって拒否される可能性がある）。

品質レポートのフィールド

{
  "status": "ok | warn | fail",
  "score": 96.5,
  "source": "bilibili",
  "language": "zh",
  "segments": 320,
  "paragraphs": 86,
  "duration": 1260.0,
  "duration_covered": 0.96,
  "coverage_span": 0.99,
  "overlaps": 0,
  "low_confidence_segments": 3,
  "duplicate_segments": 1,
  "gaps_over_10s": 2,
  "warnings": ["..."],
  "samples": {"head": [], "middle": [], "tail": []}
}

duration_covered：完全なビデオ長に対する相対値。オープニング/エンディングの広告が削除されると低くなることがある。
coverage_span：最初と最後の字幕間のコンテンツ区間に対する相対値。「発話部分がカバーされているか」をより反映する。
samples：先頭/中間/末尾から最大 5 セグメントずつ。手動サンプリングチェックに便利。
status=fail の一般的な原因：セグメントなし、カバレッジが 30% 未満、すべてのパート（P）が失敗。

失敗とダウングレード

状況	動作
外部字幕ファイルの解析失敗	失敗を記録し、プラットフォーム/埋め込み字幕の試行を続行
プラットフォーム字幕 `LOGIN_REQUIRED`	`SESSDATA` の設定を促す。faster-whisper がインストール済みで ASR が許可されていれば、自動書き起こしを実行
プラットフォームに字幕トラックがない	`NO_SUBTITLE` を報告。`--asr` または `--subtitle` を提案
埋め込み字幕が PGS/VobSub ビットマップ形式	SRT に直接変換不可。OCR または外部字幕の使用を促す
ASR がインストールされていない	スキップし、`pip install faster-whisper` を表示。静かに失敗することはない
特定の出力フォーマットで失敗	他のフォーマットは生成を続行。`quality.warnings` に記録。すべてが失敗した場合のみ `RENDER_FAILED` を報告
一括処理で一部が失敗	成功したものは出力を続行。失敗は `_manifest.json` と `*.error.json` に記録

終了コード：

0 成功（一括処理の場合は少なくとも 1 つが成功したことを意味する）
2 入力/リンク/API/解析エラー
3 字幕なし、ログインが必要、品質失敗
4 依存関係の欠如（ffmpeg/Whisper/docx など）
5 文書レンダリング失敗
1 予期しないエラー

使用例

# 基本：プラットフォーム字幕 → Markdown + Word
python main.py "https://www.bilibili.com/video/BV1xx411c7mD" --format md,docx

# Word のみ、ファイル名指定
python main.py "BV1xx411c7mD" --format docx -o "論文ノート.docx"

# 複数パート + タイムスタンプ + 品質レポート
python main.py "https://www.bilibili.com/video/BV1xx411c7mD?p=1" --pages all --format md

# 外部字幕ファイルを優先
python main.py "input.mp4" --subtitle "input.srt" --format md,docx

# 二ヶ国語（プラットフォームに 2 トラックある場合、自動アライメント）
python main.py "BV1xx411c7mD" --bilingual --language zh --format md,docx

# ログインなし、ASR でフォールバック（初回はモデルをダウンロード）
python main.py "BV1xx411c7mD" --asr --asr-model small --format md,docx

# ディレクトリを一括処理
python main.py "./videos" --format md,docx --out-dir output/batch

# ローカルビデオのハードコード字幕を OCR（実験的）
python main.py "input.mp4" --ocr --ocr-fps 2 --format md

制限事項

プラットフォーム字幕が利用可能かどうかは、動画、アカウント、地域、UP 主の設定に依存します。このスキルで権限をバイパスすることはできません。
AI 字幕には誤字、文の欠落、タイムラインのずれが含まれる可能性があります。品質レポートはそれを示唆するだけで、人手による校正の代わりにはなりません。
二ヶ国語は「時間アライメント」であり、翻訳ではありません。2 つのトラックの言語が異なる場合にのみ対照表示されます。
自動話者分離は実装されていません。字幕内の [张三]、【张三】、张三： などのタグのみを解析します。
OCR はローカルビデオのみで、デフォルトでは下部 30% の領域を処理します。アニメーション、縦長動画、字幕位置がずれている場合は、--ocr-crop または --ocr-full-frame を調整する必要があります。
PDF 出力には LibreOffice または reportlab が必要です。ない場合は明確にエラーを報告し、md/docx の生成には影響しません。
長い動画の ASR は非常に遅くなる可能性があります。small モデルの初回ダウンロードサイズは約 460MB です。

著作権とプライバシー

ユーザーが使用する権利を有する動画/字幕のみを処理します。このスキルを使用して著作権で保護されたコンテンツを一括スクレイピングしないでください。
字幕文書には、元の動画タイトル、UP 主、リンクが保持され、トレーサビリティが確保されます。
Cookie、署名付き CDN URL はログ/品質レポートに書き込まれません。それでも、ユーザーが公開の場で Cookie を貼り付けないことを推奨します。
一時的な音声/フレーム抽出ファイルは、デフォルトで出力ディレクトリの .vsub-tmp に保存され、実行後に自動的にクリーンアップされます。--keep-temp でデバッグ用に保持できます。

ファイル構成

dsh-bilibili-subtitles/
├── SKILL.md
├── README.md
├── main.py                  # CLI エントリポイント
├── vsub/
│   ├── bilibili.py          # URL/API/字幕/音声
│   ├── input_adapter.py     # 入力アダプター
│   ├── pipeline.py          # 5 層パイプラインオーケストレーション
│   ├── providers/           # external/bilibili/embedded/ocr/asr
│   ├── parsers/             # srt/vtt/ass/bilibili-json/plain
│   ├── cleaners/            # 洗浄、結合、二ヶ国語、用語
│   ├── renderers/           # md/docx/pdf/txt/srt/json
│   └── quality.py           # 品質検証
├── templates/
├── tests/
└── requirements.txt

dsh-bilibili-subtitles