Chenfan2/dsh-bilibili-subtitles

dsh-bilibili-subtitles 是做什麼的？

把一條 Bilibili 影片連結變成可讀、可搜尋、可交付的字幕文件。

核心原則：先取現成字幕，再考慮語音轉寫或 OCR。不要一上來就下載影片/音訊做 Whisper；B 站平台字幕（含 AI 字幕）品質通常更好，也更快。

何時使用

適用：

• 使用者給出 Bilibili 影片連結、BV 號、av 號、番劇 ep/ss 連結或 b23.tv 短網址，要求「提取字幕/整理成文稿/匯出 Word/Markdown」。
• 使用者有本機影片 + 外掛字幕，想批量轉成文件。
• 使用者需要帶時間戳、雙語對照、分P合併的字幕稿。
• 使用者需要一份字幕品質報告，判斷是否值得人工校對。

不適用：

• 需要「翻譯」字幕：本技能只做雙語對齊，不做機器翻譯。
• 需要精確的說話人分離：自動 diarization 尚未啟用；只保留字幕裡已有的 [說話人] 標記。
• 需要繞過 B 站登入/付費/地區限制：請使用者提供其有權使用的 Cookie，或改用其本機檔案。

安裝與呼叫

• 外掛：https://github.com/Chenfan2/dsh-bilibili-subtitles（DSH 桌面端「外掛 → 新增外掛」貼上網址，或 dsh plugin --profile web add github:Chenfan2/dsh-bilibili-subtitles）。
• 純 skill：把整個目錄複製到 DSH 的 skills 目錄（或執行 install.ps1）。

安裝後在目錄內執行：

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

如果只是臨時使用，也可以不安裝，直接在 skill 目錄執行 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
短網址	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?}]。
• 品質報告：字幕來源、語言、覆蓋率、低信心度片段、警告、前/中/尾抽樣。
• 處理嘗試記錄：每個 provider 的成功/失敗/跳過及原因。

字幕來源優先順序

按以下順序嘗試，失敗會自動降級，除非明確停用：

1. 使用者外掛字幕（--subtitle）：品質最高，完全可控。
2. Bilibili 平台字幕 / AI 字幕：透過 x/player/v2 讀取，需要 SESSDATA。
3. 本機影片內嵌字幕：ffprobe 偵測 + ffmpeg 提取為 SRT。
4. 硬字幕 OCR：僅本機影片，--ocr 開啟；實驗性。
5. Whisper 語音轉寫：--asr 開啟或自動兜底；首次會下載模型。

沒有登入時，B 站通常不回傳字幕列表。此時會給出 LOGIN_REQUIRED，並提示提供 Cookie 或啟用 ASR。這是平台限制，不是連結錯誤。

Bilibili 登入（平台字幕必需）

平台字幕介面只對登入工作階段回傳 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	雙語對照；有兩條字幕軌時按時間對齊，單軌時嘗試按行拆分
--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 輸出機器可讀摘要（便於 agent 讀取）
--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。

推薦工作流程（agent）

1. 判斷輸入：

   • Bilibili 連結/BV/av → 直接跑。
   • 本機影片 → 檢查同名 .srt/.vtt/.ass，有就優先 --subtitle；沒有則嘗試內嵌字幕。
   • 只有字幕檔案 → 也可直接作為輸入。

2. 先跑預設輸出，不要在沒看品質報告前就開 ASR：

   python main.py "<連結>" --format md,docx --out-dir output
   

3. 如果報 LOGIN_REQUIRED：

   • 告訴使用者平台字幕需要 SESSDATA，並給出設定方法；不要反覆重試。
   • 使用者沒有 Cookie 時，再建議 --asr（說明首次下載模型、耗時、可能產生辨識錯誤）。

4. 檢查 <stem>.quality.json：

   • status=ok：直接交付。
   • status=warn：看 warnings，尤其是覆蓋率、重疊、低信心度；在交付說明中提醒。
   • status=fail：不要假裝成功；報告失敗原因，建議外掛字幕/ASR/OCR。

5. 用 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 成功（批量時表示至少有一個成功）
• 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"

# 多分P + 時間戳 + 品質報告
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

# 雙語（平台有兩條軌時自動對齊）
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 字幕本身可能錯字、漏句、時間軸飄移；品質報告只能提示，不能替代人工校對。
• 雙語是「時間對齊」，不是翻譯；兩條軌語言不同才會對照。
• 自動說話人分離未實現；只解析字幕中的 [張三]、【張三】、張三： 等標記。
• 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          # 五層流水線編排
│   ├── 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