# m3u8-app

**Repository Path**: culturedream/m3u8-app

## Basic Information

- **Project Name**: m3u8-app
- **Description**: m3u8下载器
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-01
- **Last Updated**: 2026-07-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# m3u8 下载器（m3u8_app）

> 安卓优先的**自用** m3u8 / HLS 视频工具：内置浏览器嗅探、整站视频扫描、粘贴链接下载 → 并发分片 + 断点续传 + AES‑128 解密 → `ts→mp4` 合并（不重编码）→ 内置播放器 / 媒体库 / 本地转码。

![Flutter](https://img.shields.io/badge/Flutter-3.44-02569B?logo=flutter)
![Dart](https://img.shields.io/badge/Dart-3.12-0175C2?logo=dart)
![Platform](https://img.shields.io/badge/Platform-Android-3DDC84?logo=android)

<p align="center">
  <img src="docs/screenshots/crawl.png" width="720" alt="整站扫描">
</p>

---

## 目录

- [功能说明](#功能说明)
- [操作说明](#操作说明)
- [技术栈与架构](#技术栈与架构)
- [构建与运行](#构建与运行)
- [项目结构](#项目结构)
- [测试](#测试)
- [能力边界与免责声明](#能力边界与免责声明)

---

## 功能说明

### 1. 下载与队列

粘贴 `m3u8` / `mp4` 链接一键入队。分片**并发下载**、**AES‑128 解密**、`ffmpeg -c copy` 合并为 mp4（**不重编码**，快且无损）。队列支持**暂停 / 继续 / 删除 / 失败重试**，以及**全部暂停 / 清空 / 多链接一次粘贴入队**。每个任务实时显示**分片进度、已下大小、速度、剩余时间**。切到后台由前台服务保活，完成/失败有系统通知。

<p align="center"><img src="docs/screenshots/home-queue.png" width="700" alt="下载队列"></p>

### 2. 内置浏览器嗅探

内置浏览器打开任意网页，**双层嗅探**（JS 注入 `fetch/XHR/media` + 原生请求拦截）自动捕获页面里的视频流，连同回放需要的 **UA / Referer / Cookie** 一并带走，一键加入下载或在线预览。带**前进 / 后退 / 主页 / 书签 / 历史**。使用真实手机 Chrome UA，规避部分站点对内嵌 WebView 的反爬重定向。

<p align="center"><img src="docs/screenshots/browser.png" width="700" alt="浏览器嗅探"></p>

### 3. 整站视频扫描

输入网站链接，在**同源范围内有限爬行**发现站内视频，扫完列出供勾选下载。采用**混合引擎**：先轻量 HTTP 快扫（直接从 HTML / JSON 播放器配置里提取带 token 的 m3u8，含转义斜杠还原），对"看起来有播放器但没扒到流"的页再用浏览器渲染嗅探兜底。可调**深度 / 最多页数 / 超时**；自动跟随轮换镜像域名；内容/详情页优先。

<p align="center"><img src="docs/screenshots/crawl.png" width="700" alt="整站扫描"></p>

> ⚠️ **尽力版**：登录墙、强反爬、纯 JS 渲染、无限滚动、点击才取流的站点可能扫不全或扫不到。详见[能力边界](#能力边界与免责声明)。

### 4. 媒体库

列出已下载的视频，支持**播放 / 导出到系统相册 / 重命名 / 系统分享 / 删除**，以及**多选批量转码为 mp4 / 导出 / 删除**、按**时间 / 大小 / 名称**排序。批量转码复用「本地 m3u8 转码」引擎（`ffmpeg -c copy` 重封装为标准 faststart mp4 后存入相册，不重编码、不删除原文件）。

<p align="center"><img src="docs/screenshots/library.png" width="700" alt="媒体库"></p>

进入多选后，顶栏可对选中的视频批量**转码为 mp4 / 导出到相册 / 删除**；批量转码会入转码队列，点提示里的“查看”即可跟进度。

<p align="center">
  <img src="docs/screenshots/library-batch.png" width="420" alt="媒体库多选批量操作">
  <img src="docs/screenshots/library-transcode-queue.png" width="420" alt="转码队列">
</p>

### 5. 内置播放器

基于 media_kit（libmpv），播本地文件与在线 HLS/MP4。支持**记忆上次播放位置**、**倍速（0.5–2.0×）**、横屏旋转，从媒体库进入时可**上一个 / 下一个**。

<p align="center"><img src="docs/screenshots/player.png" width="560" alt="播放器"></p>

### 6. 本地 m3u8 批量转码

扫描设备上已有的本地 `m3u8`（自动扫常用目录或指定文件夹），多选 / 全选后按并发批量 `ffmpeg -c copy` 转成 mp4 并存相册；每个文件显示**实时进度**；可选"转码后删除源文件"省空间；智能输出命名（通用文件名回退用文件夹名）。

<p align="center"><img src="docs/screenshots/transcode.png" width="700" alt="本地转码"></p>

### 7. 设置

主题（浅色 / 深色 / 跟随系统）、并发下载分片数、同时下载任务数、**默认清晰度**（最高 / 1080p / 720p / 480p / 最低）、仅 Wi‑Fi 下载、下载完成自动导出相册、清理分片缓存。

<p align="center"><img src="docs/screenshots/settings.png" width="700" alt="设置"></p>

---

## 操作说明

### 粘贴链接下载
1. 主页顶部输入框粘贴 `m3u8` / `mp4` 链接（或点输入框右侧📋从剪贴板粘贴；打开 App 时若剪贴板是视频链接会自动填入）。
2. 点 **加入下载队列**。一次粘贴含多个链接的文本会**全部入队**。
3. 在"下载队列"里查看进度、速度、剩余时间；用卡片上的 **⏸ 暂停 / 🗑 删除**，或右上角 **⋮** 做"全部暂停 / 清空队列"。失败任务点 **↻ 重试**。

### 内置浏览器嗅探下载
1. 主页右上角 **🔎（内置浏览器）** → 地址栏输入网址访问。
2. 页面播放/加载视频后，底部"已嗅探 N 个流"面板会列出捕获到的流。
3. 点某条的 **下载**（或 **▶ 在线预览**），或 **全部下载**。返回主页看进度。

### 整站扫描
1. 主页右上角 **☰🔍（整站扫描）** → 输入网站首页/分类页链接。
2. 按需调 **深度 / 最多页 / 超时** → **开始扫描**。
3. 结果列表勾选（或 **全选**）→ **下载选中**。

### 队列 → 断点续传 / 链接重绑
- 杀进程或暂停后，未完成任务出现在主页"**未完成的任务**"，点 **继续** 即从断点续传（保留已下分片，重拉新鲜清单对齐）。
- 若链接已失效（`needsRefresh`），点 **刷新** 打开浏览器重新嗅探同一视频，捕获后**用新链接续传**，保留已下分片。

### 播放 / 管理
- 媒体库点视频卡片播放；点右侧 **⋮** 可**重命名 / 分享 / 导出到相册 / 删除**；顶部可**排序**、进入**多选**批量**转码为 mp4 / 导出到相册 / 删除**（批量转码入转码队列，可点提示里的“查看”查看进度）。

### 本地转码
1. 主页右上角 **🎬（本地转码）** → **扫描设备** 或 **选择文件夹**。
2. 勾选要转的 `m3u8`（可全选），可选"转码后删除源文件" → **开始转码**。按设置的并发批量进行。

---

## 技术栈与架构

- **框架**：Flutter 3.44 / Dart 3.12，Material 3。
- **状态管理**：Riverpod（`Notifier` / `FutureProvider`）。
- **核心库**：`media_kit`（播放）、`ffmpeg_kit_flutter_new_min`（`-c copy` 合并/转码）、`flutter_inappwebview`（内置浏览器 + 嗅探）、`pointycastle`（AES‑128‑CBC）、`flutter_hls_parser`、`sqflite`（任务持久化）、`flutter_foreground_task`（后台保活）、`share_plus`、`permission_handler`。
- **架构**：MVVM 分层。
  - `lib/features/<模块>/{view, view_model, model}`：下载 / 浏览器 / 整站爬取 / 媒体库 / 播放器 / 设置 / 本地转码。
  - `lib/data/{models, services, repositories}`：解析、分片下载、解密、合并、持久化、嗅探、爬取扫描等。
  - `lib/core/{di, theme, widgets}`：Provider 装配、主题、共享组件。
- **下载"真源"设计**：持久化"来源 URL + 请求头 + 指纹（分片数/序列）"，而非易过期的签名分片 URL；续传时重拉新鲜清单、按 index 对齐，抗签名过期。

---

## 构建与运行

### 前置
- Flutter **3.44+**（含 Dart 3.12+）、Android SDK（compileSdk 36 / build‑tools 36）、**JDK 17**（Gradle 用）。
- `minSdk 24`，应用 id `com.personal.m3u8_app`。

### 命令
```bash
flutter pub get

# 连真机 / 模拟器后直接运行
flutter run

# 构建调试 APK（x86_64 模拟器）
flutter build apk --debug --target-platform android-x64

# 构建发布 APK
flutter build apk --release
```

> 注：本项目目前**安卓优先**。Windows 桌面端（跨平台 Dart 引擎已就绪）尚需：安装 Visual Studio「C++ 桌面开发」、ffmpeg 改走外置 `ffmpeg.exe`、`flutter_inappwebview` Windows 端实测。

---

## 项目结构

```
lib/
├─ core/            # 主题、DI(providers)、共享组件
├─ data/
│  ├─ models/       # download_task / segment / captured_stream / app_settings ...
│  ├─ services/     # 解析 / 分片下载 / AES 解密 / 合并 / 嗅探 / 页面扫描 / 通知 ...
│  └─ repositories/ # download_manager（持久化 + 续传 + 重绑）
├─ features/
│  ├─ download/     # 主页 + 下载队列
│  ├─ browser/      # 内置浏览器嗅探
│  ├─ crawl/        # 整站视频扫描（引擎 / 控制器 / 页面）
│  ├─ library/      # 媒体库
│  ├─ player/       # 播放器
│  ├─ convert/      # 本地 m3u8 转码
│  └─ settings/     # 设置
└─ main.dart
docs/screenshots/   # README 截图
test/ · integration_test/   # 单测 + 真机集成测试
```

---

## 测试

```bash
flutter test        # 单元测试（60+）
flutter analyze     # 静态分析（应为 No issues）
```

关键链路均有单测：playlist 解析、AES‑128 往返（NIST 向量）、分片并发/取消、断点续传规划、**链接重绑→续传**、变体清晰度选择、整站爬取引擎（深度/页数/同源/去重/镜像跟随）、页面扫描（含 JSON 转义斜杠提取）等。`integration_test/` 内含在真机上跑通"解析→下载→ffmpeg 合并→有效 mp4"的端到端测试。

---

## 能力边界与免责声明

**能力边界（整站扫描为"尽力版"）**：对**登录墙**、**强反爬 / 重定向**、**纯 JS 渲染且点击才取流**、**无限滚动**、**引流到自家 App** 的站点，可能部分或完全无法获取；仅在**同源**范围内爬行，不绕过任何反爬或验证码（内置浏览器只提供可见渲染窗口供人工登录 / 过验证码）。此外**不做**重编码 / 换容器 / 抽音频、DRM 解密、直播录制、多用户 / 云同步。

**免责声明**：本项目仅供**个人学习与自用**。请仅用于**你有权访问和下载**的内容，并遵守目标网站的服务条款、`robots.txt` 与所在地法律法规。**请勿**用于侵犯版权、破解付费 / DRM 内容或任何非法用途。使用本工具产生的一切后果由使用者自行承担。