简介：面向B站用户打造的一款自动化视频下载与处理工具，基于Python语言并整合yt-dlp、ffmpeg两大开源库，能够以AV号、BV号或直接URL为入口，实现视频批量下载、高清解析、弹幕抽取及多格式转换。资源定位清晰，适用于视频学习、素材整理、弹幕数据分析等场景，对熟悉Python或希望自动化处理B站视频的用户尤其友好。压缩包共7个文件，体积仅40KB，包含Python核心脚本、txt与md说明文档、docx附加说明以及License、.gitignore等配置，脚本负责下载与处理流程，文档辅助环境搭建和参数配置，轻量且结构清晰。已有326人浏览学习，说明该工具有一定实用价值。通过该包可获得可直接运行的下载脚本、弹幕获取与转码思路、完整使用说明以及附赠文档，帮助读者快速搭建自己的B站视频自动下载管线。
1. B站视频下载，从yt-dlp命令行到Python自动化
拿着一个AV号或BV号，想把一个视频连封面带弹幕一起存到本地，B站官方客户端不给你这个选项，网页端嗅探又经常拿到一堆分片文件。这正是yt-dlp这类下载器存在的意义：它把B站的播放地址解析、音视频流分离、格式封装这些脏活全部包好，你只需要告诉它“下载哪个视频、要什么画质、存成什么格式”。加上ffmpeg做后处理，B站视频的下载和处理就能变成一条稳定、可重复的流水线。
这篇文章要讲的是我在处理B站视频时总结的一套方法：用Python封装yt-dlp的调用，批量解析BV号和AV号，拉取弹幕，同时解决多P视频、字幕、封面和高画质格式这些落地问题。标题里提到的“多格式支持”和“高清视频解析”，在实际操作中主要落在yt-dlp的格式选择参数和ffmpeg的封装命令上。适合谁看？想批量备份B站视频的UP主投稿、想把弹幕和视频一起存档的收藏爱好者，以及要给团队做内部视频抓取工具而没有现成方案的开发者。
2. 为什么选yt-dlp而不是B站API直连：解析逻辑和选型理由
2.1 B站视频地址的解析链路：从BV号到CDN分片
B站网页端的播放地址不是写死的，你打开一个视频页面，浏览器先在后台请求一个接口，拿到当前清晰度对应的视频流地址和音频流地址，然后再用播放器拉流。早期B站允许直接拿到完整的mp4文件，现在高清视频基本拆成了视频轨和音频轨两路流，下载后需要合并，这一步是ffmpeg介入的第一个理由。
yt-dlp这类下载器做的事情，就是把“请求页面 -> 解析接口 -> 拿流地址 -> 下载音视频 -> 封装合并”整条链路自动化。它内部有专门的B站提取器，能够识别BV号、AV号、URL链接，也可以从用户主页或收藏夹批量展开。这个提取逻辑不是我需要重写的，直接用就好。真正需要自己动手的，是处理播放列表、选择清晰度、给文件命名，以及把弹幕从XML或protobuf转成我们能看的格式。
这里有一个常见的误区：有人觉得B站API直连更可控，非要自己去调接口拿数据。真实情况是B站的接口有风控逻辑，请求频率一高就可能触发验证，而yt-dlp积累了很长时间的适配逻辑，踩坑的概率远小于自己从零开始。我一般只在需要拿“视频标题、UP主信息”这类元数据时才单独请求接口，下载本体始终交给yt-dlp。
2.2 安装yt-dlp和ffmpeg：版本搭配和二进制路径
先说环境。yt-dlp是纯Python项目，支持Python 3.8以上版本，但B站的高画质格式解析依赖较新的yt-dlp版本，所以安装时不要用系统自带的旧包，直接用pip升级到最新版本即可。ffmpeg则需要单独下载可执行文件，Windows下解压后将bin目录加入系统PATH，Linux直接用包管理器安装。
# 在Python虚拟环境中安装yt-dlp python3 -m venv bili_env && source bili_env/bin/activate pip install -U yt-dlp # 检查yt-dlp版本，确保能够解析B站最新格式 yt-dlp --version # Linux下安装ffmpeg apt install -y ffmpeg # 验证ffmpeg可用 ffmpeg -version这段命令里，虚拟环境是第一步，和系统Python隔离的好处是不会把依赖装乱。yt-dlp升级很频繁，有的版本只活一两个月就因为B站改接口而失效，所以我的习惯是在每次批处理前先执行一遍pip install -U yt-dlp，确保用的是最新支持代码。
另外注意ffmpeg是独立于yt-dlp的进程，yt-dlp在下载完成后会去PATH里找ffmpeg来合并音视频流。如果找不到，它会自动退化为只下载单独的视频流，低画质还好，高清视频就会得到一个只有画面没有声音的文件，这是新手最容易翻车的地方。我一般会在脚本里加上路径检测，避免这种问题。
2.3 Python调用yt-dlp的最小闭包：模拟浏览器请求和Cookie配置
B站对未登录用户开放的是480P清晰度，高清视频需要登录账号才能解析，这一点在yt-dlp的命令行里体现为需要给下载器传入登录凭据。处理思路有两种：一是用yt-dlp的--cookies-from-browser参数直接读取本地浏览器的登录态，二是把Cookie保存为Netscape格式后传给脚本。第一种方便但依赖浏览器，第二种适合放到服务器上跑。
import yt_dlp ydl_opts = { 'format': 'bv*+ba/b', 'merge_output_format': 'mp4', 'outtmpl': '%(title)s.%(ext)s', 'cookiesfrombrowser': 'chrome', # 读取Chrome浏览器中的B站登录态 'quiet': False, } url = 'https://www.bilibili.com/video/BV1xx411c7mD' with yt_dlp.YoutubeDL(ydl_opts) as ydl: info = ydl.extract_info(url, download=True)这段代码是一个最小闭包，不需要维护登录状态就能下载高清视频，前提是电脑里装了Chrome并且登录过B站。format: 'bv*+ba/b'是yt-dlp的格式选择语法，bv*表示最好的视频流，ba表示最好的音频流，中间的+代表合并，最后面的/b表示如果分离流失败则退化为单一格式。参数outtmpl控制输出文件的命名模板，B站返回的标题有时会包含特殊字符，做好转义能避免Windows下的命名报错。
3. 批量下载B站视频：BV号与AV号的统一入口和任务队列
3.1 用URL批量输入代替手工拼接：从收藏夹到文本文件的转换
批量下载场景一般有这么几种：把某个UP主的主页全部视频拉下来、把某个收藏夹的视频存到本地、给一个包含几十个BV号的文本文件批量解析。这三种场景中，第一种和第二种yt-dlp都已经支持从URL直接展开，你只需要把主页地址或收藏夹地址传进去。第三种需要我们自己写一个读取文件、循环下载的脚本。
“支持AV号BV号URL多种”这个需求点，实际上y-dlp内部已经做了归一化，它可以把AV号转换成BV号，也可以接受带参数跳转的短链接。我的做法是写一个通用的任务解析函数，把各种输入形式统一成标准URL列表，再交给下载队列处理。
import re def parse_bilibili_input(text): """把用户输入统一转换成可下载的URL列表""" text = text.strip() # 支持直接粘贴完整URL if text.startswith('https://www.bilibili.com/video/'): return [text] # 支持BV号，补全URL bv_match = re.search(r'BV[0-9A-Za-z]+', text) if bv_match: return [f'https://www.bilibili.com/video/{bv_match.group()}'] # 支持AV号，转成BV后补全 av_match = re.search(r'av([0-9]+)', text, re.IGNORECASE) if av_match: return [f'https://www.bilibili.com/video/av{av_match.group(1)}'] raise ValueError(f'无法识别的输入: {text}')这个函数的逻辑很简单但很实用：用户不管是从网页复制链接、手动输入BV号、还是拿一个旧的AV号粘贴进来，最后都能拿到一个可下载的标准URL。正则匹配中BV号的规则是固定的字母数字组合，需要注意大小写都要支持。AV号转BV号这一步yt-dlp在内部会处理，不需要我们自己去查转换表。
3.2 多P视频的展开：分P选择和批量命名规则
B站视频分为单P和多P，多P视频在URL里显示的是一整个合集，但实际视频流是分成多个片段。yt-dlp默认会把多P全部下载下来，文件的命名规则需要专门设计，不然就会出现下载完一堆文件却看不出顺序的问题。
我一般会在outtmpl里加入集数占位符，例如%(playlist_index)02d_%(title)s.%(ext)s，这样文件名会带上01_、02_这样的序号前缀。这里有第二个坑：B站多P视频的标题往往到P数和P标题为止，不包含UP主的名字，所以如果同时下载多个UP主的视频，建议在文件命名时加入频道信息%(channel)s，避免重名覆盖。
ydl_opts = { 'format': 'bv*+ba/b', 'merge_output_format': 'mp4', 'outtmpl': '%(channel)s/%(playlist_title)s/%(playlist_index)02d_%(title)s.%(ext)s', 'noplaylist': False, }这里的noplaylist: False让yt-dlp保留展开播放列表的行为，也就是多P视频会全部下载。文件路径按频道/合集名/序号_标题的三级结构组织，对后续批量处理很友好。整个目录结构是在下载时自动创建的，不需要提前手动建文件夹。playlist_index是整数，02d格式化后在排序时不会出现第10集排在第二集前面的问题。
3.3 断点续传和失败重试：批量下载不中断的三个参数
批量下载最怕的是中途失败后重头再来，一个几十集的合集下载到第20集断掉确实很折磨人。yt-dlp本身就支持断点续传，它下载过程中会使用.part临时文件，重跑命令时会自动检测并继续未完成的部分。
针对失败请求，我习惯加三个参数：retries表示每个片段的请求重试次数，fragment_retries是分片下载的重试次数，continuedl确保断点续传开关打开。还有一个更隐蔽的concurrent_fragment_downloads，它可以控制分片并发数，值大小直接影响带宽占用和下载速度，默认1是串行，我一般设为4到8，B站对分片并发有一定的容忍空间。
ydl_opts = { 'format': 'bv*+ba/b', 'merge_output_format': 'mp4', 'retries': 10, # 请求失败后的重试次数 'fragment_retries': 10, # 分片下载失败的重试次数 'continuedl': True, # 断点续传 'concurrent_fragment_downloads': 4, # 分片并发数 'ignoreerrors': True, # 单集下载失败时跳过，不中断整个队列 }ignoreerrors: True是批量下载的生命线配置：某些视频因版权限制或UP主删除导致无法解析，如果没有这个参数，整个脚本会抛异常终止，后面所有的视频都不下载了。有了它，失败的条目只会打印一条警告，任务队列继续往前走，全部结束后我再回头处理失败列表。代价是会掩盖部分真实网络问题，所以我一般会在脚本结尾打印失败计数，保证至少知道它发生了什么。
4. 弹幕获取与多格式支持：从XML到ass字幕的处理链路
4.1 B站弹幕的三种获取途径和yt-dlp的弹幕参数
B站的弹幕文件有两种主流格式：XML格式可以直接解析出弹幕内容和发送时间，另一种是protobuf格式，需要额外的解码库。yt-dlp自带弹幕下载选项，官方文档里支持的选项有--write-subs和--write-auto-subs，这些命令配合格式化参数使用能够下载B站的外挂字幕。但弹幕的真实情况是：yt-dlp目前对B站弹幕的支持还不够完整，它有时候能拿到CC字幕，但获取所有弹幕需要单独调用B站接口。
我常用的方案是：视频下载完成后，单独请求B站的弹幕接口拉取XML文件，再解析需要的部分。B站弹幕接口需要视频的cid参数，这个值在yt-dlp返回的视频信息字典里可以拿到。
import requests import re def fetch_danmaku_by_cid(cid): """根据视频cid获取XML弹幕文件""" url = f'https://comment.bilibili.com/{cid}.xml' headers = { 'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36', 'Referer': 'https://www.bilibili.com/' } resp = requests.get(url, headers=headers, timeout=10) if resp.status_code != 200: raise RuntimeError(f'弹幕获取失败，HTTP {resp.status_code}') return resp.content这里的关键是cid和视频ID之间的对应关系。在yt-dlp提取信息后，信息字典中有cid字段，它是弹幕接口真正需要的参数。如果直接用BV号去请求弹幕，B站会返回参数错误。headers里的Referer必须保留，这个接口需要校验请求来源，否则部分部署会返回403。
4.2 弹幕转ASS：把滚动弹幕压进视频的ffmpeg滤镜思路
如果只是把弹幕存成XML文件，很多播放器并不直接支持，想在看视频的时候看到弹幕，常见的做法是转换成ASS字幕格式，再用ffmpeg把ASS字幕烧录进视频画面。我做弹幕转换时用现成的方案，把XML的标准字段映射成ASS的Dialogue行，时间轴从毫秒转成ASS时间格式，同时把弹幕类型映射成不同样式。
def xml_time_to_ass(raw_time): """将XML弹幕的时间戳转成ASS字幕格式的时间""" seconds = int(raw_time) / 1000 hours = int(seconds // 3600) minutes = int((seconds % 3600) // 60) secs = int(seconds % 60) centsecs = int((seconds - int(seconds)) * 100) return f'{hours:02d}:{minutes:02d}:{secs:02d}.{centsecs:02d}'时间戳转换逻辑是整个链路里最容易出错的地方。B站弹幕XML的p属性里第一项是弹幕出现的毫秒时间，直接除以1000就能得到秒数；转成ASS格式时要注意毫秒位是两位的厘秒制，直接保留三位会出问题。转换后，用ffmpeg的ass滤镜烧录到视频里，可以得到带弹幕的成品文件：
ffmpeg -i input.mp4 -vf "ass=danmaku.ass" -c:v libx264 -c:a aac output.mp4这个命令属于视频后处理环节，通常在全部下载完成后统一执行。-vf ass=danmaku.ass滤镜会把字幕直接渲染到画面上，输出的是硬字幕，播放设备不需要额外安装字库。缺点是烧录过程无法撤销，所以我在批量执行前会先在单个视频上做预览。
4.3 多格式支持：为什么mp4不是唯一答案
标题里提到“多格式支持”，实际落地时有几层含义：一是下载时音视频流的封装格式可控，二是输出容器的可选性。B站原视频流的容器有mp4、webm等，yt-dlp的merge_output_format参数可以强制输出指定的容器，默认是mkv，因为mkv同时容纳多种编码的音视频流。但很多用户拿到mp4后更容易直接导入手机和剪辑软件，所以我会改成mp4。
这里有一个比较隐蔽的坑：mp4容器要求视频流必须是H264或者H265编码，音频流必须是AAC。如果B站返回的视频流是AV1编码，合并成mp4时ffmpeg会直接报错，或者输出一个播放器不认的文件。我一般会加上--recode-video mp4参数，yt-dlp会用ffmpeg重新转码，确保输出兼容性。
ydl_opts = { 'format': 'bv*+ba/b', 'merge_output_format': 'mp4', # 不允许转码，只重新封装 'recode_video': None, }recode_video: None的含义是“如果容器和编码匹配，直接直播拷贝不转码”，速度快，画质零损伤。但前提是得保证原始流编码和容器匹配。如果遇到容器匹配失败的情况，再把recode_video改成mp4让ffmpeg做一次完整转码，代价是cpu占用和画质衰减。我一般在下载参数里把format限定为bv*[vcodec^=avc]+ba[acodec^=aac]，先把不兼容的编码过滤掉，再考虑容器问题。
5. 高清视频解析：从480P到4K的格式选择和清晰度锁定
5.1 B站清晰度等级与yt-dlp格式标识的对应关系
B站对视频清晰度的定义和yt-dlp的格式标识不是直接对应的，这一点容易让人困惑。B站页面上标注的360P、480P、720P、1080P、4K等选项，在yt-dlp解析出来的formats列表里体现为不同的分辨率、视频编码和带宽组合。同一个分辨率可能对应多个视频流，视频编码可能是AVC也可能是HEVC，它们的格式ID都不同。
搞清楚清晰度等级和格式ID的对应关系，需要查看视频的具体格式列表：
import yt_dlp from pprint import pprint with yt_dlp.YoutubeDL({'quiet': True}) as ydl: info = ydl.extract_info( 'https://www.bilibili.com/video/BV1xx411c7mD', download=False ) for fmt in info['formats']: print(fmt.get('format_id'), fmt.get('height'), fmt.get('vcodec'), fmt.get('acodec'), fmt.get('tbr'))这段代码只打印不下，执行结果中第一列是yt-dlp内部的格式ID（如30032、30280等），第二列是高度，后面是视频编码和音频编码。B站4K视频往往会有多个不同编码的流，AVC编码兼容性最好但不是所有的4K视频都有AVC版本，有时只有HEVC或AV1。这时如果强求mp4容器，就得接受转码开销。
5.2 用format参数锁定最高清晰度：格式选择语法的优先级问题
我见过很多人的format参数写成bestvideo+bestaudio，这个写法在多数网站没问题，但在B站可能会出现选到一个AV1视频流的情况，AV1视频流的播放对CPU要求高，而且封装兼容性差。针对B站的实际情况，我推荐自己定义格式优先级：
format_spec = ( 'bv*[height<=2160][vcodec^=avc]+ba[acodec^=aac]/' 'bv*[height<=2160][vcodec^=hev1]+ba[acodec^=aac]/' 'bv*[height<=2160]+ba/b' )这个格式串的结构是三条优先级递减的规则，用斜杠隔开。第一条优先找不超过4K的AVC编码视频流，找不到就尝试HEVC编码，再找不到就允许任意编码。这样锁定的结果是：既有最高清晰度，又没有让编码格式成为后续封装的隐患。需要说明的是height<=2160中的2160是像素高度，4K视频通常满足这个条件；如果你只想下1080P，改成height<=1080即可。
5.3 高画质视频的下载速度和稳定性：分片并发和限速的平衡点
高清视频文件大，动辄几十个GB，下载稳定性和速度控制比清晰度选择更实际。B站的分片机制是把视频切成一个个几秒的小块，然后提示开发者自行下载并拼接。默认的并发数是1到2，高速网络下往往跑不满带宽，但并发过高又容易遇到B站限流或封IP。
ydl_opts = { 'format': format_spec, 'concurrent_fragment_downloads': 8, 'http_chunk_size': 10485760, # 10MB一个分片 'retries': 30, 'fragment_retries': 30, }http_chunk_size指定每个HTTP请求拉取的分片大小，默认值较小，请求次数多，频繁握手容易触发风控。调到10MB后请求次数减少，对稳定性的帮助很明显。retries和fragment_retries都设为30，在高清场景下是合理的，因为网络波动一次会毁掉好几个分片，重试不够的话会造成文件缺块坏掉。注意这两个参数的单位是“次”，不是“倍”，具体数值按网络情况来调整。
6. 批量下载全流程的避坑记录：从Cookie失效到弹幕时间来维权
踩坑一：Cookie失效导致的高清视频全部失效
现象：前一天还能下载1080P，第二天突然所有的视频都只能拿到480P甚至更低。排查原因后发现Cookie过期，cookiesfrombrowser虽然能读取浏览器登录态，但浏览器本身可能已经清除了B站的登录会话，或者该浏览器没有登录B站。
解决：在写脚本前先手动打开浏览器访问bilibili.com，确认登录状态是正常且保持有效的状态。批量下载数量巨大时，建议长期跑脚本用独立的Netscape格式Cookie文件，退出浏览器后Cookie文件依然有效，也能避免浏览器占用文件锁定导致读取失败。
踩坑二：弹幕时间戳错位，视频和弹幕对不上
现象：用XML转ASS后烧录到视频里，发现弹幕出现的时间比视频大概延迟了，或者在某些位置凭空出现提前量。原因多半是我用的时间基准和分析的视频起点不一致，B站存在以分段为单位的时间偏移量，视频有片头时弹幕时间轴从正片开始。
解决：弹幕转换脚本只处理正片区间，下载时用--download-sections截掉片头区间，或者在记录视频分段时把裁掉的偏移量手动补偿回弹幕时间轴里。加上一段偏移补偿逻辑就解决了，手动记录下来每一次的分段偏移。
踩坑三：文件名太长导致Windows路径报错
现象：某些B站视频标题特别长，加上频道名和编号后组合出的文件名超过Windows路径上限，脚本在文件创建阶段就抛异常。原因是outtmpl模板组合时没有做长度检查。
解决：在outtmpl里加一个%(title).50s之类的截断表达式，限制标题长度，同时把频道名作为目录层级来区分，而不是全拼进文件名。B站标题加频道名的组合模式在多级目录结构中出现截断问题，用截断表达式做限定后整个流程稳定很多。
踩坑四：视频有音无画或者有画无音
现象：下载完成后的mp4只有音频没有画面，或者用播放器打开黑屏只有声音。原因是在不同的时间点B站返回的视频轨编码不同，有时会返回AV1流，部分播放器和剪辑软件根本不支持AV1解码，导致画面播放异常。
解决：在下载参数里强制限定[vcodec^=avc]或[vcodec^=hev1]，把AV1过滤掉。如果确实需要AV1的高压缩率，那么用ffmpeg转成H264再封装，但要做好CPU占用升高的准备。
踩坑五：批量下载单集失败导致整个队列中断
现象：跑了20集，到第21集时视频因版权问题下载失败，整个脚本直接退出，后面30集都没留下记录。原因是批量脚本没有对单集异常做捕获，yt-dlp抛出的下载错误直接向上冒。
解决：在循环外包一层异常捕获，配合ignoreerrors: True确保单集失败只记日志，循环立刻进入下一集。我还会把每个视频的下载结果写进一个JSON文件，跑完后能看到哪些成功哪些失败，失败的原因是什么，不需要靠人眼去翻终端日志。
7. 进阶用法：把整套流程封装成一个可复用的Python下载器类
到这一步，前面的功能已经能解决B站个人用户日常下载需求了，但真正把工具变成可持续落地的方案，需要把它封装成一个可复用的类，不然每次换一批视频就要改一遍脚本。我在实际项目中使用的做法是定义一个BilibiliDownloader类，把任务解析、下载器初始化、弹幕获取、异常处理全部收纳进去。
import yt_dlp import requests from pathlib import Path class BilibiliDownloader: def __init__(self, output_dir='downloads'): self.output_dir = Path(output_dir) self.output_dir.mkdir(parents=True, exist_ok=True) self.base_opts = { 'format': 'bv*[height<=2160][vcodec^=avc]+ba[acodec^=aac]/b', 'merge_output_format': 'mp4', 'outtmpl': str(self.output_dir / '%(channel)s' / '%(title)s.%(ext)s'), 'ignoreerrors': True, 'retries': 10, 'fragment_retries': 10, } def download(self, url_or_ids): urls = self._normalize_input(url_or_ids) with yt_dlp.YoutubeDL(self.base_opts) as ydl: return ydl.download(urls) def _normalize_input(self, raw_input): # 支持用逗号或换行分隔多个BV号 text = raw_input.replace(',', '\n').replace('，', '\n') lines = [ln.strip() for ln in text.splitlines() if ln.strip()] return [self._to_url(ln) for ln in lines]这个封装解决了我日常最大的痛点“输入格式混乱”和“下载参数不统一”。调用时不管是传一个URL还是一个文本块，内部都会先归一化成URL列表再交给yt-dlp，输出目录自动创建，单集失败自动跳过。类封装的价值在于把配置集中到一个字典里，参数一改，所有调用都同步更新，不需要每次新建脚本再复制粘贴那一段参数。
验证这个工具是否可靠，我一般会跑三组测试：一组是单人单P视频，确认清晰度满足预期；一组是合集多P视频，确认文件命名和目录结构正确；最后一组混合故意失败的链接，确认ignoreerrors真的不会中断整个队列。测试通过后再跑大批量就不会有意外惊喜了。
这个方案目前在我的日常使用中稳定运行，遇到的绝大多数问题都能靠升级yt-dlp版本解决。在下一次的实践中，踩坑五的JSON日志记录已经加进了类的实现里，每次下载完看一份JSON就知道有没有漏网之鱼，不用再对着终端输出逐条去找。希望帮到你。
本文还有配套的精品资源，点击获取
