N_m3u8DL-RE · 流媒体下载：加密下载与直播录制的完整实战指南

N_m3u8DL-RE · 流媒体下载：加密下载与直播录制的完整实战指南

【免费下载链接】N_m3u8DL-RECross-Platform, modern and powerful stream downloader for MPD/M3U8/ISM. English/简体中文/繁體中文.项目地址: https://gitcode.com/GitHub_Trending/nm3/N_m3u8DL-RE

N_m3u8DL-RE 是一款跨平台的流媒体下载工具，统一支持 MPD（DASH）、M3U8（HLS）、ISM（MSS）三种协议，覆盖点播和直播两种场景。它帮你把一条流媒体链接直接变成本地可播放的视频文件——解析、选轨、解密、合并、混流全部由一条命令行完成，不用再在浏览器、下载器和 ffmpeg 之间来回倒腾。

一、先搞清楚：这个项目能帮你解决什么

拿到链接却下不下来：用普通下载工具打开 m3u8/mpd 链接，得到的只是一份播放列表文本，不是视频。手动拆列表、逐个抓分片，遇到加密流基本无从下手。本工具自动解析播放列表，并发拉取分片并合并成完整文件。

加密内容解密麻烦：下下来的文件打开全是雪花，提示缺少解密密钥。老办法是找第三方解密程序、手动查密钥再逐文件处理。你只需通过--key传入密钥，程序自动调度解密流程。

直播录制总中断：直播录几小时就断流、丢片段，得盯着屏幕手动重开。专属直播引擎会定时刷新直播列表、续传新分片，可长时间无人值守运行。

二、快速上手：从零到跑通第一条命令

源码编译只需两步：

# 克隆源码 git clone https://gitcode.com/GitHub_Trending/nm3/N_m3u8DL-RE cd N_m3u8DL-RE # 编译发布版（需先安装 .NET 10 SDK） dotnet build -c Release

安装完成后，用 TestStreams.md 里提供的公开测试流跑通第一条命令：

# 下载一个公开测试 DASH 流，验证基本功能 N_m3u8DL-RE "http://media.axprod.net/TestVectors/v7-Clear/Manifest_1080p.mpd"

成功标志：终端先列出解析出的视频/音频/字幕轨道，然后是带实时速度的分片下载进度条，结束后打印合并文件路径，并在同目录生成一份解析信息的.json文件（--write-meta-json默认开启）。用播放器能打开该文件，说明链路完全跑通。完整参数列表见 README.md。

注意：这个项目没有 JSON 配置文件，所有设置都通过命令行参数完成，另有极少数RE_前缀的环境变量用于细节控制（见第五章）。

三、核心能力拆解

3.1 流选择与轨道匹配——精准挑出你要的视频、音频和字幕

快速体验

# 自动选择所有类型的最佳轨道 N_m3u8DL-RE "https://example.com/stream.m3u8" --auto-select

深入用法

# 按分辨率、语言、名称正则筛选轨道 N_m3u8DL-RE "https://example.com/stream.mpd" \ -sv res=1080p:for=best \ # 选最佳 1080p 视频轨 -sa lang="zh|chi":for=best \ # 选最佳中文音轨（兼容两种语言标签） -ss name="中文":for=all # 取所有名称含"中文"的字幕轨

容易踩的坑

• ❌-sv res=720（正则会部分匹配，可能选中宽为 720 的横屏流） ✅-sv res="1280*720"（写完整"宽*高"，用*通配更稳）
• ❌-sa all（把解说、多声道等全部音轨都拉下来） ✅-sa lang=en:for=best -da name="commentary"（选最佳英语轨并剔除解说轨）

为什么错：-sv/-sa是正则筛选器，for参数决定取哪一条（best/best2/all），写得越模糊，拉回来的内容越多。

原理一句话

流里的每条轨道都带有分辨率、语言、编码器等元数据标签，选择参数就是用正则去匹配这些标签，选出你指定的那几条去下载。

检查要点

