royswift2007/m3u8-video-sniffer

GitHub: royswift2007/m3u8-video-sniffer

M3U8D 是一个 Windows 桌面工具,用于从网站嗅探和下载 m3u8、mpd、mp4 等视频流。

Stars: 23 | Forks: 3

# M3U8D 版本 0.4.1

English | 简体中文

Main Interface

Browser Workbench Resource List

## 概述 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应用, 下载工具, 协议处理, 多引擎下载, 媒体解析, 媒体资源抓取, 无后门, 桌面软件, 流媒体下载, 流媒体工具, 浏览器扩展集成, 浏览器自动化, 特征检测, 登录状态保持, 网络资源下载, 视频下载, 资源嗅探, 逆向工具, 队列管理