streamfirefly README

The project's README from github.com/rumoii/streamfirefly. As one markdown file: README.md.

流萤 StreamFirefly

本地优先的网页媒体发现与下载工具

版本 下载量 Stars 许可证 浏览器 系统

下载 · 安装指南 · 使用说明 · 隐私政策 · English

流萤由浏览器扩展和 Windows 本地助手两部分组成。扩展在网页里发现视频、音频、图片和 HLS/DASH 清单；本地助手用 Rust 编写，负责下载、排队、断点恢复和 FFmpeg 合并。任务和设置只保存在本机。

当前版本为 1.0.8。流萤不绕过 DRM，请只下载你拥有版权或已获授权的内容。

流萤分为两个发行版，源码相同：

亮点

看中哪个，点下载就行：16 路并发、切片自动重试、断点续传、FFmpeg 合并 三步装好，复制粘贴就行：下载扩展、加载扩展、复制安装命令 HLS 解析页：清晰度、音轨、字幕自己挑，还能按时间截取

功能

截图

资源列表
资源列表		 下载任务
下载任务
悬浮工作区
悬浮工作区		 HLS 解析
HLS 解析

截图来自自动化界面测试，资源为测试数据。

支持范围

类型 状态 说明
普通 HTTP 文件 支持 视频、音频、图片；并发下载、暂停续传
HLS 点播 支持 切片级重试、检查点与重启恢复
HLS AES-128 支持 批量下载前先用第一个切片验证密钥
HLS 直播 支持 在解析页单独开始录制；不支持 LL-HLS Part
DASH 点播 实验性 仅静态、单 Period、非加密清单
Blob / MediaSource 实验性 通过缓存捕捉保存开始捕捉之后播放的数据
DRM、SAMPLE-AES 不支持 只提示，不绕过
可选功能说明
  • 识别规则：按后缀、MIME 或 URL 正则匹配，可限定站点和大小，排除规则优先；支持排序、复制、导入导出，并显示命中原因。正则和模板在有超时限制的 Worker 中运行。
  • URL 提取：从请求地址中提取真实媒体地址，作为单独的资源显示。提取出的资源不继承原请求的凭据，也不会自动发送到外部工具。
  • 输出模板：HLS、DASH 和其他资源可分别设置复制模板，另有文件名模板。只做字符串变换，不执行脚本。
  • 文件命名与位置：默认用网页标题命名，服务器提供文件名时拼在标题后面；默认按来源网站放进子文件夹（如 bilibili.com）。可在设置中改回资源原名或关闭分文件夹，已有文件不会移动。
  • 检查更新：通用版和 Firefox 版每天第一次打开时向 GitHub 查询一次新版本，有新版才提示，可在设置中关闭。
  • 外部工具：发送前在确认页预览展开后的参数，并逐项显示结果。明确失败的可以手动重试，结果未知的不会自动重发。自动发送只对配置过的站点和 HTTP/Aria2 工具生效。
  • 深度搜索：默认关闭，按页面开启，可记住站点。会观察 JSON.parse、Base64、文本解码和同源 Worker 中出现的完整 HLS/MPD 文本。发现的疑似 AES-128 密钥只保存在内存中，可在 HLS 解析页选用。
  • 缓存捕捉：推荐“重新捕捉”，授权后刷新来源页，从首次追加开始保存。普通捕捉补入页面内存中的有效初始化段，只保存开启后追加的正文；无法确认 Blob 关联时可手动选择。拖动或编码变化分段输出 MKV，不回溯浏览器旧缓存。可选 2–16 倍速静音录制；一键捕捉默认优先录制兼容格式（H.264），录好的视频以网页标题保存在保存目录，系统自带播放器即可播放（部分网站清晰度可能降低，可关闭）。暂存范围和上限见 隐私政策。

安装

一键安装（推荐）

  1. 安装扩展：Chrome 应用商店版还在审核中，审核通过前请按安装指南安装通用版；其他浏览器同样见安装指南。
  2. 安装后会自动打开设置页。点击“复制安装命令”，按 Win + R，粘贴并回车。
  3. 命令会下载与扩展同版本的本地助手，校验 SHA-256 后安装到当前用户目录，无需管理员权限。完成后扩展自动连接。

手动安装完整包

从 Releases 下载适合架构的 Windows 完整包，再按安装指南操作。

从源码构建

需要 Node.js 24、Rust 1.98（MSVC 工具链，需安装 Visual Studio C++ 生成工具），与 CI 使用的版本一致；以及 Chrome/Edge 116+ 或 Firefox 140+。本地助手使用 Windows 自带的 curl 下载，HLS/DASH 合并需要 FFmpeg。

