N_m3u8DL-RE 流媒体下载实操：从零跑通 DASH/HLS/MSS 完整教程

N_m3u8DL-RE 流媒体下载实操：从零跑通 DASH/HLS/MSS 完整教程

【免费下载链接】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 是跨平台流媒体下载工具，支持 DASH、HLS、MSS 三种协议，覆盖点播与直播，也能处理加密流与直播录制。本文面向会用终端的用户，从零跑通一次真实下载，并覆盖选画质、解密、部分下载、命名规则等高频需求。

🚀 跑通第一次下载：安装、运行、验证

1. 安装并检查依赖。Arch Linux 及其衍生版直接装：

yay -Syu n-m3u8dl-re-bin

其他系统克隆 https://gitcode.com/GitHub_Trending/nm3/N_m3u8DL-RE 后用 .NET 10 SDK 编译。程序启动时会预检查 ffmpeg，先确认它已安装且在 PATH 中，再用自带 doctor 命令自检环境：

N_m3u8DL-RE doctor

2. 跑第一条命令。这条 DASH 样例来自项目测试流清单（多音轨多字幕），程序自动识别协议并进入交互式选流界面：

N_m3u8DL-RE "https://media.axprod.net/TestVectors/v7-Clear/Manifest_1080p.mpd"

不指定--save-dir时，结果文件输出到当前工作目录。

3. 验证产物。任务结束后检查目录：

ls -lh

应看到合并后的视频文件和 meta.json（记录全部流信息，--write-meta-json默认开启；--no-log可关闭日志文件输出）。

📋 能力速查：什么需求配什么参数

能解决什么	关键参数	一句话说明
选择画质/音频/字幕轨	-sv -sa -ss	按分辨率、编码、语言等正则条件筛选轨道
解密 CENC/AES 加密流	--key --decryption-engine	下载后交给 mp4decrypt 或 ffmpeg 解密
录制直播流	--live-real-time-merge --live-record-limit	边下边追新分片，可实时合并并限制时长
只下部分内容	--custom-range	按分片序号或时间区间截取点播内容
下载后混流	-M format=mp4	分离的音视频自动合成 mp4/mkv 单文件
命名与目录管理	--save-dir --save-pattern	模板变量避免文件名互相覆盖

🎯 高频场景实战

选择最高画质

想干什么：多画质流里只下最高分辨率的那条视频轨。

N_m3u8DL-RE "https://dash.akamaized.net/dash264/TestCases/2c/qualcomm/1/MultiResMPEG2.mpd" -sv best --save-dir ~/Videos --save-name MultiRes

• 起作用的是-sv best：把所有视频轨按带宽排序取最高的一条；--save-name让输出文件名可预期。
• 若只要 4K HEVC 轨，就换成-sv res="3840*":codecs=hvc1:for=best，用正则把候选缩小到 4K HEVC 轨，避免误选同分辨率的其他编码。
• 完整筛选语法（语言、帧率、声道、码率等）看N_m3u8DL-RE --morehelp select-video。

加密流下载完整步骤：密钥怎么填

想干什么：下载加密 DASH 流，下载完成后自动解密。

N_m3u8DL-RE "https://media.axprod.net/TestVectors/v7-MultiDRM-SingleKey/Manifest_1080p_ClearKey.mpd" --key 9eb4050de44b4802932e27d75083e266:166634c675823c235a4a9446fad52e4d -sv best

• 起作用的是--key：采用 KID:KEY 形式，程序下载完分片后把密钥交给解密程序处理。
• 默认解密引擎是 MP4DECRYPT，需要本机装有 mp4decrypt；若本机只有 ffmpeg，用--decryption-engine FFMPEG切换。
• 注意：所有轨道共用同一把 KEY 时直接写--key KEY即可，无需 KID；密钥来自文件时用--key-text-file。

录制直播并限制时长

想干什么：把一路直播录 10 分钟，分片录制中实时合并。

N_m3u8DL-RE "https://cmafref.akamaized.net/cmaf/live-ull/2006350/akambr/out.mpd" --live-real-time-merge --live-record-limit 00:10:00 --save-name LiveDemo

• 程序检测到所选流是直播后自动进入录制模式，持续追取新分片，直到 Ctrl+C 停止。
• --live-real-time-merge让分片在录制中实时合并进最终文件，省去事后合并；--live-record-limit 00:10:00把录制锁在 10 分钟内，防止文件无限增长。
• ⚠️ README 明确提醒：网络环境不够稳定时不要开启--live-pipe-mux，管道内数据读取由 ffmpeg 负责，某些环境下容易丢失直播数据。
• 若想补看过去的节目，换成--live-catchup "01:00:00"配合--live-record-limit，从一小时前开始下载（README「直播回看」一节）。

