fnm3u8dl · m3u8 下载器 飞牛 NAS 上的视频下载工具

一零一二

# fnm3u8dl · m3u8 下载器

> 飞牛 NAS 上的视频下载工具。复制 m3u8 / MPD / ISM 链接，一键下完整片到本地硬盘。
> 不限时长、不限大小、不限来源；直播能录，广告能跳，字幕跟着下载。

---

## 它能做什么

### 📥 点播下载（VOD）

把网上视频的 m3u8 链接贴进来，坐等收完整片。

- **三协议通吃**：m3u8（HLS）、MPD（DASH）、ISM（MSS / Smooth Streaming）—— 国内主流 CDN 这三种基本覆盖
- **AES-128 / SAMPLE-AES 解密**：会员视频、加密流自动解密，不需要你手动处理 key
- **分片并行 + 自动合并**：8 路并发拉分片，下载完自动拼成 mp4 或原始 ts
- **续传不丢进度**：网络抖一下断开了，第二次点"继续"接着下，不会重头再来
- **失败重试**：单分片最多重试 3 次，指数退避，临时网络问题不用你管
- **批量添加**：一行一个 URL，一次提交 N 个任务，UI 上并排看进度

### 🔴 直播录制

不是"先下完再播"，是真把正在播的流持续录下来。

- **3 维检测直播源**：URL 含 `live/livez/livestream` 关键词 + m3u8 短分片（≤6 个）+ 缺失 `#EXT-X-ENDLIST`，任一命中就判定是直播
- **10 个直播参数：`livePerformAsVod` / `liveRealTimeMerge` / `liveKeepSegments` / `livePipeMux` / `liveRecordLimit` / `liveWaitTime` / `liveTakeCount` / `liveFixVttByAudio` / `taskStartAt` / `liveRefreshInterval`
- **定时录制**：今晚 8 点自动开录 1 小时，挂着不管，到时候文件夹里就有成品
- **实时合并 / 增量追加**：录 30 分钟时已经能看到前 30 分钟的完整视频（`liveRealTimeMerge`），不用等结束
- **录制时长上限 + 分片数上限 + 录制前等待**：3 道安全网，防止直播断流了任务卡死
- **字幕偏移自动修**：`liveFixVttByAudio` 根据音频起始时间修正 VTT 字幕时间轴（ffprobe 实现）

### 🎬 视频处理

下完了不是黑盒，UI 里能直接看能直接改。

- **流筛选器**：用 `--select-video` / `--drop-video` 表达式挑"最高码率 1080p"、"只要 H264 编码"、"不要 AC-3 音轨"，提交前实时看到匹配结果
- **格式自动选**：清晰度从高到低排序（1080p > 720p > 480p > 360p），分片多但延迟低
- **转 MP4 / 保持 TS**：合并阶段选 mp4（带字幕轨）或者保持 ts（兼容性好但字幕要外挂）
- **外挂字幕自动下载**：SRT / WebVTT 自动拉到输出目录同位置，ffprobe 写进 mp4 metadata

### 🔐 安全 & 限制

- **SSRF 防护**：只放行 http(s) 协议，`file:///etc/passwd` / `gopher://` / `ldap://` 一律拒
- **URL 自动解码**：从聊天软件复制的 m3u8 被自动 percent-encode 了？应用自动识别并解码，不需要你手动 `%XX` 转换
- **IPv6 越权防护**：IPv4 映射的 IPv6 内网地址拒访问（如 `::ffff:127.0.0.1`）
- **路径白名单**：下载路径必须在 fnOS 注册的应用数据目录下，逃逸 `..` 一律拒
- **CORS 同源回退**：前端跨域配置异常时自动回退同源，避免接口全挂

### 📊 实时面板

- **KPI 4 联卡片**：进行中任务数 / 实时下载速度 / 已下载大小 / 任务总大小
- **Sparkline 趋势线**：每个 KPI 卡片内置 60s 趋势小图，能看到"这一分钟速度掉了一截"
- **进度条 5 色编码**：常规蓝 / 成功绿 / 警告黄 / 错误红 / 直播粉，瞄一眼就知道哪个任务在干吗
- **ETA 倒计时**：剩余大小 / 当前速度 = 剩余时间，自动算，live update
- **平均速度 vs 瞬时速度**：详情面板两个分开显示，能看出"网络稳不稳"