• 先用--skip-download跑一遍，只解析不下载，确认目标轨道存在
• 查看终端"已选择轨道"列表，核对分辨率与语言
• 语法拿不准时执行N_m3u8DL-RE --morehelp select-video查看官方示例

3.2 加密流解密——把 AES/CHACHA20 保护的内容变成能播的文件

快速体验

# 已知 KID 时直接传密钥（KID 和 KEY 均为十六进制） N_m3u8DL-RE "https://example.com/encrypted.m3u8" --key "KID:KEY"

深入用法

# 多密钥场景：密钥文件 + 指定解密引擎 N_m3u8DL-RE "https://example.com/stream.mpd" \ --key-text-file "keys.txt" \ # 每行一个 KID:KEY 对，程序按 KID 检索 --decryption-engine MP4DECRYPT \ # 可选 FFMPEG / MP4DECRYPT / SHAKA_PACKAGER --mp4-real-time-decryption # 边下边解 MP4 分片，适合长直播

容易踩的坑

• ❌--key "abc123"（明文随手写的短密钥） ✅--key "9eb4050de44b4802932e27d75083e266:166634c675823c235a4a9446fad52e4d"（KID:KEY 成对出现，均为 32 位十六进制）
• ❌ 播放列表里没有声明密钥时，只传--key然后报错 ✅ 用--custom-hls-method AES_128 --custom-hls-key KEY_HEX手动指定加密方式与密钥

为什么错：密钥必须与加密方式匹配，且多个密钥时要保证 KID 与 KEY 正确对应，解密引擎只是执行者，给错密钥它无解。解密相关实现见 src/N_m3u8DL-RE/Crypto/。

原理一句话

下载器负责把密文分片拉回来，真正的解密交给 mp4decrypt、ffmpeg 或 shaka-packager 这类外部程序，本项目管的是密钥管理、引擎选择和分片调度。

检查要点

• 核对 KID 与 KEY 都是十六进制字符串且长度正确
• 解密失败时用--del-after-done false保留临时分片，检查文件内容
• 默认引擎失败时切换--decryption-engine逐个尝试

3.3 直播录制——长时间直播不断流、不漏片段

快速体验

# 录制直播并限制时长（格式 HH:mm:ss，录满 2 小时自动停止） N_m3u8DL-RE "https://example.com/live.m3u8" --live-record-limit 2:00:00

深入用法

# 手动控制列表刷新间隔，并开启实时管道混流 N_m3u8DL-RE "https://example.com/live.mpd" \ --live-record-limit 6:00:00 \ # 录满 6 小时停止 --live-wait-time 30 \ # 每 30 秒刷新一次直播列表 --live-pipe-mux # 通过管道 + ffmpeg 实时混流为 TS

容易踩的坑

• ❌ 网络波动时开启--live-pipe-mux✅ 网络不稳时只录分片，录完后再合并
• ❌ 想把直播一次性下完，却一直在等直播自然结束 ✅--live-perform-as-vod以点播方式下载直播流

为什么错：管道混流时数据读取由 ffmpeg 负责，网络抖动容易丢直播数据；而点播模式会把当前直播缓冲当作品点播内容处理，不必等结束。直播录制逻辑位于 src/N_m3u8DL-RE/DownloadManager/。

注意：官方明确提示，网络环境不够稳定时不要开启--live-pipe-mux。

原理一句话

程序按固定间隔反复请求直播播放列表，只下载新出现的分片，再按需实时或事后合并，所以可以脱离人工值守长时间运行。

检查要点

• 录制中用ffprobe看输出文件时长是否在持续增长
• 日志中确认没有大面积重连错误
• 长时间录制前确认磁盘剩余空间（分片默认会保留在本地）

3.4 网络调优——在限速、防盗链、弱网环境下保住速度和成功率

快速体验

# 提高并发线程数并限速（-R 单位为 Mbps 或 Kbps） N_m3u8DL-RE "https://example.com/stream.m3u8" --thread-count 16 -R 50M

深入用法

