# Bilibili Downloader
[](https://badge.fury.io/py/bilibili-downloader)
[](https://pypi.org/project/bilibili-downloader/)
[](https://github.com/twwch/bilibili-downloader/blob/main/LICENSE)
[](https://github.com/twwch/bilibili-downloader/actions/workflows/ci.yml)
[](https://pepy.tech/project/bilibili-downloader)
一个简单易用的B站视频下载Python库，支持下载视频和音频。
## 特性
- 支持下载B站视频（包括音视频合并）
- 支持仅下载音频并转换格式（mp3, wav, m4a）
- 支持分P视频下载
- 自动处理短链接跳转
- 支持设置最大下载时长限制
- 异步下载，提高效率
- 清晰的错误处理
## 安装
```bash
# 安装依赖
pip install aiohttp httpx requests ffmpy3
```
注意：还需要安装FFmpeg并确保在系统PATH中可用。
## 快速开始
### 基础用法
```python
from bilibili_downloader import BilibiliDownloader
# 创建下载器实例
downloader = BilibiliDownloader()
# 下载音频
result = downloader.download_audio("https://www.bilibili.com/video/BV1xx411c7mD")
if result.success:
print(f"下载成功: {result.file_path}")
else:
print(f"下载失败: {result.message}")
# 下载视频
result = downloader.download_video("https://www.bilibili.com/video/BV1xx411c7mD")
if result.success:
print(f"下载成功: {result.file_path}")
```
### 高级配置
```python
# 使用认证信息（可选，用于下载高清视频）
downloader = BilibiliDownloader(
sessdata="your_sessdata",
bili_jct="your_bili_jct",
buvid3="your_buvid3",
download_dir="./my_downloads",
ffmpeg_path="/usr/local/bin/ffmpeg",
max_duration=7200 # 最大2小时
)
# 指定输出路径和格式
result = downloader.download_audio(
"https://www.bilibili.com/video/BV1xx411c7mD",
output_path="./output/audio.mp3",
audio_format="mp3"
)
# 获取视频信息
video_info = downloader.get_video_info("https://www.bilibili.com/video/BV1xx411c7mD")
print(f"标题: {video_info.title}")
print(f"时长: {video_info.duration}秒")
# 检查视频时长
ok, msg, duration = downloader.check_duration("https://www.bilibili.com/video/BV1xx411c7mD")
if ok:
print(f"视频时长: {duration}秒")
else:
print(f"错误: {msg}")
```
### 异步使用
```python
import asyncio
async def download_multiple():
downloader = BilibiliDownloader()
urls = [
"https://www.bilibili.com/video/BV1xx411c7mD",
"https://www.bilibili.com/video/BV1yy4y1k7VD",
]
tasks = [downloader.download_audio_async(url) for url in urls]
results = await asyncio.gather(*tasks)
for result in results:
if result.success:
print(f"下载成功: {result.file_path}")
else:
print(f"下载失败: {result.message}")
# 运行异步下载
asyncio.run(download_multiple())
```
## API 参考
### BilibiliDownloader
#### 初始化参数
- `sessdata` (str): B站Cookie中的SESSDATA，用于认证
- `bili_jct` (str): B站Cookie中的bili_jct
- `buvid3` (str): B站Cookie中的buvid3
- `download_dir` (str): 下载目录，默认"./downloads"
- `ffmpeg_path` (str): FFmpeg路径，不指定则自动查找
- `max_duration` (int): 最大允许下载时长（秒），默认10800（3小时）
#### 方法
- `get_video_info(url: str) -> VideoInfo`: 获取视频信息
- `download_audio(url: str, output_path: str = None, audio_format: str = "mp3") -> DownloadResult`: 下载音频
- `download_video(url: str, output_path: str = None, video_format: str = "mp4") -> DownloadResult`: 下载视频
- `check_duration(url: str) -> Tuple[bool, str, int]`: 检查视频时长
### 数据模型
#### VideoInfo
- `bvid`: 视频BV号
- `title`: 视频标题
- `duration`: 视频时长（秒）
- `video_url`: 视频流URL
- `audio_url`: 音频流URL
- `page`: 分P号
#### DownloadResult
- `success`: 是否成功
- `message`: 结果消息
- `file_path`: 下载文件路径
- `duration`: 视频时长
- `video_info`: 视频信息对象
## 异常处理
SDK定义了以下异常类：
- `BilibiliDownloadError`: 基础异常类
- `VideoNotFoundError`: 视频未找到
- `DurationExceededError`: 视频时长超出限制
- `NetworkError`: 网络请求失败
- `FFmpegError`: FFmpeg处理失败
```python
from bilibili_downloader import BilibiliDownloader, VideoNotFoundError, DurationExceededError
downloader = BilibiliDownloader(max_duration=3600) # 1小时限制
try:
result = downloader.download_audio("https://www.bilibili.com/video/BV1xx411c7mD")
except VideoNotFoundError:
print("视频不存在")
except DurationExceededError:
print("视频时长超过限制")
except Exception as e:
print(f"下载失败: {e}")
```
## 注意事项
1. 需要安装FFmpeg才能正常使用
2. 下载高清视频可能需要提供Cookie认证信息
3. 请遵守B站的使用条款，合理使用下载功能
4. 默认限制最大下载时长为3小时，可通过参数调整
## License
MIT
Raw data
{
"_id": null,
"home_page": "https://github.com/twwch/bilibili-downloader",
"name": "bilibili-downloader",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "bilibili, video, download, audio, api",
"author": "chenhao",
"author_email": "chenhao <twch97780@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/a8/97/a0f67c6790ebefdf4bf02207ab91deef05bca218fe82221ba33b1f6a17cd/bilibili_downloader-0.0.3.tar.gz",
"platform": null,
"description": "# Bilibili Downloader\n\n[](https://badge.fury.io/py/bilibili-downloader)\n[](https://pypi.org/project/bilibili-downloader/)\n[](https://github.com/twwch/bilibili-downloader/blob/main/LICENSE)\n[](https://github.com/twwch/bilibili-downloader/actions/workflows/ci.yml)\n[](https://pepy.tech/project/bilibili-downloader)\n\n\u4e00\u4e2a\u7b80\u5355\u6613\u7528\u7684B\u7ad9\u89c6\u9891\u4e0b\u8f7dPython\u5e93\uff0c\u652f\u6301\u4e0b\u8f7d\u89c6\u9891\u548c\u97f3\u9891\u3002\n\n## \u7279\u6027\n\n- \u652f\u6301\u4e0b\u8f7dB\u7ad9\u89c6\u9891\uff08\u5305\u62ec\u97f3\u89c6\u9891\u5408\u5e76\uff09\n- \u652f\u6301\u4ec5\u4e0b\u8f7d\u97f3\u9891\u5e76\u8f6c\u6362\u683c\u5f0f\uff08mp3, wav, m4a\uff09\n- \u652f\u6301\u5206P\u89c6\u9891\u4e0b\u8f7d\n- \u81ea\u52a8\u5904\u7406\u77ed\u94fe\u63a5\u8df3\u8f6c\n- \u652f\u6301\u8bbe\u7f6e\u6700\u5927\u4e0b\u8f7d\u65f6\u957f\u9650\u5236\n- \u5f02\u6b65\u4e0b\u8f7d\uff0c\u63d0\u9ad8\u6548\u7387\n- \u6e05\u6670\u7684\u9519\u8bef\u5904\u7406\n\n## \u5b89\u88c5\n\n```bash\n# \u5b89\u88c5\u4f9d\u8d56\npip install aiohttp httpx requests ffmpy3\n```\n\n\u6ce8\u610f\uff1a\u8fd8\u9700\u8981\u5b89\u88c5FFmpeg\u5e76\u786e\u4fdd\u5728\u7cfb\u7edfPATH\u4e2d\u53ef\u7528\u3002\n\n## \u5feb\u901f\u5f00\u59cb\n\n### \u57fa\u7840\u7528\u6cd5\n\n```python\nfrom bilibili_downloader import BilibiliDownloader\n\n# \u521b\u5efa\u4e0b\u8f7d\u5668\u5b9e\u4f8b\ndownloader = BilibiliDownloader()\n\n# \u4e0b\u8f7d\u97f3\u9891\nresult = downloader.download_audio(\"https://www.bilibili.com/video/BV1xx411c7mD\")\nif result.success:\n print(f\"\u4e0b\u8f7d\u6210\u529f: {result.file_path}\")\nelse:\n print(f\"\u4e0b\u8f7d\u5931\u8d25: {result.message}\")\n\n# \u4e0b\u8f7d\u89c6\u9891\nresult = downloader.download_video(\"https://www.bilibili.com/video/BV1xx411c7mD\")\nif result.success:\n print(f\"\u4e0b\u8f7d\u6210\u529f: {result.file_path}\")\n```\n\n### \u9ad8\u7ea7\u914d\u7f6e\n\n```python\n# \u4f7f\u7528\u8ba4\u8bc1\u4fe1\u606f\uff08\u53ef\u9009\uff0c\u7528\u4e8e\u4e0b\u8f7d\u9ad8\u6e05\u89c6\u9891\uff09\ndownloader = BilibiliDownloader(\n sessdata=\"your_sessdata\",\n bili_jct=\"your_bili_jct\",\n buvid3=\"your_buvid3\",\n download_dir=\"./my_downloads\",\n ffmpeg_path=\"/usr/local/bin/ffmpeg\",\n max_duration=7200 # \u6700\u59272\u5c0f\u65f6\n)\n\n# \u6307\u5b9a\u8f93\u51fa\u8def\u5f84\u548c\u683c\u5f0f\nresult = downloader.download_audio(\n \"https://www.bilibili.com/video/BV1xx411c7mD\",\n output_path=\"./output/audio.mp3\",\n audio_format=\"mp3\"\n)\n\n# \u83b7\u53d6\u89c6\u9891\u4fe1\u606f\nvideo_info = downloader.get_video_info(\"https://www.bilibili.com/video/BV1xx411c7mD\")\nprint(f\"\u6807\u9898: {video_info.title}\")\nprint(f\"\u65f6\u957f: {video_info.duration}\u79d2\")\n\n# \u68c0\u67e5\u89c6\u9891\u65f6\u957f\nok, msg, duration = downloader.check_duration(\"https://www.bilibili.com/video/BV1xx411c7mD\")\nif ok:\n print(f\"\u89c6\u9891\u65f6\u957f: {duration}\u79d2\")\nelse:\n print(f\"\u9519\u8bef: {msg}\")\n```\n\n### \u5f02\u6b65\u4f7f\u7528\n\n```python\nimport asyncio\n\nasync def download_multiple():\n downloader = BilibiliDownloader()\n \n urls = [\n \"https://www.bilibili.com/video/BV1xx411c7mD\",\n \"https://www.bilibili.com/video/BV1yy4y1k7VD\",\n ]\n \n tasks = [downloader.download_audio_async(url) for url in urls]\n results = await asyncio.gather(*tasks)\n \n for result in results:\n if result.success:\n print(f\"\u4e0b\u8f7d\u6210\u529f: {result.file_path}\")\n else:\n print(f\"\u4e0b\u8f7d\u5931\u8d25: {result.message}\")\n\n# \u8fd0\u884c\u5f02\u6b65\u4e0b\u8f7d\nasyncio.run(download_multiple())\n```\n\n## API \u53c2\u8003\n\n### BilibiliDownloader\n\n#### \u521d\u59cb\u5316\u53c2\u6570\n\n- `sessdata` (str): B\u7ad9Cookie\u4e2d\u7684SESSDATA\uff0c\u7528\u4e8e\u8ba4\u8bc1\n- `bili_jct` (str): B\u7ad9Cookie\u4e2d\u7684bili_jct\n- `buvid3` (str): B\u7ad9Cookie\u4e2d\u7684buvid3\n- `download_dir` (str): \u4e0b\u8f7d\u76ee\u5f55\uff0c\u9ed8\u8ba4\"./downloads\"\n- `ffmpeg_path` (str): FFmpeg\u8def\u5f84\uff0c\u4e0d\u6307\u5b9a\u5219\u81ea\u52a8\u67e5\u627e\n- `max_duration` (int): \u6700\u5927\u5141\u8bb8\u4e0b\u8f7d\u65f6\u957f\uff08\u79d2\uff09\uff0c\u9ed8\u8ba410800\uff083\u5c0f\u65f6\uff09\n\n#### \u65b9\u6cd5\n\n- `get_video_info(url: str) -> VideoInfo`: \u83b7\u53d6\u89c6\u9891\u4fe1\u606f\n- `download_audio(url: str, output_path: str = None, audio_format: str = \"mp3\") -> DownloadResult`: \u4e0b\u8f7d\u97f3\u9891\n- `download_video(url: str, output_path: str = None, video_format: str = \"mp4\") -> DownloadResult`: \u4e0b\u8f7d\u89c6\u9891\n- `check_duration(url: str) -> Tuple[bool, str, int]`: \u68c0\u67e5\u89c6\u9891\u65f6\u957f\n\n### \u6570\u636e\u6a21\u578b\n\n#### VideoInfo\n- `bvid`: \u89c6\u9891BV\u53f7\n- `title`: \u89c6\u9891\u6807\u9898\n- `duration`: \u89c6\u9891\u65f6\u957f\uff08\u79d2\uff09\n- `video_url`: \u89c6\u9891\u6d41URL\n- `audio_url`: \u97f3\u9891\u6d41URL\n- `page`: \u5206P\u53f7\n\n#### DownloadResult\n- `success`: \u662f\u5426\u6210\u529f\n- `message`: \u7ed3\u679c\u6d88\u606f\n- `file_path`: \u4e0b\u8f7d\u6587\u4ef6\u8def\u5f84\n- `duration`: \u89c6\u9891\u65f6\u957f\n- `video_info`: \u89c6\u9891\u4fe1\u606f\u5bf9\u8c61\n\n## \u5f02\u5e38\u5904\u7406\n\nSDK\u5b9a\u4e49\u4e86\u4ee5\u4e0b\u5f02\u5e38\u7c7b\uff1a\n\n- `BilibiliDownloadError`: \u57fa\u7840\u5f02\u5e38\u7c7b\n- `VideoNotFoundError`: \u89c6\u9891\u672a\u627e\u5230\n- `DurationExceededError`: \u89c6\u9891\u65f6\u957f\u8d85\u51fa\u9650\u5236\n- `NetworkError`: \u7f51\u7edc\u8bf7\u6c42\u5931\u8d25\n- `FFmpegError`: FFmpeg\u5904\u7406\u5931\u8d25\n\n```python\nfrom bilibili_downloader import BilibiliDownloader, VideoNotFoundError, DurationExceededError\n\ndownloader = BilibiliDownloader(max_duration=3600) # 1\u5c0f\u65f6\u9650\u5236\n\ntry:\n result = downloader.download_audio(\"https://www.bilibili.com/video/BV1xx411c7mD\")\nexcept VideoNotFoundError:\n print(\"\u89c6\u9891\u4e0d\u5b58\u5728\")\nexcept DurationExceededError:\n print(\"\u89c6\u9891\u65f6\u957f\u8d85\u8fc7\u9650\u5236\")\nexcept Exception as e:\n print(f\"\u4e0b\u8f7d\u5931\u8d25: {e}\")\n```\n\n## \u6ce8\u610f\u4e8b\u9879\n\n1. \u9700\u8981\u5b89\u88c5FFmpeg\u624d\u80fd\u6b63\u5e38\u4f7f\u7528\n2. \u4e0b\u8f7d\u9ad8\u6e05\u89c6\u9891\u53ef\u80fd\u9700\u8981\u63d0\u4f9bCookie\u8ba4\u8bc1\u4fe1\u606f\n3. \u8bf7\u9075\u5b88B\u7ad9\u7684\u4f7f\u7528\u6761\u6b3e\uff0c\u5408\u7406\u4f7f\u7528\u4e0b\u8f7d\u529f\u80fd\n4. \u9ed8\u8ba4\u9650\u5236\u6700\u5927\u4e0b\u8f7d\u65f6\u957f\u4e3a3\u5c0f\u65f6\uff0c\u53ef\u901a\u8fc7\u53c2\u6570\u8c03\u6574\n\n## License\n\nMIT\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "\u4e00\u4e2a\u7b80\u5355\u6613\u7528\u7684B\u7ad9\u89c6\u9891\u4e0b\u8f7dPython\u5e93",
"version": "0.0.3",
"project_urls": {
"Bug Tracker": "https://github.com/twwch/bilibili-downloader/issues",
"Documentation": "https://github.com/twwch/bilibili-downloader#readme",
"Homepage": "https://github.com/twwch/bilibili-downloader",
"Repository": "https://github.com/twwch/bilibili-downloader.git"
},
"split_keywords": [
"bilibili",
" video",
" download",
" audio",
" api"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a20523ba89a7bcc7b7e774057fb6727e3edc8c01421ae644da526d2bc15138cf",
"md5": "59e125d8b7842d28c9ac3a31a98851e8",
"sha256": "5a0414cce04c941e3766ffd41f5beee41f30d340acf624a3a9f2df06a2254add"
},
"downloads": -1,
"filename": "bilibili_downloader-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "59e125d8b7842d28c9ac3a31a98851e8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 10508,
"upload_time": "2025-07-26T00:14:15",
"upload_time_iso_8601": "2025-07-26T00:14:15.623839Z",
"url": "https://files.pythonhosted.org/packages/a2/05/23ba89a7bcc7b7e774057fb6727e3edc8c01421ae644da526d2bc15138cf/bilibili_downloader-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a897a0f67c6790ebefdf4bf02207ab91deef05bca218fe82221ba33b1f6a17cd",
"md5": "032353d0f9e35b8af0b1cf63aa13e3ce",
"sha256": "2ab6da70fae34a49e2010c93015b1ab10c83c75967c972fec4c73405b923b9f4"
},
"downloads": -1,
"filename": "bilibili_downloader-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "032353d0f9e35b8af0b1cf63aa13e3ce",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 21891,
"upload_time": "2025-07-26T00:14:16",
"upload_time_iso_8601": "2025-07-26T00:14:16.609067Z",
"url": "https://files.pythonhosted.org/packages/a8/97/a0f67c6790ebefdf4bf02207ab91deef05bca218fe82221ba33b1f6a17cd/bilibili_downloader-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-26 00:14:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "twwch",
"github_project": "bilibili-downloader",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "aiohttp",
"specs": [
[
">=",
"3.8.0"
]
]
},
{
"name": "httpx",
"specs": [
[
">=",
"0.24.0"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.25.0"
]
]
},
{
"name": "ffmpy3",
"specs": [
[
">=",
"0.2.4"
]
]
}
],
"lcname": "bilibili-downloader"
}
JSON
