royswift2007/m3u8-video-sniffer

# M3U8D 版本 0.4.1

English | 简体中文

## 概述 M3U8D 是一个基于 Python 和 PyQt6 构建的 Windows 桌面应用程序。它将以下任务整合到一个工作流程中： - 在持久化的浏览器会话中打开真实网页，保持登录状态和 cookies - 在播放过程中自动发现 m3u8 / mpd / mp4 / webm / magnet 等媒体资源 - 从资源列表中筛选、选择质量并分配下载引擎 - 使用多个引擎执行下载，并管理队列、重试和历史记录 - 通过本地 HTTP API 和 `m3u8dl://` 协议接收来自外部浏览器扩展或脚本的资源 ## 核心功能 ### 浏览器工作台与资源嗅探 - 通过 Playwright 启动真实的持久化 Chrome（而非内嵌浏览器控件） - 在会话间保持登录状态、cookies 和浏览器扩展 - 四种发现路径：页面 URL 模式匹配、请求拦截、响应 Content-Type 检测以及注入前端脚本回调 - 捕获窗口机制，用于延迟/动态注入的媒体链接 - 通过 `--disable-blink-features=AutomationControlled` 减少自动化检测 ### 资源列表与筛选 - 多层去重（URL、视频 ID、itag、标题、变体） - 按标题 / URL / 源文本搜索 - 按类型（M3U8 / MPD / MP4 / FLV / MKV / WEBM / TS）、源域名和分辨率筛选 - 自动解析 M3U8 主播放列表并展开变体 - 批量下载、批量移除和清空操作 ### 多引擎下载 五个下载引擎协同工作： | 引擎 | 适用场景 | |--------|----------| | N_m3u8DL-RE | m3u8 / mpd / HLS / DASH，支持质量选择 | | yt-dlp | YouTube / Bilibili / TikTok / Instagram / Twitter / Vimeo 以及基于页面的网站 | | Streamlink | 直播流（Twitch / Douyu / Huya / Bilibili 直播） | | Aria2 | 直接链接文件和磁力链接 | | FFmpeg | 后处理（重混流、合并、字幕提取） | 引擎选择优先级：用户偏好 → 基于扩展名的检测 → MIME 探测 → 直播平台列表 → yt-dlp 回退。规则外部化存储在 `resources/engine_rules.json` 中。 ### 下载管理 - 幂等入队：重复的请求会被合并，而不是堆叠 - 入队前进行磁盘空间预检查（预估大小的 1.2 倍） - 带动态调整的并发工作线程池（缩小时软退出） - HLS 预检查探测（关键 URL + 首个分片可达性） - 带退避的重试、引擎回退链和认证重试优先策略 - 2 秒内响应停止（500ms 读循环退出 + 1.5s 递归终止） - 清晰反馈：`已入队` / `已合并` / `需确认` / `失败` ### 组件管理器 - 管理所有五个引擎：检查本地版本、检查远程更新、一键更新 - 三层 sha256 验证：静态 pin、动态伴随文件（`sha256_url`）、首次使用信任（TOFU，通过 `~/.m3u8d/component_pins.json`） - 暂存目录隔离 → 安装前 sha256 再验证 → 原子替换，支持 `.bak` 回滚 - 安装后版本交叉检查，使用宽松的前缀匹配 - 大文件下载（如 FFmpeg ~130 MB）每 2% 进度更新 - 无静默后台安装；启动时只读检查，用户确认后才更新 ### 外部集成 **CatCatch 本地 HTTP 服务：** - 严格绑定到 `127.0.0.1:9527`（回退 9528-9539） - 会话令牌认证（`X-Session-Token` + 允许的来源列表） - SSRF 过滤：拒绝私有/环回/链路本地/云元数据 URL - 请求体限制：64 KiB（超出返回 413） - `GET /download` 被禁用（405）；所有下载通过认证的 `POST /download` 进行 - 外部载荷中内部以 `_` 为前缀的头部被剥离 **协议处理器（`m3u8dl://`）：** - 读取 `~/.m3u8d/session.token` 并通过认证的 POST 传递给正在运行的实例 - 仅在无运行实例响应时，才回退启动新实例 - 日志脱敏：令牌和敏感查询参数永不以明文写入 ### 安全与隐私 - 所有引擎命令行使用参数化数组（无字符串拼接） - 传递给引擎的头部经过白名单过滤：仅 Referer / User-Agent / Origin / Cookie / Accept-Language - yt-dlp 的 `format_id` 根据 `[A-Za-z0-9_.+:\-]+` 进行验证（拒绝 shell 元字符） - 下载历史（`history.json`）在写入前剥离 Cookie / Authorization / X-Session-Token - 日志脱敏：28 种敏感查询键模式（OAuth / AWS / GCS / CloudFront / Azure 令牌） - 调试敏感日志（`SECURITY_DEBUG=1`）被隔离且默认禁用 ## 运行环境 | 项目 | 要求 | |------|------| | 操作系统 | Windows 10/11 64 位 | | Python | 3.9+ | | GUI | PyQt6 + PyQt6-WebEngine | | 浏览器 | 系统已安装 Google Chrome | | 网络 | 能够访问 GitHub 和常见媒体网站 | | 磁盘 | 至少 500 MB，推荐 2 GB+ | **重要提示：** 内置浏览器依赖系统安装的 Chrome。仅运行 `playwright install chromium` 并不能替代。 ## 快速开始 ### 1. 安装 Python 依赖 ``` pip install -r requirements.txt ``` ### 2. 准备浏览器和外部工具 - 确保 Google Chrome 已安装并能正常启动 - 确保 `bin/` 目录下存在所需的引擎，或运行 `scripts/download_tools.bat` ### 3. 启动应用程序 ``` python mvs.pyw ``` 或使用更轻量的开发入口： ``` python main.py ``` ### 4. （可选）注册协议处理器 ``` scripts\register_protocol.bat ``` 这将使浏览器扩展（例如 CatCatch）发送的 `m3u8dl://` 链接能被 M3U8D 接收。 ## 命令行参数 | 参数 | 描述 | |-----------|-------------| | `--url` | 视频或页面 URL（仅限 http/https，最大 4096 字符，经过 SSRF 过滤） | | `--headers` | 包含请求头的 JSON 字符串（仅限白名单字段） | | `--filename` | 默认文件名（Windows 安全处理，路径最大 240 字节） | ## 依赖项 ### Python 列在 `requirements.txt` 中： - PyQt6 ≥ 6.6.0 - PyQt6-WebEngine ≥ 6.6.0 - plyer ≥ 2.1.0 - requests ≥ 2.31.0 - playwright ≥ 1.40.0 ### 外部引擎 声明在 `deps.json` 中： - **必需：** yt-dlp, N_m3u8DL-RE, FFmpeg - **推荐：** aria2c, Streamlink - **可选：** Deno ## 打包与安装 | 步骤 | 工具 | 入口 | |------|------|------| | 构建 | PyInstaller | `build_pyinstaller.py` / `build_pyinstaller.bat` | | 安装程序 | Inno Setup | `installer/M3U8D.iss` | | 输出 | | `installer/output/M3U8D-Setup v0.4.1.exe` | 安装程序可以： - 安装主应用程序包和协议处理器 - 可选地在安装后下载必需/推荐的引擎 - 可选地注册 `m3u8dl://` 协议 ## 项目结构 ``` M3U8D/ ├── mvs.pyw # recommended entry (packaging-aligned) ├── main.py # development entry ├── protocol_handler.pyw # m3u8dl:// protocol handler ├── config.json # application configuration ├── deps.json # external dependency manifest ├── core/ # sniffing, download management, component updates │ └── download/ # modular download manager (queue, workers, classifier) ├── engines/ # download-engine adapters ├── ui/ # PyQt6 GUI layer ├── utils/ # logging, i18n, config, redaction, path sanitization ├── resources/ # icons, manuals, engine_rules.json ├── scripts/ # protocol registration, dependency download ├── tests/ # automated tests ├── installer/ # Inno Setup installer ├── bin/ # external engine binaries ├── logs/ # runtime logs (auto-rotated) └── cookies/ # cookie storage per domain ``` ## 常见问题 ### 浏览器启动了，但某些视频无法播放 Playwright 驱动的 Chrome 使用的启动标志与您日常使用的浏览器不同。常见原因： - Widevine DRM CDM 未加载（在内置浏览器中检查 `chrome://components`） - 自动化模式下 GPU/硬件解码受限 - 一些反机器人系统检测到自动化环境 **解决方法：** 使用您的系统浏览器 + CatCatch 扩展捕获资源 URL，然后让 M3U8D 通过协议处理器或 HTTP API 下载。 ### 协议处理器启动了新实例，而不是复用正在运行的实例 - 确保在最新安装后执行了 `scripts\register_protocol.bat` - 检查 `~/.m3u8d/session.token` 是否存在且可读 - 验证端口 9527-9539 是否未被防火墙阻止 ### 组件更新似乎卡住了 大型组件（如 FFmpeg ~130 MB）需要几分钟时间。界面会显示每 2% 的进度更新。每个 HTTPS 请求的总超时时间为 10 分钟。如果确实卡住了（长时间零速度），请在组件管理器中点击“重试”。 ## 合规性与开源声明 参见 [`OPEN_SOURCE_NOTICE.md`](OPEN_SOURCE_NOTICE.md)。 - 本项目用于技术研究、学习和合法个人使用 - 开源并不授予对目标网站内容的任何权利 - 用户必须核实网站条款、版权和当地法律 - 第三方引擎有其各自的许可证 - 不得用于侵权、大量滥用或非法活动 ## 相关文档 - [安装指南](INSTALL.md) — 安装和环境配置 - [v0.4.1 更新日志](CHANGELOG_v0.4.1.md) — 自 v0.3.1 起的详细更新日志 - [resources/manual_zh.md](resources/manual_zh.md) — 详细中文用户手册 - [resources/manual_en.md](resources/manual_en.md) — 详细英文用户手册 ## 许可证 参见 [LICENSE](LICENSE)。在重新分发二进制文件或安装程序之前，请验证所有捆绑的第三方工具的许可证。

标签：HTTP API, M3U8解析, MP4下载, MPD下载, Playwright, PyQt6, Python, Windows应用, 下载工具, 协议处理, 多引擎下载, 媒体解析, 媒体资源抓取, 无后门, 桌面软件, 流媒体下载, 流媒体工具, 浏览器扩展集成, 浏览器自动化, 特征检测, 登录状态保持, 网络资源下载, 视频下载, 资源嗅探, 逆向工具, 队列管理