QRREC 可以让两台设备仅通过“屏幕 + 摄像头”传输文件。发送端把文件编码成连续播放的二维码或彩色矩阵，接收端采集有效画面、重组并校验文件。V1–V4 在浏览器本地运行，V5/V5.1 使用网页发送端和 iOS App 接收端；文件内容都不会上传服务器。
| 版本 | 核心定位 | 主要特点 | 适合场景 | 在线入口 | 理论速率 | 实测速率 |
|---|---|---|---|---|---|---|
| V1 稳定基础版 | 兼容性与稳定性优先 | 单路动态 QR、喷泉码抗丢帧、本地文件校验、图片/视频/文本预览与下载 | 首次使用、设备性能一般、需要稳定传输 | 接收端 · 发送端 | 约 33.9 KB/s（1445 B × 24 FPS） | 暂无统一真机记录 |
| V2 自适应高速版 | 在标准 QR 协议上提高吞吐量 | 双 QR 并行、自适应载荷与帧率、自动 gzip 压缩、稳定帧过滤、双 ROI/多 Worker 解码、PWA 接收端 | 屏幕较大、光线稳定、希望获得比 V1 更高的速度 | 接收端 · 发送端 | 默认约 38.3 KB/s；大屏自适应约 56.4 KB/s | 暂无统一真机记录 |
| V3 多通道实验版 | 继续优化实时接收，并探索彩色高密度编码 | 高速双 QR、画面指纹去重、重叠 ROI 并行搜索；另带 libcimbar 彩色矩阵通道、实时速率/进度/解码统计、完成后媒体预览 | 测试高性能实时传输，或比较双 QR 与彩色矩阵效果 | 接收端 · 发送端 | 双 QR 约 57.4 KB/s；彩色矩阵约 109.9 KB/s | 彩色矩阵 24.4–32.8 KB/s；双 QR 暂无统一记录 |
| V4 先录像后解码版 | 把摄像头采集和 QR 解码分成两个阶段 | 发送端生成有限且可验证的循环并给出建议录像时长；接收端先录像或导入已有视频，停止拍摄后再以 30 FPS 本地离线解码，重组成功即可提前结束 | 手机实时解码跟不上、需要先稳定录下画面再慢慢处理 | 接收端 · 发送端 | 录像阶段约 28.7 KB/s（双 QR、15 FPS） | 暂无统一真机记录；离线解码不宜与实时速率直接比较 |
| V5 libcimbar iOS 版 | 用原生 App 提高彩色矩阵接收稳定性 | 网页端使用 libcimbar 彩色符号、Reed–Solomon、交织和 Wirehair 喷泉码；iOS App 提供相机权限管理、屏幕常亮、4 路 WASM 解码、沙盒保存和系统分享 | 使用 iPhone 接收彩色高密度光码，希望减少普通移动网页的生命周期与权限限制 | 15 FPS 发送端 · 接收端使用 QRREC V5 iOS App | 约 109.9 KB/s（7.5 KB × 15 FPS） | 约 35–40 KB/s |
| V5.1 原生 C++ 版 | 去掉 WebView/WASM 接收瓶颈 | AVFoundation 直接采集 1080p NV12，原生 C++ libcimbar/OpenCV 解码；3 路解码、60 FPS 采样、实时性能指标、App 内结果与手动保存 | 在真机上继续提高 libcimbar 吞吐量并观察原生解码性能 | 20 FPS 发送端 · 接收端使用 QRREC V5.1 iOS App | 约 146.5 KB/s（7.5 KB × 20 FPS） | 131.4 KB/s（最新真机测试） |
| V5.2 全屏显示版 | 验证更大光码对定位率和吞吐量的影响 | 保持 V5.1 编码与原生解码链路不变；开始传输后自动请求浏览器全屏，让彩色矩阵占满可用视口 | 对照测试显示面积、拍摄距离、未定位帧与有效解码 FPS | 全屏发送端 · 接收端沿用 QRREC V5.1 App | 约 146.5 KB/s（7.5 KB × 20 FPS） | 180 KB/s（B 模式真机测试） |
| V5.3 最高压缩版 | 减少需要通过光码发送的数据量 | 保留 V5.2 全屏模式，发送前使用 zstd 22 级无损压缩，接收完成后自动解压并恢复原文件名 | 文本、日志、CSV、源码和未压缩数据；已压缩媒体收益有限 | 本地 V5.3 发送端 · 接收端沿用 QRREC V5.1 App | 光学上限不变；有效文件速率取决于压缩比 | 待真机测试 |
| V5.4 光学条件优化版 | 用显示与取景小技巧提高有效解码率 | 92% 安全取景、黑色外围、控制按钮自动隐藏、首帧保持约 1 秒完成定位与曝光 | 与 V5.3 做同文件 A/B 测试，验证未定位帧和有效解码 FPS | 本地 V5.4 发送端 · 接收端沿用 QRREC V5.1 App | 约 146.5 KB/s 光学载荷上限，另叠加压缩收益 | 待真机测试 |
| V6 RaptorQ 标准 QR 高速版 | 用标准二维码建立跨平台高速通道 | RaptorQ WASM、V20/V30、1/2/4 QR、最高 30 FPS、CRC32C、Balanced repair 调度、Worker 预渲染与最新帧背压 | 希望使用浏览器接收，并测试标准 QR 的最高持续传输速率 | 本地 V6 接收端 · 本地 V6 发送端 | 默认计划速率约 167.6 KiB/s（V30-L × 4 QR @ 30 FPS、20% repair） | 合成全链路 167.6 KiB/s；真机待测试 |
**速率口径：**从 V6 起，版本主速率统一为“原始文件大小 ÷ 第一个有效唯一数据包至文件重建、解压完成的时间”，排除授权相机、举起手机和初始对焦等用户操作时间。页面另保留唯一载荷接收率作为诊断指标。V1–V5.4 表中的旧实测值是历史数据，其中 V5/V5.1/V5.2 按成功解码帧载荷统计，可能包含重复帧，不能与 V6 主速率直接比较；后续真机复测时再逐步统一。
- 优先稳定、第一次使用：选择 V1。
- 想用标准二维码获得更高实时速度：选择 V2。
- 想查看更多实时指标，或测试彩色矩阵：选择 V3。
- 实时解码容易掉帧，但手机录像清晰：选择 V4。
- 使用 iPhone，并希望用 App 接收 libcimbar 彩色矩阵：选择 V5。
- 希望测试真正的 AVFoundation + C++ 原生接收链路：选择 V5.1。
- 希望测试全屏大尺寸光码能否继续提高有效识别率：选择 V5.2。
- 希望通过最高等级压缩减少发送数据量：选择 V5.3。
- 希望测试无遮挡、安全边框和首帧校准：选择 V5.4。
- 希望通过浏览器测试标准 QR、RaptorQ 和四码并行的高速路线：选择 V6。
不同版本和不同通道的封装或协议可能不兼容，请始终使用同一版本、同一模式的发送端和接收端。
- 在电脑或另一块较亮的屏幕上打开某个版本的发送端。
- 选择需要发送的图片、视频、文档或压缩包。
- V1–V4 在手机浏览器打开相同版本的接收端；V5/V5.1 在 iPhone 上运行对应的 QRREC App。首次使用时允许摄像头权限。
- 让二维码或彩色矩阵完整进入取景框，保持画面稳定并避免反光。
- 接收完成后可在本地预览支持的媒体，并手动下载文件。
摄像头权限通常要求 HTTPS；localhost 本地开发环境除外。
V1 保留项目最基础、直接的实时光学传输路径：发送端持续生成喷泉编码 QR 帧，接收端通过摄像头扫描并重组文件。它适合作为兼容性基准，也方便在 V2/V3 参数过于激进时回退使用。
- 单路动态二维码，画面更大、更容易识别。
- LT 喷泉码允许乱序接收并容忍丢帧。
- 使用哈希验证重组后的文件是否正确。
- 文件编码、解码、预览和下载都在浏览器本地完成。
- 支持图片、视频、文本或网址等结果预览。
V2 在标准 QR 路径上增加双码并行、压缩和接收端性能优化。
- 自适应高速参数：发送端根据显示能力选择载荷密度和帧率；接收端会在定位困难时提高解码分辨率，并在持续成功后降低开销。
- 双 QR 模式：左右两个二维码同时承载独立喷泉帧；识别困难时仍可切换单码模式。
- 稳定帧检测：定位成功后，提前丢弃模糊、过渡或残影明显的画面，减少无效 WASM 解码。
- 双 ROI 解码：先进行全画面搜索，再把两个二维码区域交给独立 Worker 并行处理，减少每次扫描的像素量。
- 透明压缩：仅当 gzip 确实能缩小文件时才启用，接收端自动解压并验证原始数据。
- 本地结果展示：图片、视频、文本和网址可直接预览，下载仍由用户主动触发。
- PWA 接收端：网页外壳可安装并缓存，重复使用更方便；摄像头仍需要安全环境。
V3 不改变 V1/V2，而是在同一页面提供两个相互独立的光学通道。
- 默认面向 30 FPS 显示与采集场景。
- 左右重叠 ROI 搜索和两个并行解码 Worker。
- 稳定帧过滤，减少屏幕刷新边界产生的残影帧。
- 使用 128 点画面指纹避免重复解码同一个显示帧。
- 实时展示有效帧、重复帧、接收进度和估算吞吐量。
- 复用 sz3/libcimbar 的形状/颜色符号、Reed–Solomon 纠错、交织、Wirehair 喷泉码和 zstd 压缩能力。
- 发送端默认 15 FPS，并保留 libcimbar 原有的轻微位置抖动；该抖动用于帮助接收端排除跨帧残影，不是普通二维码动画错误。
- 接收端展示传输速率、已用时间、进度、采集/提交、有效帧、未识别、定位丢弃和解码错误。
- 文件接收完成后停止继续解码；图片和视频可直接在页面中预览。
- 彩色矩阵与 QRREC 的标准 QR 通道协议不兼容，发送和接收两端必须同时选择“彩色矩阵”。
彩色矩阵运行层采用 MPL-2.0 许可证，并与 QRREC 的 MIT 源码分开放置。固定的上游提交、许可证和集成修改记录见 v3/color/NOTICE.md 与 v3/color/LICENSE.libcimbar。
V4 将摄像头采集和二维码解码拆成两个阶段，避免实时解码性能影响录像质量。
- 发送端预先生成有限、可本地验证的喷泉帧集合，并循环播放。
- 页面显示完整循环时长和建议录像时长，默认额外保留 3 秒边缘余量。
- 接收端录像时不进行繁重的条码识别，停止后立即释放摄像头。
- 支持直接录制摄像头画面，也支持导入设备中已有的录像。
- 本地视频按 30 FPS 采样并交给 WASM Worker 解码。
- 喷泉解码器一旦重组并校验成功，会提前停止后续视频分析。
- 完成后支持图片、视频预览和文件下载。
V5 保留 V3 的暗色视觉语言，但只保留 libcimbar 彩色矩阵通道。发送端仍是网页，接收端改为 SwiftUI iOS App。
- 发送端复用已验证的 libcimbar WebAssembly 编码运行层，支持 B、Bm、Bu 和 4C 模式以及 5–20 FPS。
- 码制包含形状与颜色符号、Reed–Solomon 纠错、单元交织、透视提取、色彩适应和 Wirehair 喷泉码。
- iOS App 通过内置 WebKit/WASM 解码核心保持与网页发送端兼容，并使用原生相机授权和 App 生命周期管理。
- App 接收期间禁止系统自动锁屏；完成的文件保存到沙盒临时目录并打开系统分享面板。
- 上游 C++ 原生编译依赖 iOS OpenCV 工具链；当前下载的 libcimbar 仓库没有携带该依赖，因此 V5 首版采用可编译、兼容现有码流的混合原生架构。
- V5 没有网页接收地址，发送页面会明确提示使用 QRREC V5 iOS App。
工程和真机运行说明见 v5/README.md。
V5.1 保留 V5 的码流和界面风格，但建立独立的 20 FPS 网页发送入口与 iOS 工程。相机通过 AVFoundation 以最高 1080p/60 FPS 直接输出 NV12，帧数据进入 3 路本地 libcimbar/OpenCV C++ 解码器，不再经过 WKWebView、Canvas、JavaScript 或 WASM。文件完成后先显示在 App 内，由用户点击保存。构建依赖和使用方法见 v5.1/README.md。
V5.2 沿用 V5.1 的 20 FPS libcimbar 码流和原生 iOS 接收端，只改变发送画面的空间利用率。点击开始后浏览器会尝试进入系统全屏，隐藏设置区并把彩色矩阵铺满可用视口；结束传输或退出全屏后恢复设置界面。当前真机测试中，普通 B 模式可用，App 显示接收速率达到 180 KB/s；Bm 矩形模式未能正常接收，暂不推荐。说明见 v5.2/README.md。
单向光学链路没有实用的重传通道。自动对焦、设备移动、屏幕刷新边界和解码器负载都可能导致帧丢失。
QRREC 把数据拆成源块，再依据 Robust Soliton 分布持续发送确定性的异或组合，也就是 LT 喷泉编码。接收端只需收集足够多的不同有效帧，不要求顺序连续。漏掉一帧通常只会增加接收时间，不会直接造成文件损坏，也不会依赖容易与摄像头采样周期同步冲突的固定帧序列。
标准 QR 通道的每帧带有紧凑的 20 字节二进制头，包含会话 ID、序列号、源块数量、块大小、总载荷长度和哈希。序列号用于在两端确定性地选择相同源块，而不只是循环帧的索引。
文件 → 可选 gzip → 文件封装 → 源数据块 → Robust Soliton LT 编码
→ 单个/两个动态二维码 → 摄像头 → 稳定帧过滤 → 全画面定位
→ ROI Worker → ZXing WASM → LT 剥离解码 → 哈希校验
→ 可选 gunzip → 浏览器预览 / 手动下载
Safari 没有提供可靠的跨浏览器原生 QR 解码器，因此接收端通过 zxing-wasm 在 Web Worker 中运行 zxing-cpp。网页版本把 WASM 作为可独立缓存的资源加载；针对某些不允许单独托管 .wasm 的宿主，也保留了将 WASM 内嵌进 JavaScript 的构建方式。
环境要求：Node.js 20 或更高版本，以及现代浏览器。
npm install
npm run dev生产构建：
npm run build:webV5 网页发送端单独启动或构建：
npm run dev:sender:v5
npm run build:sender:v5iOS 接收端使用 Xcode 打开 v5/ios/OpticalReceiverV5/OpticalReceiverV5.xcodeproj，配置 Development Team 后安装到真实 iPhone。模拟器可用于编译和界面检查，但不能完成真实相机传输验证。
V5.1 首次构建先运行 v5.1/scripts/prepare_native_ios.sh，再打开 v5.1/ios/OpticalReceiverV51/OpticalReceiverV51.xcodeproj。V5.1 当前仅支持 iPhone arm64 真机。
静态文件会生成到 release/web-receiver，主要路由如下：
/与/send/：V1 接收端与发送端。/v2/与/v2/send/：V2 接收端与发送端。/v3/与/v3/send/：V3 接收端与发送端，页面内可切换高速双 QR 和彩色矩阵。/v4/与/v4/send/：V4 录像接收端与固定循环双 QR 发送端。/v5/send/：V5 libcimbar 网页发送端；接收端为 iOS App，不提供网页接收路由。/v5.1/send/：V5.1 原生 C++ iOS App 配套发送端，默认 20 FPS；识别环境不稳定时可手动降为 15 FPS。/v5.2/send/：V5.2 全屏彩色光码发送端，默认 20 FPS；接收端沿用 V5.1 原生 iOS App。
手机调试摄像头时需要 HTTPS 开发地址；普通局域网 HTTP 地址通常无法获得摄像头权限。
实际速度取决于屏幕刷新率、亮度、反光、二维码尺寸、摄像头曝光与对焦、设备性能、Worker 调度，以及文件是否容易压缩。
V2 默认使用稳定双码配置：20 个显示节拍/秒、每码 1000 字节；当单码显示面积足够大时可自动提高到 1465 字节。如果识别不稳定，可尝试改成单码、降低单帧字节数或帧率、增大二维码显示面积，并提高屏幕亮度。
双 QR 能提高发送端提供的数据量，但不保证有效速度严格翻倍，因为两个二维码都必须保持足够大且清晰。实时指标中的采集帧、成功解码、新帧/重复帧、过滤帧、ROI 状态和估算速率，更适合用来判断真实瓶颈。
V3 彩色矩阵是实验通道。它的识别效果对屏幕、摄像头、距离、反光和刷新残影更敏感；默认的轻微位置变化属于上游定位策略，不建议关闭。
- QRREC 不上传文件内容；编码、解码、解压、校验和预览都在本地浏览器完成。
- 首次打开在线页面仍需要正常网络连接来加载网页、JavaScript 和 WASM 资源。
- 任何能够看到并完整录制动态光码的人，都可能重组文件；光学传输本身不等于加密。
- 各版本应配套使用；不要混用不同版本或不同通道的发送端与接收端。
- V2、V3 和 V4 包含实验性性能路径，遇到兼容性问题时可回到 V1。
- V5 需要 iOS 16 或更高版本，并应在真实 iPhone 上测试相机传输。
本项目基于原始的 MIT 许可 Decimen Optical Transfer 概念验证，保留其紧凑二进制协议、确定性喷泉编码与纯光学传输设计。界面、PWA 和预览流程参考了 Qrs。相关项目包括 txqr、airgapped-qr-code-transfer 和使用高密度彩色条码的 libcimbar。
主要依赖：node-qrcode、zxing-wasm 和 fflate。
QRREC 自有源码使用 MIT 许可证，详见 LICENSE。v3/color/ 下独立分发的 libcimbar 浏览器运行层使用 MPL-2.0，详见 THIRD_PARTY_NOTICES.md。