只下载部分内容

想干什么：先下几个分片验证链路，再决定是否下全量。

N_m3u8DL-RE "https://dash.akamaized.net/dash264/TestCases/2c/qualcomm/1/MultiResMPEG2.mpd" -sv best --custom-range 0-10

• 起作用的是--custom-range 0-10：只下载序号 0 到 10 共 11 个分片。
• 其他写法：10-从第 10 个分片开始往后下，-99取前 100 个分片，05:00-20:00按时间截取（按分片起始时间筛选，保留完整分片，不精确裁切）。
• 注意：该参数仅对点播生效，直播不适用。

命名与输出目录管理

想干什么：一次下视频加多条音轨，各文件互不覆盖、落进指定目录。

N_m3u8DL-RE "https://media.axprod.net/TestVectors/v7-Clear/Manifest_1080p.mpd" -sv best -sa all --save-dir ~/Videos --save-name Demo --save-pattern "<SaveName>_<MediaType>_<Language>"

• --save-dir和--save-name决定文件落在哪、基础名是什么；--save-pattern用变量展开文件名，-sa all下全部音轨时各文件互不覆盖。
• 模板还支持<Resolution>、<Bandwidth>、<Codecs>等变量，区分大小写，详见--morehelp save-pattern。
• 注意：过长的保存名和模板生成的文件名会自动缩短并附加短哈希以减少重名（README 命令行参数一节）。

🩺 慢、挂、播不了怎么办

三个核心调优参数，统一用法：

• --thread-count：改的是并发下载分片的线程数，默认 10。带宽没跑满而服务器支持并发时调到 20（默认值的 2 倍）；服务器限流或网络拥堵时反而调低。
• --http-request-timeout：改的是单次 HTTP 请求超时（秒），默认 100。分片大、网速慢、超时频繁时调到 180，给单请求更多时间；调低只会让失败更快出现。
• --download-retry-count：改的是单个分片下载异常后的重试次数，默认 7。弱网下偶发 4xx/5xx 导致任务中断时调到 10，降低失败概率；设太高会让已失效的分片白白多等。

现象	可能原因	处理办法
启动即报找不到 ffmpeg	系统未安装 ffmpeg 或不在 PATH	安装 ffmpeg，或用--ffmpeg-binary-path指定全路径
加密流下载完成但无法播放	未提供密钥，或 KID:KEY 对应错误	核对密钥来源后用--key KID:KEY重下，或改用--key-text-file
旧版 Windows 终端启动崩溃或乱码	系统终端不支持本程序	换用 cmder 等现代终端运行（README 建议）
直播录制出现数据丢失	弱网下开启了--live-pipe-mux	关闭 pipe-mux，仅用--live-real-time-merge
实际分片数少于预期，任务报错	部分分片请求失败且重试不够	调大--download-retry-count后重跑，核对--check-segments-count结果

🧭 代码导览：各模块职责

• src/N_m3u8DL-RE/Program.cs 主入口：做 ffmpeg、解密工具等预检查，完成流选择后按协议与直播属性分发到不同管理器。
• src/N_m3u8DL-RE/CommandLine/ 命令行参数定义与解析，包括 -sv、--custom-range 等复合参数语法。
• src/N_m3u8DL-RE/DownloadManager/ 任务编排：SimpleDownloadManager 负责点播，SimpleLiveRecordManager2 与 HTTPLiveRecordManager 负责直播录制。
• src/N_m3u8DL-RE/Downloader/ 单个分片的下载与合并执行。
• src/N_m3u8DL-RE/Processor/ URL、Key、Content 三类处理器的扩展点，二次开发可按站点插入自定义逻辑。
• src/N_m3u8DL-RE.Parser/Extractor/ DASH、HLS、MSS 的流提取器实现；src/N_m3u8DL-RE.Parser/Mp4/ 处理 MP4 box 解析与字幕提取。
• src/N_m3u8DL-RE.Common/ 公共实体（Playlist、MediaSegment、StreamSpec）、HTTP 工具与日志。
• src/N_m3u8DL-RE.Tests/ 单元测试与测试资源，用例可直接参考。

📌 下一步

N_m3u8DL-RE 把流媒体下载的主链路拆得职责清晰，真实场景大多靠参数组合即可覆盖。

1. 运行N_m3u8DL-RE --morehelp select-video，通读轨道筛选的完整语法。
2. 按 TestStreams.md 里的 DASH/HLS/MSS 测试流各跑一遍，确认本机环境正常。
3. 批量任务把--save-pattern与--save-dir固化成脚本模板，或写入~/.config/N_m3u8DL-RE/config.conf配置文件复用。

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