bilibili-subtitle

Bilibili Subtitle Extraction Tool

Extract subtitles from Bilibili videos, supporting AI subtitle detection and ASR transcription fallback.

Quick Reference

Task	Command
Pre-check	`pixi run python -m bilibili_subtitle --check`
Basic Extraction	`pixi run python -m bilibili_subtitle "BV1234567890"`
Quick Mode	`pixi run python -m bilibili_subtitle "URL" --skip-proofread --skip-summary`
JSON Output	`pixi run python -m bilibili_subtitle "URL" --json-output`
Bilingual Output	`pixi run python -m bilibili_subtitle "URL" --output-lang zh+en`

Execution Tiers

┌─────────────────────────────────────────────────────────┐
│ Layer 0: Preflight Check (前置检查)                      │
│   --check → 验证 BBDown/API Keys/登录状态               │
├─────────────────────────────────────────────────────────┤
│ Layer 1: Video Detection (视频检测)                      │
│   URL → BBDown → 字幕存在性检测                         │
├─────────────────────────────────────────────────────────┤
│ Layer 2: Content Extraction (内容提取)                   │
│   有字幕 → 加载 SRT → 校对                               │
│   无字幕 → 下载音频 → ASR 转录 → 校对                    │
├─────────────────────────────────────────────────────────┤
│ Layer 3: Enhancement (增强处理)                          │
│   校对(ANTHROPIC_API_KEY) → 摘要(ANTHROPIC_API_KEY)     │
└─────────────────────────────────────────────────────────┘

Prerequisite Check

Must be run firstto verify the environment configuration:

pixi run python -m bilibili_subtitle --check

Output example:

✅ BBDown: Installed (1.6.3)
✅ BBDown Auth: Logged in
✅ ffmpeg: Installed
⚠️  ANTHROPIC_API_KEY: Not set (required for proofreading)
⚠️  DASHSCOPE_API_KEY: Not set (required for ASR)
✅ Python Dependencies: All installed

JSON format output (for easy parsing by parent skill):

pixi run python -m bilibili_subtitle --check --check-json

Error Tiers

Code	Level	Description	Fix Suggestion
E001	FATAL	BBDown not installed	`./install.sh`
E002	FATAL	BBDown not logged in	`BBDown login`
E003	RECOVERABLE	Download failed	Check URL/network
E004	RECOVERABLE	No subtitles	Automatically trigger ASR
E005	FATAL	ASR not configured	Set DASHSCOPE_API_KEY
E006	RECOVERABLE	AI features not configured	Use --skip-* or set the API Key
E007	FATAL	ffmpeg not installed	`pixi install`
E008	FATAL	Invalid URL	Provide the correct BV/URL
E010	FATAL	Video does not exist	Check whether the video has been deleted/private

Exit Codes：

0 - Success
1 - Fatal error (FATAL)
2 - Recoverable error (RECOVERABLE, partially completed)
3 - Partial success (with warnings)

Invocation Contract as a Sub-Skill

Standard Invocation

pixi run python -m bilibili_subtitle "<URL>" \
  -o /tmp/bilibili_output \
  --skip-summary \
  --json-output

Success Criteria

Exit code is 0 or 2
Output directory contains *.transcript.md

JSON Output Structure

{
  "exit_code": 0,
  "success": true,
  "output": {
    "video_id": "BV1xxx",
    "title": "视频标题",
    "files": {
      "transcript": "/path/to/xxx.transcript.md",
      "srt": "/path/to/xxx.srt",
      "vtt": "/path/to/xxx.vtt",
      "summary_json": null
    }
  },
  "warnings": [],
  "errors": []
}

Parent Skill Integration Example

from bilibili_subtitle import build_cli_command, ExitCode

cmd = build_cli_command(
    "BV1xxx",
    output_dir="/tmp/output",
    skip_proofread=True,
    skip_summary=True,
)
# ['pixi', 'run', 'python', '-m', 'bilibili_subtitle', 'BV1xxx', ...]

Output Files

output/
├── {title}.srt          # SRT 字幕
├── {title}.vtt          # VTT 字幕
├── {title}.transcript.md   # Markdown 逐字稿
├── {title}.summary.json    # 结构化摘要 (可选)
└── {title}.summary.md      # 摘要 Markdown (可选)

API Keys

Key	Provider	Purpose	Requirement
`ANTHROPIC_API_KEY`	Anthropic	Proofreading/Summarization	Recommended
`DASHSCOPE_API_KEY`	Alibaba Cloud	ASR transcription	Required when there are no subtitles

Installation

cd ~/.agents/skills/bilibili-subtitle
./install.sh
BBDown login  # 扫码登录

Detailed Documentation

references/preflight.md - Pre-check details
references/errors.md - Error handling guide
references/contract.md - Sub-skill contract
references/agents.md - AI Agent configuration

Version: v0.2.0