npm install
npm run build:extension
cargo build --release --manifest-path native-host/Cargo.toml

  1. 在 chrome://extensions 开启开发者模式，加载 extension/ 目录，记下扩展 ID。

  2. 注册本地助手：

    .\tools\install-native-host.ps1 `
  -ChromeExtensionId '<Chrome 扩展 ID>' `
  -FirefoxExtensionId '[email protected]'

  3. 每次重新编译本地助手后需要再运行一次安装脚本；扩展更新后在扩展管理页点击“重新加载”。

使用

  1. 打开有视频或音频的网页，点击工具栏中的流萤图标。
  2. “资源”页列出已发现的媒体，可以按名称、类型、大小和时长筛选；点开一项可以看到封面、预览和完整地址。
  3. 点击“下载”保存。HLS/DASH 可以进入解析页选择画质、音轨、字幕和范围；勾选多项后可以批量下载、复制或发送到外部工具。
  4. “下载”页显示进度，可以暂停、继续、重试或删除任务。

默认只在流萤打开时嗅探。列表为空时先播放一下视频；还是没有的话，刷新网页后重新打开流萤，或在设置里把嗅探时机改为“始终嗅探”。

小提示：推荐开启深度搜索。 深度搜索默认关闭。开启后，流萤还会识别网页用脚本动态生成的视频清单，能找到更多资源。开启方法：在“资源”页点击工具栏的雷达图标 →“开启深搜”，然后刷新网页。常用的网站可以勾选“记住此站点”。

遇到问题

悬浮窗口操作

工作原理

工作原理：网页中的内容脚本与页面探针交给浏览器扩展嗅探识别；扩展与悬浮面板双向通信，并通过 Native Messaging 与 Rust 本地助手通信；本地助手调用 curl 下载、FFmpeg 合并

目录 内容
extension/ 浏览器扩展：后台、内容脚本、页面探针和清单
extension-ui/ 侧栏与网页内工作区界面（Vue 3）
native-host/ 本地助手：协议、任务存储、调度和 HTTP/HLS/DASH 下载
shared/ 扩展与界面共用的识别、提取和模板逻辑
tools/ 构建、测试和 Windows 安装脚本
docs/ 设计决策与开发说明

开发

npm install
npm run typecheck
npm run validate:extension   # 构建并校验 Chrome / Firefox 扩展
npm run test:unit
npm run test:ui:browser      # 界面测试，使用模拟 API，截图在 test-results/ui/
npm run verify:features      # 包括 cargo test 和本地助手集成测试
浏览器测试

使用独立的临时配置，不影响日常浏览器数据。

npm run test:chrome
npm run test:firefox
npm run test:browsers        # 依次运行 Chrome、Edge、Firefox

浏览器路径可以用 CHROME_BINARY、EDGE_BINARY、FIREFOX_BINARY 指定。

本地助手测试 
cargo test --manifest-path native-host/Cargo.toml
npm run test:native

首次运行前准备测试用 FFmpeg（不需要安装 Inno Setup）：

.\tools\download-ffmpeg.ps1 -Architecture x64        # 发布包捆绑的精简版
New-Item -ItemType Directory -Force installer\build\x64 | Out-Null
Copy-Item tools\ffmpeg-cache\ffmpeg-x64.exe installer\build\x64\ffmpeg.exe
.\tools\download-fixture-ffmpeg.ps1                  # 生成测试素材用的完整版

test:native 默认使用刚编译的 debug 版本，任务写入临时目录；可以用 STREAMFIREFLY_NATIVE_EXE 指定其他版本。HLS/DASH 测试中，本地助手使用 STREAMFIREFLY_FFMPEG_EXE 指定的精简版 FFmpeg（默认 installer/build/x64/ffmpeg.exe）；测试素材的生成和检查使用 tools/download-fixture-ffmpeg.ps1 下载的完整版 FFmpeg 和 FFprobe，也可用 STREAMFIREFLY_FIXTURE_FFMPEG_EXE、STREAMFIREFLY_FFPROBE_EXE 指定。

打包与发布

开发自测：

.\tools\package-extension.ps1 -Edition general        # 通用版 Chromium 扩展
.\tools\package-extension.ps1 -Edition chrome-store   # Chrome 应用商店上传包
npm run package:firefox                               # Firefox 测试用 XPI（未签名）
.\tools\build-installer.ps1 -Architecture x64         # 本地 EXE 安装器，不进 Release；arm64 同理

