# bilibili-media-downloader

> 使用yt-dlp从B站下载音频和视频。**默认同时下载视频+音频**,支持--audio-only参数仅下载音频(向后兼容),支持--video-only只下载视频。支持多种音频格式(mp3/wav/m4a)和视频画质(1080P/720P/480P)。这是完整B站视频处理工作流的第一步,下载后可使用audio-to-subtitle生成字幕,subtitle-summarizer生成带截图的图文总结。

- Author: WangJie
- Repository: Andy-WJ/bilibili-media-ai
- Version: 20260201133847
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/Andy-WJ/bilibili-media-ai
- Web: https://mule.run/skillshub/@@Andy-WJ/bilibili-media-ai~bilibili-media-downloader:20260201133847

---

---
name: bilibili-media-downloader
description: 使用yt-dlp从B站下载音频和视频。**默认同时下载视频+音频**,支持--audio-only参数仅下载音频(向后兼容),支持--video-only只下载视频。支持多种音频格式(mp3/wav/m4a)和视频画质(1080P/720P/480P)。这是完整B站视频处理工作流的第一步,下载后可使用audio-to-subtitle生成字幕,subtitle-summarizer生成带截图的图文总结。
---

# B站媒体下载器

## ⚠️ 执行方式要求

**重要**: 执行脚本时必须使用**直接执行**方式,让脚本使用内置的shebang:

```bash
# ✓ 正确方式 - 直接执行脚本
./.claude/skills/bilibili-media-downloader/scripts/download_media.py "URL"

# ✗ 错误方式 - 不要用python解释器调用
python .claude/skills/bilibili-media-downloader/scripts/download_media.py "URL"
.venv/bin/python .claude/skills/bilibili-media-downloader/scripts/download_media.py "URL"
```

**原因**: 脚本的shebang已配置为使用项目虚拟环境中的Python解释器。直接执行会自动使用正确的Python和依赖包。

## 功能说明

这个skill使用yt-dlp从B站下载音频和视频文件,支持多种下载模式。

**核心优势**:
- 支持音频和视频下载
- 直接下载最佳质量,无需转换
- 支持多种音频格式和视频画质
- 自动选择最高可用画质

## ⚠️ 重要:工作目录

**默认输出位置**: `当前工作目录/output/`

**使用前确认**:
1. 确保在项目根目录下运行(包含`.claude`文件夹的目录)
2. 音频文件保存在: `{当前目录}/output/audio/`
3. 视频文件保存在: `{当前目录}/output/video/`

**检查当前目录**:
```bash
pwd  # 查看当前工作目录
ls .claude  # 确认当前目录包含.claude文件夹
```

## Python环境要求

**虚拟环境**: 项目使用uv管理的Python 3.10虚拟环境
- **位置**: `.venv/`
- **Python解释器**: `.venv/bin/python`
- **依赖包**: yt-dlp, ffmpeg-python等

## 使用方式

### 默认模式: 同时下载音频和视频

```bash
/bilibili-media-downloader "https://www.bilibili.com/video/BV1xx411c7mD"
```

输出:
- 音频: `{当前目录}/output/audio/视频标题.mp3`
- 视频: `{当前目录}/output/video/视频标题.mp4`

### 音频模式 (向后兼容)

```bash
/bilibili-media-downloader "https://www.bilibili.com/video/BV1xx411c7mD" --audio-only
```

输出: `{当前目录}/output/audio/视频标题.mp3`

### 仅下载视频

```bash
/bilibili-media-downloader "https://www.bilibili.com/video/BV1xx411c7mD" --video-only
```

输出: `{当前目录}/output/video/视频标题.mp4`

### 指定视频画质

```bash
# 下载1080P视频(默认)
/bilibili-media-downloader "BV1xx411c7mD" --quality 1080

# 下载720P视频
/bilibili-media-downloader "BV1xx411c7mD" --quality 720

# 下载480P视频
/bilibili-media-downloader "BV1xx411c7mD" --quality 480
```

### 指定音频格式

```bash
/bilibili-media-downloader "BV1xx411c7mD" --format wav
```

**注意**: 音频格式参数仅影响音频文件,视频始终为mp4格式

### 使用BV号

```bash
/bilibili-media-downloader "BV1xx411c7mD"
```

## 返回结果

### 下载音频+视频成功时(默认模式):
```json
{
  "success": true,
  "audio_path": "/path/to/audio.mp3",
  "video_path": "/path/to/video.mp4",
  "title": "视频标题",
  "duration": 180,
  "format": "mp3",
  "file_size": 5242880,
  "video_size": 104857600
}
```

### 仅下载音频成功时(--audio-only):
```json
{
  "success": true,
  "audio_path": "/path/to/audio.mp3",
  "title": "视频标题",
  "duration": 180,
  "format": "mp3",
  "file_size": 5242880
}
```

### 仅下载视频成功时(--video-only):
```json
{
  "success": true,
  "video_path": "/path/to/video.mp4",
  "title": "视频标题",
  "duration": 180,
  "video_size": 104857600
}
```

### 失败时:
```json
{
  "success": false,
  "error": "错误类型",
  "message": "详细错误信息",
  "suggestions": ["解决方案1", "解决方案2"]
}
```

## 支持的格式和画质

### 音频格式
- **mp3** (默认) - 最通用,兼容性好
- **wav** - 无损质量,文件较大
- **m4a** - AAC编码,高质量且文件小

### 视频画质
- **1080P** (默认) - 高清,≤1080P
- **720P** - 标清,≤720P
- **480P** - 流畅,≤480P

**说明**: 系统会自动选择指定画质及以下的最高可用画质。如果1080P不可用,会自动降级到720P。

## 常见错误处理

### 需要会员的视频
自动跳过,返回提示信息。

### 视频失效或删除
返回明确错误信息。

### 网络错误
自动重试,仍失败则返回错误。

## 完整工作流

### 完整视频工作流 (推荐)

```
/bilibili-media-downloader "BV1xxx"
  → /audio-to-subtitle "{audio_path}"
  → 请求: "请总结字幕并生成截图:
     字幕: {subtitle_path}
     视频: {video_path}"
```

**说明**: 默认模式自动下载视频+音频,然后直接总结字幕并调用video-screenshot截图

### 音频工作流 (向后兼容)

```
/bilibili-media-downloader "BV1xxx" --audio-only
  → /audio-to-subtitle "{audio_path}"
  → 请求: "请总结字幕: {subtitle_path}"
```

**说明**: 使用 `--audio-only` 仅下载音频,生成纯文本总结

## 相关Skills

- **audio-to-subtitle**: 将音频转为字幕
- **video-screenshot**: 快速提取视频截图(开始/中间/结束)
- **subtitle-summarizer**: 生成智能图文总结(支持自动截图)

## 下一步操作

### 下载完成后(默认模式)

**生成带截图的完整总结**:
```bash
/audio-to-subtitle "{audio_path}"
  → 请求: "请总结字幕并生成截图:
     字幕: {subtitle_path}
     视频: {video_path}"
```

**说明**: 直接读取字幕文件,生成总结并调用video-screenshot skill提取关键帧截图

### 仅下载模式

如果用户明确只想下载媒体文件(不处理后续步骤),可以在调用时说明,下载完成后不执行后续步骤。