# 伪装浏览器请求 + 走代理 + 加重试 N_m3u8DL-RE "https://example.com/stream.m3u8" \ -H "User-Agent: Mozilla/5.0" \ # 伪装 UA，规避 403 -H "Referer: https://example.com" \ # 防盗链站点需要来源页 --custom-proxy "http://127.0.0.1:7890" \# 自定义代理 --download-retry-count 5 # 单分片异常时重试 5 次

容易踩的坑

• ❌--thread-count 64（并发拉满，触发服务端限流反而更慢） ✅--thread-count 16（CPU 核心数 2-4 倍，够用即可）
• ❌ 站点要求 Cookie 时裸请求，反复 403 ✅-H "Cookie: session=xxx" -H "User-Agent: ..."补齐请求头

为什么错：每个分片独立下载、独立重试，线程数决定并发度，但服务端对并发有限额，超出后会被限速甚至拒连。

原理一句话

分片之间天然互不依赖，多线程各下各的；某个分片失败只重试它自己，不会拖累其他分片。

检查要点

• 观察终端实时速度是否稳定，波动大就降低线程数
• 403 时优先检查 UA、Referer、Cookie 是否齐全
• 弱网环境调大--download-retry-count和--http-request-timeout

3.5 混流与字幕——把分离的音视频装进一个文件

快速体验

# 下载完成后自动把分离的音视频混流为 mp4 N_m3u8DL-RE "https://example.com/stream.mpd" -M format=mp4

深入用法

# 指定 mkvmerge 混流为 mkv，并引入一条外部中文轨 N_m3u8DL-RE "https://example.com/stream.mpd" \ -M format=mkv:muxer=mkvmerge \ # 容器格式 + 混流程序 --sub-format SRT \ # 字幕输出格式（SRT/VTT） --mux-import path="zh.srt":lang=chi:name="中文 (简体)" # 外部字幕合入文件

容易踩的坑

• ❌ 内容含 HEVC 或特殊字幕时混进 mp4，部分设备打不开 ✅ 改用-M format=mkv，mkv 容器几乎兼容所有编码
• ❌ 混流后找不到外部音轨 ✅--mux-import时补上lang=语言代码，播放器才能正确识别

为什么错：mp4 容器对编码格式和字幕类型有兼容限制，mkv 则基本来者不拒。

原理一句话

音视频先分开下载解密，最后由 ffmpeg 或 mkvmerge 把已解好的数据"装壳"进新容器，不重新编码，所以快且无画质损失。

检查要点

• ffprobe确认最终文件同时含视频轨和音轨
• 字幕轨语言标签与内容一致
• 混流失败时检查 ffmpeg 是否在 PATH 中，或用--ffmpeg-binary-path指定全路径

四、实战场景：从需求到执行

场景一：备份多音轨多字幕的公开课

场景：你有一门 DASH 协议的网课，含多语言音轨和字幕，想保留最佳画质视频 + 中文音轨 + 全部中文字幕。

# 选最佳 1080p 视频 + 中文音轨 + 所有中文字幕 N_m3u8DL-RE "https://edu.example.com/course.mpd" \ -sv res=1080p:for=best \ -sa lang="zh|chi":for=best \ -ss name="中文":for=all \ --save-name "AI基础课" \ --save-dir "./Courses"

验证：ffprobe ./Courses/AI基础课.*，确认视频轨分辨率为 1920x1080，音轨语言为中文，字幕轨存在。

场景二：8 小时会议直播录制

场景：一场 8 小时的学术会议直播，需要全程录制、无人值守、事后能排查问题。

# 直播录制 8 小时，30 秒刷新一次列表 N_m3u8DL-RE "https://conference.example.com/live.mpd" \ --live-record-limit 8:00:00 \ --live-wait-time 30 \ --log-file-path "./conference.log" \ --save-name "AI_Conference"

验证：结束后检查conference.log无大面积重连错误；ffprobe显示文件时长接近 8 小时。

场景三：批量下载系列纪录片

场景：一个 12 集的系列，编号规则统一，需要全部入库并自动重命名。