正式发布入口是 .\tools\package-release.ps1 -SignedFirefoxXpi '<已签名 XPI 路径>'，签名、验收和上传的完整步骤见正式发布流程。

  • 正式打包必须使用干净提交和与其运行时代码一致的 Firefox 签名包。内测工具只用于历史版本，不用于正式发布。
  • tools/prepare-release.ps1 是旧的发布流程，产出 EXE 安装器和未签名 XPI，已废弃，不要用于发布。
  • EXE 安装器构建需要 Inno Setup 6，同时会生成本地助手测试默认读取的 installer/build/<架构>/ffmpeg.exe。捆绑的 FFmpeg 是 tools/ffmpeg/build.sh 编译的精简 LGPL 版，按固定 SHA-256 下载，不提交到仓库。
  • 本地开发用的扩展 ID 是 gimoeapmpoeogpabfdplccplmmohklff，不要用它构建对外发布的安装包。Firefox 固定使用 [email protected]。
  • 商店提交材料在 store-assets/。

升级与数据

文档

隐私

Cookie 和 Authorization 只在下载过程中保存在内存里，不写入任务记录。缓存捕捉只保存开始捕捉之后的数据，不读取浏览器缓存。详见隐私政策。

Star 趋势

Star 趋势

致谢

流萤使用了 Vue、Pinia、hls.js、Tabler Icons、curl 和 FFmpeg。第三方许可见 THIRD_PARTY_NOTICES.md，FFmpeg 来源见 installer/FFMPEG-SOURCE.txt。

streamfirefly (rumoii/streamfirefly)

Searching Database…

286 ·GitHub
Streamfirefly
Что это такое?StreamFirefly (流萤) — это локальный инструмент для поиска и скачивания медиафайлов на веб-страницах, который работает в первую очередь с данными на вашем компьютере. Браузерное расширение находит видео, аудио, изображения и манифесты HLS/DASH, а нативный помощник для Windows на Rust выполняет само скачивание, управляет очередью, докачкой и склейкой через FFmpeg; задачи и настройки остаются на вашем компьютере.
Это просто браузерное расширение, или нужно что-то ещё устанавливать?Это две части, работающие вместе: расширение для Chrome/Edge/Firefox, которое находит медиафайлы и показывает интерфейс, плюс отдельное нативное приложение-помощник для Windows, которое выполняет само скачивание.
Нативный помощник работает на Mac или Linux, или только на Windows?Только Windows — нативный помощник является приложением для Windows. Для сборки из исходников дополнительно нужны Node.js 24, Rust 1.98 с инструментарием MSVC, а также Chrome/Edge 116+ или Firefox 140+; сам помощник использует встроенный в Windows curl и FFmpeg для склейки потоков HLS/DASH.
Может ли он скачивать потоки с защитой DRM?Нет. StreamFirefly принципиально не обходит защиту DRM или SAMPLE-AES — такой контент он лишь помечает, но не скачивает. Инструмент предназначен только для медиафайлов, которыми вы уже владеете или на сохранение которых у вас есть разрешение.
А если видео начало проигрываться ещё до того, как я открыл StreamFirefly?В момент открытия он восстанавливает манифест из данных resource-timing самой страницы, так что можно поймать даже потоки, которые начали загружаться раньше.
Может ли он находить манифесты, которые страница создаёт динамически через скрипты?Да, для этого нужно включить «Deep Search» (по умолчанию выключено) — он отслеживает вызовы JSON.parse, декодирование Base64 и вывод воркеров с того же домена, чтобы найти полный текст HLS/MPD, который иначе остался бы незамеченным.
Могу ли я записывать прямую трансляцию HLS, а не только VOD?Да, прямые HLS-потоки можно вручную запускать, ставить на паузу и останавливать для записи со страницы разбора.
Можно ли передать скачивание во внешний инструмент, например Aria2?Да, необязательная функция внешних инструментов позволяет пересылать ресурсы в Aria2, HTTP-сервис, локальную программу или пользовательский протокол, показывая предпросмотр итоговых параметров перед отправкой.
What are similar projects?cat-catch, N_m3u8DL-CLI, Tailtab, clients, ext-saladict, maxurl, desktop_gifs, Telegram-Media-Downloader
Which topics is it in?edge-extension, webextension, dash, media-downloader, firefox-addon, m3u8, hls, live-streaming, video-downloader, firefox, video-streaming, firefox-extension
Creator
rumoii
Size
5.3 MB
Stars
286
Updated
CommitOct 17Releasev1.0.8Oct 13
Age
13d
Commits · 90 Days