m3u8视频下载工具m3u8_downloader实战手记：从解析HLS流到批量保存本地视频

【免费下载链接】m3u8_downloaderm3u8（HLS流）下载，实现了AES解密、合并、多线程、批量下载项目地址: https://gitcode.com/gh_mirrors/m3/m3u8_downloader

你有没有遇到过这种情况：一门在线课程的付费视频，网页上能正常播放，浏览器里却怎么也找不到"下载"按钮，右键另存为得到的只是一个几十KB的m3u8文件？我第一次碰到时也懵了——后来才搞明白，m3u8（HLS流）只是视频的"目录清单"，真正的画面被切成几百个小分片存在服务器上。今天这篇实战手记，就记录我如何用一个Python小工具 m3u8_downloader，把这种"看得见摸不着"的在线视频整整齐齐地搬回本地，顺带把 AES 解密、多线程加速、批量下载这些坑全部踩平。

一、先搞清楚对手：m3u8 到底是什么？

在动手写工具之前，我花了一下午研究 HLS 协议。简单来说，HLS（HTTP Live Streaming）是苹果提出的一套流媒体方案，它会把一段视频切成若干秒一个的 TS 分片文件，再用一个 m3u8 播放列表把这些分片的名字和顺序记下来。视频播放器拿到 m3u8 后，像按菜谱上菜一样，一个一个把分片拉下来拼起来播放。

所以想"下载整段视频"，本质要做四件事：

1. 把 m3u8 文件抓下来，解析出所有分片地址；
2. 看看视频有没有加密（通常加密方式是 AES-128），有的话要额外拿到密钥文件 key；
3. 用多线程把所有 TS 分片同时下载到本地；
4. 按顺序合并分片，再用 FFmpeg 封装成 MP4。

这四步听起来简单，自己手写却处处是坑。好在开源项目 m3u8_downloader 已经把这套流程封装好了，我要做的只是把它跑起来。

二、五分钟跑起来：环境准备与安装步骤

2.1 拉取项目源码

首先把项目克隆到本地，注意仓库地址是这个：

git clone https://gitcode.com/gh_mirrors/m3/m3u8_downloader cd m3u8_downloader

打开目录你会发现两样东西：主程序m3u8_downloader.py，以及lib/文件夹里自带的两个 FFmpeg 二进制文件（ffmpeg和ffmpeg.exe）。FFmpeg 是最后合并视频的"秘密武器"，项目已经替你打包好了，Windows 和 macOS 都能直接调用。

2.2 安装 Python 依赖

项目基于 Python 3，需要先装几个第三方库，一句话搞定：

pip install beautifulsoup4 m3u8 pycryptodome requests threadpool

这几个库的分工很明确：m3u8负责解析播放列表，pycryptodome负责 AES 解密，requests负责发 HTTP 请求，threadpool负责多线程调度。装完就可以准备素材了。

三、准备"购物清单"：批量下载输入文件怎么写

这个工具支持批量下载，核心思路是先在一个 UTF-8 编码的文本文件里列好"我要下哪些视频"。每一行的格式很直白，用|把视频名称和 m3u8 链接隔开：

Python教程完整版|https://example.com/python-course/index.m3u8 机器学习实战|https://example.com/ml-practice/index.m3u8 数据分析入门|https://example.com/data-analysis/index.m3u8

我给它起了个外号叫"购物清单"——你想存几个视频，就写几行，程序会挨个处理。文件名就是第一列的文字，所以起名时尽量避开/ \ : * ? " < > |这些 Windows 不允许出现在文件名里的字符，工具内部其实也会自动帮你替换掉。

四、动手改配置：五个参数决定下载行为

打开m3u8_downloader.py，文件顶部就是一块醒目的配置区。新手一定要先读懂这五行，它们决定了整个下载流程：

m3u8InputFilePath = "D:/input/m3u8_input.txt" saveRootDirPath = "D:/output" errorM3u8InfoDirPath = "D:/output/error.txt" m3u8TryCountConf = 10 processCountConf = 50

逐一说下我的理解：

• m3u8InputFilePath：刚才那份"购物清单"文件的路径，必须是 UTF-8 编码，否则中文名称会乱码；
• saveRootDirPath：最终 MP4 文件的保存目录，程序启动时如果发现不存在会自动创建；
• errorM3u8InfoDirPath：下载失败任务的"记黑账"文件，跑完检查这里就知道哪些视频没成功；
• m3u8TryCountConf：m3u8 清单和 key 密钥文件的下载重试次数，默认 10 次；
• processCountConf：并发线程数，也就是同时下载多少个分片，默认 50。

把这些路径改成你自己电脑上的实际路径，配置就算完成了。

