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)

video-streaming
Searching Database…

What is this?StreamFirefly (流萤) is a local-first tool for finding and downloading media on web pages. A browser extension detects videos, audio, images and HLS/DASH manifests, while a Rust-based Windows native helper handles the actual downloading, queuing, resuming and FFmpeg merging; tasks and settings stay on your machine.
Is this just a browser extension, or does it need something else installed?It's two pieces working together: a Chrome/Edge/Firefox extension for detecting media and showing the UI, plus a separate Windows native helper app that performs the actual downloads.
Does the native helper run on Mac or Linux, or only Windows?Only Windows — the native helper is a Windows app. Building from source additionally needs Node.js 24, Rust 1.98 with the MSVC toolchain, and Chrome/Edge 116+ or Firefox 140+; the helper itself relies on Windows' built-in curl and FFmpeg for HLS/DASH merging.
Can it download DRM-protected streams?No. StreamFirefly explicitly refuses to bypass DRM or SAMPLE-AES protection — it only flags such content without downloading it, and is meant only for media you already own or are authorized to save.
What if the video started playing before I opened StreamFirefly?It backfills the manifest from the page's resource-timing data at the moment you open it, so you can still catch streams that started loading earlier.
Can it detect manifests that a page generates dynamically via scripts?Yes, by turning on 'Deep Search' (off by default), which watches JSON.parse, Base64 decoding, and same-origin Worker output for full HLS/MPD text that would otherwise be missed.
Can I record a live HLS stream instead of just a VOD?Yes, HLS live streams can be manually started, paused and stopped for recording from the parsing page.
Can downloads be sent to an external tool like Aria2?Yes, the optional external-tools feature can forward resources to Aria2, an HTTP service, a local program, or a custom protocol, previewing the expanded parameters before sending.
Creator
rumoii
Size
5.3 MB
Stars
286
Age
13d
Commits · 90 Days