### 📱 移动端

- **iOS / Android WebView 自适应**：360dp 屏不挤、480px / 768px / 1024px 三档断点
- **触摸优化**：批量选择改成卡片模式、弹窗全屏、按钮 44px 起
- **手机端 5 列 KPI 改 2 列**：不让数字挤成蚂蚁
- **横屏 / 竖屏都好用**：KPI 4 列不强制，最窄屏自动 wrap

### ⚙️ 高级配置

- **下载线程数**：1-32 路并发，默认 8
- **速度限制**：KB/s 单位，0 = 不限速
- **User-Agent 自定义**：模拟 iOS Safari / Android Chrome 绕过反爬
- **HTTP 代理**：本地代理服务器中转
- **Referer 设置**：部分站需要带 Referer 才返回内容
- **重定向深度**：默认 10 层
- **重试次数**：单分片重试 1-10 次
- **超时控制**：单分片下载 30s 默认，可调 1-300s

### 🎨 UI 设计


- **玻璃拟态 Header**：背景模糊 + 顶部三色渐变条 + shimmer 动画
- **8 项视觉重构**：KPI Dashboard / Toolbar 分组 / 三段式任务卡 / Badge / Empty State / Batch Bar / Sparkline / Settings 侧边栏 modal
- **键盘快捷键**：`/` 搜索 / `Esc` 关闭弹窗 / `Del` 删除选中 / `Enter` 提交表单

---

## 适合谁用

✅ **直播主 / UP 主**：定时录制自己的直播间，结束后自动合并
✅ **下载党**：看到喜欢的视频有 m3u8 链接，复制粘贴下到 NAS 本地
✅ **离线观看**：出差没网，提前下好视频放 NAS 上
✅ **教学 / 培训场景**：录网课、录会议、录讲座，定时启动到点停
✅ **爬虫 / 备份**：批量 URL 一键提交，后台慢慢下



---



## 它不做什么

- **不解析** 视频网站首页（** / B 站 / 抖音等）—— 这些站需要 Cookie + 复杂签名算法，本应用是"已知 URL 下载"工具
- **不转码**（除非用 ffmpeg）—— 合并后是原始编码格式，需要转码可以装独立 ffmpeg
- **不上传** —— 纯下载工具
- **不开代理** —— 不做"科学上网"，你得自己解决网络问题

---

## 常见使用场景

### 场景 1：下载电影网站视频

1. 浏览器开 DevTools → Network 标签 → 过滤 `m3u8`
2. 播放视频，看到第一条 m3u8 请求，复制完整 URL
3. 打开 fnm3u8dl，点 "+ 添加"，粘 URL，选清晰度
4. 等 5-30 分钟（看视频长度），下载完合并自动完成
5. 输出目录找 `*.mp4` 即可

### 场景 2：定时录制直播

1. 点"定时"按钮，新增定时录制
2. 填：直播 URL + 开始时间（今晚 8:00）+ 持续时长（1 小时）+ 分片上限（3000）
3. 到点自动开录，1 小时后自动停
4. 在输出目录找 `live_*.ts`（默认）或 `live_*.mp4`（启用了实时合并）

### 场景 3：批量下整套教程

1. 从视频教程页提取所有 m3u8 URL（一行一个）
2. 点"批量添加"，粘贴
3. 8 路并发跑，UI 看实时进度
4. 全完成后文件夹就是整套教程

---

## 技术亮点

- **零依赖**：纯 Node.js ESM 模块，fpk 解包即跑，不依赖 npm install
- **188+ 单元测试**：核心逻辑（解析 / 解密 / 合并 / 直播 / 调度）全 TDD 覆盖
- **fnOS 网关原生支持**：Unix socket + `/app/fnm3u8dl/` 网关前缀自动剥离
- **数据目录标准**：`${TRIM_PKGVAR}/data/tasks/` 不污染用户卷（不在 `/vol*/UID/.@#local/` 写任何东西）
- **配置持久化**：所有设置存 `${TRIM_PKGVAR}/config/config.json`，卸载重装不丢

---

## 安装

1. 在 fnOS 应用中心上传 `fnm3u8dl.fpk` 包
2. 启用应用，浏览器访问桌面图标
3. 首次打开进入"下载设置"，配置下载路径（建议 `/vol2/1000/fnm3u8dl/` 或类似）