五、正式开跑：看到进度条的那一刻

5.1 一定要在终端里运行

这里有个特别容易踩的坑：请直接在终端（命令行）里运行脚本，不要在 PyCharm 等 IDE 里执行，否则动态进度条会显示不出来。运行命令很简单：

python m3u8_downloader.py

程序启动后会先检查"购物清单"是否存在，然后逐条处理。每处理一个视频，终端会按步骤打印1、开始下载m3u8...、2、开始下载key...、3、开始下载ts...等提示。

5.2 实时进度条与网速监控

下载 TS 分片时是最好玩的：终端上会刷出一个动态进度条，显示已完成数/总分片数、百分比进度，以及实时的下载速度（自动按 B/s、KiB/s、MiB/s 切换单位）。看着一格格方块被填满，网速数字一路飙升，那种"坐等收货"的感觉特别解压。

5.3 遇到多级码流怎么办

很多视频网站的 m3u8 是"套娃"结构——主清单里不直接给分片，而是按清晰度列了几个子清单（比如超清、高清、标清）。程序检测到is_variant（多级码流）后，会自动寻找子 m3u8 链接并递归解析，直到拿到真正的分片列表，不需要你手动干预。

六、加密视频也能下：AES-128 解密原理速览

如果你要下的视频带防盗链加密，m3u8 清单里会声明METHOD=AES-128并指向一个 key 文件。工具的处理流程是：

1. 从 m3u8 解析出密钥地址，若地址是相对路径会自动拼上域名；
2. 下载 key 文件，重试上限就是前面配置的m3u8TryCountConf；
3. 用 pycryptodome 初始化 AES-CBC 解密器，如果清单里声明了 IV 向量就用 IV，没声明就用 key 本身当 IV；
4. 合并分片时边写边解密，最终输出正常可播放的视频。

关于 key 下载，程序还做了两件贴心小事：一是跟随重定向（有些服务器会 301 跳转拿真实地址），二是校验 Content-Length 与实际内容长度，防止拿到"半截"密钥。如果你发现提示"不支持的解密方式"，那说明视频用了 AES-128 以外的加密（比如 SAMPLE-AES 或更高级的 DRM 方案），这类就不在工具的能力范围内了。

七、提速与调优：把下载速度榨干

多线程是提速的核心，processCountConf就是调节的旋钮。根据我这几个月的使用经验，不同网络环境有不同建议：

需要提醒的是：线程数不是越大越好。设置过高容易被目标服务器判定为攻击而拒绝连接，导致大量分片反复重试，反而更慢。另外 TS 分片下载采用的是"无限重试直到成功"策略，单个分片失败会自己反复重连，所以偶尔闪断也不用慌。

存储方面也提个醒：下载过程中会产生大量临时分片和中间文件，建议目标盘预留视频体积 2 倍以上的空间，有条件的话用 SSD 存放缓存目录，写入速度会明显影响整体耗时。

八、失败自救指南：下载出错了怎么办

跑了几个视频之后，我总结出最常见的三种失败场景和对应解法：

场景一：提示 m3u8 或 key 下载失败多半是网络不通、链接失效或密钥地址无法访问。先用浏览器手动打开链接确认有效性，再检查代理和防火墙设置。

场景二：进度条卡住不动看是卡在单个分片反复重试，还是整体无速度。前者通常是被服务器限速或限并发，试着把线程数调低；后者检查网络是否断连。

场景三：合并/转换 MP4 失败确认lib/目录下的 FFmpeg 文件还在且具备执行权限，检查缓存分片是否完整。程序会在cache/log.log里写详细的运行日志，出问题先翻日志，基本能定位到是哪个分片在作妖。

另外，整个下载过程中断后重跑，已经下载好的分片会被重新下载（工具当前没有断点跳过机制），所以建议一次跑完，或者分批写"购物清单"。

九、写在最后：一点使用底线

工具本身完全本地运行，不会把你的下载记录上传到任何服务器，可以放心使用。但请务必只下载自己有合法访问权限的内容，比如自己购买的课程、官方开放的学习资源，把它用于个人学习与研究，不要拿去盗录传播。开源工具的价值在于学习与合规使用，这个底线别破。

如果你也想把在线视频稳稳抓在手里，现在就照着上面的步骤，去克隆仓库装好依赖，用自己手头一个合法的 m3u8 链接试一次。相信我，当终端里跳出那个 100% 进度条、本地多出一个能正常播放的 MP4 时，你会回来感谢自己的。

【免费下载链接】m3u8_downloaderm3u8（HLS流）下载，实现了AES解密、合并、多线程、批量下载项目地址: https://gitcode.com/gh_mirrors/m3/m3u8_downloader