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-REN_m3u8DL-RE 是一个跨平台的流媒体下载器专门处理 MPDDASH、M3U8HLS和 ISMMSS三种协议的点播与直播内容。它解决的核心痛点是这三种协议的描述文件、分片方式、加密手段各不相同多数下载脚本只覆盖其中一种而它把三类协议的解析、选轨、下载、解密、混流收敛进了同一个命令行。适合已经在用命令行工具处理媒体文件、需要稳定拿到多码率多音轨内容的技术用户。三步拿到第一次下载成功环境要求只有一个安装 .NET 10.0 SDK项目目标框架为net10.0。# 1. 获取源码 git clone https://gitcode.com/GitHub_Trending/nm3/N_m3u8DL-RE cd N_m3u8DL-RE # 2. 构建 Release 版本 dotnet build --configuration Release # 可执行文件位于 src/N_m3u8DL-RE/bin/Release/net10.0/ # 3. 一条最小可用命令URL 可换成 TestStreams.md 中的测试流 src/N_m3u8DL-RE/bin/Release/net10.0/N_m3u8DL-RE \ https://media.axprod.net/TestVectors/v7-Clear/Manifest_1080p.mpd \ --save-name test # 输出文件名前缀运行后程序会列出解析到的所有轨道并进入交互式选择界面方向键 空格勾选、回车确认即可。想跳过交互直接加--auto-select自动选最佳视频 每种语言的最佳音频 全部字幕。仓库自带的 TestStreams.md 列出了 15 个以上可用的测试流覆盖 DASH、HLS、MSS、加密、直播等场景调参数时可以逐个尝试不用自己找资源。核心能力食谱按场景取用以下每条对应一个真实使用场景直接复制改 URL 即可。选轨是全部操作的核心-sv/-sa/-ss接收正则表达式组合-dv/-da/-ds做反向排除# 场景只下载 4K HEVC 视频 最佳英语音轨 所有中文字幕 N_m3u8DL-RE stream.mpd \ -sv res3840*:codecshvc1:forbest \ -sa langen:forbest \ -ss name中文:forallforbest选最优一条forbest2选最优两条forall全选还可按id lang name frame segsMin plistDurMin等维度过滤如-sv plistDurMin1h20m30s:forbest只选时长超过 1 小时 20 分 30 秒的流。只取字幕 / 批量抓字幕# 只选字幕轨道输出为 SRT默认也可 --sub-format VTT N_m3u8DL-RE stream.m3u8 --sub-only -ss all --sub-format SRT点播内容只下载一部分--custom-range同时支持序号范围和真实时间范围# 下载前 100 个分片 N_m3u8DL-RE vod.mpd --custom-range -99 # 下载第 5 分钟到 20 分钟 N_m3u8DL-RE vod.mpd --custom-range 05:00-20:00 # 从序号 10 开始下载后续所有分片 N_m3u8DL-RE vod.mpd --custom-range 10-多轨道下载时的命名冲突用--save-pattern模板变量区分# 变量: SaveName Id Codecs Language Resolution Bandwidth # MediaType Channels FrameRate VideoRange GroupId Ext N_m3u8DL-RE multi_quality.mpd --save-name movie \ -sv all \ --save-pattern SaveName_Resolution_Bandwidthkbps # 输出: movie_1920x1080_5000000kbps.mp4 / movie_1280x720_2500000kbps.mp4认证与请求头-H可重复使用程序内置了一个 Chrome User-Agent 作为默认头自定义头会覆盖同名项N_m3u8DL-RE https://protected.example.com/manifest.m3u8 \ -H Authorization: Bearer your_token \ -H Referer: https://protected.example.com代理与限速# 走自定义代理默认使用系统代理--use-system-proxy 默认为 true N_m3u8DL-RE stream.mpd --custom-proxy http://127.0.0.1:8888 # 限速单位 Mbps 或 Kbps N_m3u8DL-RE stream.mpd -R 10M架构透视一条分片是怎么走到最终文件的先跟数据流走一遍再回头看目录结构。核心链路在 Program.cs 的DoWorkAsync中一目了然CLI 解析CommandInvoker基于 System.CommandLine把参数解析成MyOption对象并在此阶段预检 ffmpeg / mp4decrypt / mkvmerge / shaka-packager 是否可用缺依赖立即报错而不是下载一半才发现协议解析StreamExtractor加载源文件自动识别 DASH/HLS/MSS/HTTP-LIVE 类型调用对应的 Extractor 把描述文件转成统一的轨道列表StreamSpec轨道筛选FilterUtil依次应用排除过滤-dv系列、包含过滤-sv系列、自动选择或交互式选择再套用--custom-range和广告分片关键字--ad-keyword分片列表获取FetchPlayListAsync拉取各轨道的 Playlist此时会经过可插拔的 UrlProcessor/KeyProcessor 链见后文扩展节任务路由根据流类型分派三个 Manager 之一——点播走SimpleDownloadManagerDASH/HLS 直播走SimpleLiveRecordManager2裸 HTTP 直播流走HTTPLiveRecordManager并发下载SimpleDownloader按--thread-count线程池下载分片每个分片失败按--download-retry-count重试解密如需要CENC 加密的 MP4 调用外部解密引擎HLS 的 AES-128/ChaCha20 用内置的AESUtil/ChaCha20Util就地解密合并与混流分片合并成文件后若指定了-M调用 ffmpeg/mkvmerge 把音视频字幕合成最终容器对应的模块结构只保留与流程相关的部分src/ ├── N_m3u8DL-RE/ # 主程序层 │ ├── CommandLine/ # CLI 参数定义与解析 (MyOption/CommandInvoker) │ ├── DownloadManager/ # 任务路由与流程控制 (点播/直播三套 Manager) │ ├── Downloader/ # 分片下载实现 (SimpleDownloader) │ ├── Crypto/ # 内置 AES/ChaCha20 解密 │ ├── Processor/ # 内置 URL/内容处理器示例 (二次开发入口) │ └── Program.cs # 主流程编排 ├── N_m3u8DL-RE.Common/ # 公共层 │ ├── Entity/ # 统一数据模型 (StreamSpec/MediaSegment/Playlist) │ ├── Log/ # ANSI 彩色控制台日志 (Spectre.Console) │ └── Util/ # HTTP/重试/二进制校验等基础设施 └── N_m3u8DL-RE.Parser/ # 协议解析层 ├── Extractor/ # DASH/HLS/MSS/HTTP-LIVE 四种提取器 ├── Processor/ # Content/Key/Url 处理器链 (默认实现 挂载点) └── Mp4/ # MP4 box 级解析 (供实时解密/字幕处理使用)一个值得注意的设计取舍CENC 加密的 MP4 解密被外包给了第三方工具mp4decrypt / ffmpeg / shaka-packager 三选一而不是全部用 C# 实现。代价是依赖外部可执行文件换来的是与主流工具行为一致、少踩 CENC 各种 corner case 的坑而 HLS 的 AES-128 和 ChaCha20 则是内置纯 C# 实现因为这两种算法简单、无 box 结构依赖。进阶场景加密内容下载原理CENC 加密的 DASH/ISM 流按 KID密钥 ID索引密钥程序把密钥交给解密引擎逐分片解密。# 单密钥 / 多密钥 N_m3u8DL-RE encrypted.mpd --key KID1:KEY1 --key KID2:KEY2 # 密钥相同可直接给 KEY大列表用文件每行 KID:KEY N_m3u8DL-RE encrypted.mpd --key-text-file keys.txt # 切换解密引擎默认 MP4DECRYPT备选 FFMPEG / SHAKA_PACKAGER N_m3u8DL-RE encrypted.mpd --decryption-engine FFMPEG --key KEY注意事项程序会在启动时按所选引擎查找对应二进制mp4decrypt、ffmpeg、shaka-packager及各平台架构命名如packager-linux-x64找不到直接报FileNotFoundException可先用--decryption-binary-path/--ffmpeg-binary-path指定路径--mp4-real-time-decryption让程序在合并前逐分片实时解密 MP4减少一次完整临时文件的落盘适合磁盘紧张的大文件场景HLS 加密另有专用参数用于描述文件没写明或写错加密方式的情况--custom-hls-methodAES_128 / CENC / CHACHA20 / SAMPLE_AES 等、--custom-hls-key、--custom-hls-iv值支持文件路径、HEX 或 Base64。直播录制原理直播流没有总长度录制 Manager 循环刷新 Playlist把新出现的分片追加下载。# 基本录制限制时长 2 小时 N_m3u8DL-RE live.m3u8 --save-name live --live-record-limit 02:00:00 # 边录边合并--live-real-time-merge 实时合并已下载分片 # 管道混流--live-pipe-mux 通过管道ffmpeg 实时混流成 TS会强制开启实时合并 N_m3u8DL-RE live.m3u8 --live-pipe-mux注意事项--live-pipe-mux的管道内数据读取由 ffmpeg 负责官方 README 明确提示网络不稳定时不要开启容易丢直播数据--live-keep-segments默认为true实时合并时仍保留分片文件排障建议保持默认确认流程稳定后再考虑关闭省空间管道混流的 ffmpeg 参数可用环境变量RE_LIVE_PIPE_OPTIONS覆盖如-readrate 1 -re非 Windows 下管道文件目录可用RE_LIVE_PIPE_TMP_DIR指定字幕时间戳偏移可用--live-fix-vtt-by-audio按音频起始时间修正多轨道混流与外部媒体引入原理分离下载的视频、音频、字幕默认是独立文件-M即--mux-after-done在全部完成后调用混流程序合成一个容器。# 默认用 ffmpeg 混成 mp4 N_m3u8DL-RE stream.mpd -M formatmp4 # 换 mkvmerge 封装 MKV可自定义程序路径 N_m3u8DL-RE stream.mpd -M formatmkv:muxermkvmerge N_m3u8DL-RE stream.mpd -M formatmp4:muxerffmpeg:bin_pathC:\Tools\ffmpeg.exe # 混流后保留原始分轨文件 N_m3u8DL-RE stream.mpd -M formatmp4:keeptrue # 混流时引入外部字幕/音轨 N_m3u8DL-RE video.mpd \ --mux-import pathchinese.srt:langchi:name中文(简体) \ --mux-import pathenglish_audio.m4a:langeng:nameEnglish Audio注意事项开启-M后程序会自动改用二进制合并BinaryMerge且--mux-import必须先开启-M否则启动即报错MuxAfterDone disabled, MuxImports not allowed。调优与排障关键参数推荐值参数默认值建议值说明--thread-count本机 CPU 线程数4–16并发下载分片数超过服务器连接上限反而变慢--download-retry-count35单个分片异常重试次数弱网调高--http-request-timeout100 秒30–60 秒全局 HTTP 超时直播流建议调低以快速失败--live-take-count1632–64直播首次获取的分片数量影响录制起点--live-wait-time由节目单自适应5 秒手动固定直播列表刷新间隔秒并发开关-mt--concurrent-download默认关闭表示多条已选轨道串行处理多轨下载想提速时开启它并配合--thread-count控制总并发。常见问题三段式诊断现象速度慢或分片频繁失败 → 原因并发不足或超时设置过宽 → 处理开启-mt--thread-count调到 4–16--http-request-timeout降到 30快速失败快速重试检查是否被限速干扰确认没有误加-R代理环境下用--custom-proxy明确指定现象解密报错或输出文件无法播放 → 原因引擎不可用或密钥不匹配 → 处理查看日志中ffmpeg /mp4decrypt 路径是否指向真实存在的文件必要时用--decryption-binary-path指定确认密钥格式KID:KEY或纯KEYKID/KEY 均为 32 位十六进制换引擎交叉验证--decryption-engine FFMPEG兼容性最好MP4DECRYPT性能最好现象合并失败或成品损坏 → 原因容器封装依赖 ffmpeg 且分片可能缺失 → 处理确认--check-segments-count默认开启的校验结果日志会报告实际与预期分片数是否一致无法识别的加密方式程序会自动切到--binary-merge二进制直拼手动场景可直接指定该参数检查磁盘剩余空间临时目录建议显式指定--tmp-dir到空间充足的盘现象直播录制中途断流 → 原因管道混流在弱网下丢数据 → 处理关闭--live-pipe-mux退回--live-real-time-merge的传统合并路径--live-take-count提高到 32–64--live-wait-time设为 5–10 秒保持--live-keep-segments为 true断点后可从保留的分片排查生态与扩展二次开发入口解析层提供了三种处理器链在 ParserConfig 上以Insert(0, ...)挂载到链首优先级最高ContentProcessor分片内容后处理如改写字节流KeyProcessor解密前对密钥/描述信息做处理UrlProcessor分片 URL 预处理仓库内已有示例可参照DemoProcessor.cs、DemoProcessor2.cs以及针对特定站点 URL 重写的 NowehoryzontyUrlProcessor.cs。配套的--urlprocessor-args参数可把命令行字符串直接透传给自定义处理器。第三方工具协作程序把重活外包给成熟工具按职责分工——工具职责查找方式ffmpeg混流、concat 合并、备选解密引擎启动时自动查找--ffmpeg-binary-path指定mp4decryptCENC 解密默认引擎--decryption-binary-path指定mkvmergeMKV 容器封装-M muxermkvmerge时自动查找shaka-packagerCENC 解密备选引擎--decryption-engine SHAKA_PACKAGER支持各平台架构命名配置管理三个环境变量提供命令行之外的细粒度控制定义在 EnvConfigKey.cs# 覆盖 live-pipe-mux 时 ffmpeg 的命令行参数 export RE_LIVE_PIPE_OPTIONS-readrate 1 -re # 非 Windows 下命名管道文件的生成目录 export RE_LIVE_PIPE_TMP_DIR/tmp/nm3u8 # 图形字幕处理时保留 m4s 文件调试用 export RE_KEEP_IMAGE_SEGMENTS1日志侧--log-file-path落盘日志、--log-level控制级别DEBUG/INFO/WARN/ERROR/OFF--write-meta-json默认开启会把解析结果写成meta.json/meta_selected.json排障时直接看它比看终端滚动输出高效得多。收尾最佳实践清单临时目录显式指定--tmp-dir并在下载前确认有 2–3 倍成品大小的空闲空间--del-after-done默认开启确认流程稳定后让它自动清理多轨道任务用--save-pattern模板命名避免依赖程序的自动消歧弱网环境固定组合--download-retry-count 5 --http-request-timeout 30直播任务--live-real-time-merge保底弱网别开--live-pipe-mux分片保留作为事故现场排障先看meta.json和日志文件再用--skip-download/--skip-merge分段隔离问题出在解析、下载还是合并环节更新检查走 302 重定向判断离线环境加--disable-update-check最后提醒工具只负责技术能力下载前确认你对内容拥有合法访问权限并遵守所在地区的版权法规与平台服务条款。【免费下载链接】N_m3u8DL-RECross-Platform, modern and powerful stream downloader for MPD/M3U8/ISM. English/简体中文/繁體中文.项目地址: https://gitcode.com/GitHub_Trending/nm3/N_m3u8DL-RE创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考