#!/bin/bash # 批量下载 12 集纪录片并混流为 mp4 BASE_URL="https://docu.example.com/series" for i in $(seq 1 12); do N_m3u8DL-RE "${BASE_URL}/ep${i}.m3u8" \ --save-name "自然奇观_EP$(printf '%02d' $i)" \ -M format=mp4 \ --save-dir "./Documentaries" \ --del-after-done true \ --log-level info done

验证：ls ./Documentaries应出现 12 个输出目录；逐个ffprobe抽查片头片尾是否完整。

场景四：只取长视频的某一段

场景：一段两小时的视频，你只需要第 5 到第 20 分钟做素材剪辑。

# 按时间范围只下载对应分片 N_m3u8DL-RE "https://news.example.com/vod.m3u8" \ --custom-range 05:00-20:00 \ --save-name "News_Clip"

验证：ffprobe显示时长约 15 分钟，且首尾画面与源片 5 分钟、20 分钟处吻合。

五、效率进阶与性能调优

跨平台差异

性能参数对比

持久化配置：本项目没有 JSON 配置文件，常用做法是把高频参数固化成 shell 别名和环境变量：

# 写入 ~/.bashrc 或 ~/.zshrc 长期生效 alias dl='N_m3u8DL-RE --thread-count 12 --log-level info' # 常用参数打包 export RE_LIVE_PIPE_TMP_DIR=/tmp/re_pipe # 非 Windows 下管道文件生成目录 export RE_LIVE_PIPE_OPTIONS="" # 自定义 live-pipe-mux 时的 ffmpeg 参数

配套工具链

• ffmpeg：混流、合并、解码都靠它调用，必装
• mp4decrypt：CENC 解密的默认引擎，由程序自动寻找
• MKVToolNix（mkvmerge）：混流为 mkv 时的替代混流程序
• ffprobe：验收工具，一条命令核对轨道数、分辨率、时长
• yt-dlp / Streamlink：从网页里提取出 m3u8/mpd 链接，再交给本工具下载

小贴士：线程数不是越高越好。服务端通常对单 IP 并发有限额，遇到"加线程反而变慢"时，正确做法是降线程 + 调大--download-retry-count，而不是继续加并发。

六、常见问题速查

Q：下下来的文件打不开或画面花屏？A：大概率是加密流没给密钥。用--key "KID:KEY"传密钥，多密钥用--key-text-file指向文件；播放列表里没声明密钥时，用--custom-hls-method+--custom-hls-key手动指定加密方式和密钥。

Q：下载速度上不去怎么办？A：先加--thread-count（16-32）试并发；仍慢说明是服务端限速，改降线程并用-R限速稳住速度，同时调大--download-retry-count。另外确认--use-system-proxy/--custom-proxy没有让流量绕远路。

Q：解密失败了，密钥和引擎怎么选？A：默认引擎是 MP4DECRYPT，适配大多数 CENC 内容；失败就依次换--decryption-engine FFMPEG、SHAKA_PACKAGER。前提是密钥格式正确、加密方式匹配（--custom-hls-method支持 AES_128、CHACHA20、SAMPLE_AES 等）。

Q：任务中断后，缺的分片怎么补？A：分片是独立下载的，用--custom-range指定缺失的编号区间（如10-）或时间区间（如05:00-20:00）重新下载即可，不用整片重下。

Q：临时文件占满磁盘了？A：临时分片默认放在系统临时目录，可用--tmp-dir换到空间大的盘；任务完成后默认删除（--del-after-done true）。要留现场排查问题时传--del-after-done false。

Q：混流成 mp4 后部分设备播不了？A：mp4 容器对编码和字幕类型有限制，换-M format=mkv基本都能解决；也检查一下内容是否用了 HEVC/AV1 这类设备兼容性较差的编码。

七、术语速查

【免费下载链接】N_m3u8DL-RECross-Platform, modern and powerful stream downloader for MPD/M3U8/ISM. English/简体中文/繁體中文.项目地址: https://gitcode.com/GitHub_Trending/nm3/N_m3u8DL-RE