参考 libcimbar 做的一个实现，1m 40秒能传输完成

[1123Javayanglei]

参考 libcimbar 做的一个实现，1m 40秒能传输完成，css 风格统一

[1123Javayanglei]

Cimbar 传输助手使用说明

📖 简介

Cimbar 传输助手是一个基于视觉二维码的文件传输工具，通过摄像头扫描屏幕上的动态二维码实现文件传输。无需网络连接，完全离线可用。

⚡ 传输速度

• 典型速度：1MB 文件约需 40 秒 传输完成
• 影响因素：
  • 摄像头质量和对焦速度
  • 光线条件
  • 屏幕刷新率
  • 编码模式选择

🌐 浏览器兼容性

✅ 推荐浏览器

macOS / Windows / Linux

• Chrome（推荐）
• Firefox
• Edge
• Safari（macOS）

iOS / iPadOS

• Chrome for iOS（强烈推荐）
• Firefox for iOS
• Edge for iOS

⚠️ 重要提示：iOS Safari 浏览器存在兼容性问题，不建议使用。请使用 Chrome、Firefox 或 Edge 的 iOS 版本。

Android

• Chrome for Android（推荐）
• Firefox for Android
• CFC Android App（官方客户端，性能最佳）

📱 移动端优化建议

iOS 用户

1. 必须使用 Chrome/Firefox/Edge，不要使用 Safari
2. 确保授予摄像头权限
3. 保持设备稳定，避免抖动
4. 在光线充足的环境下使用

Android 用户

1. 推荐使用 CFC Android App
   • 专为 Cimbar 优化
   • 更好的解码性能
   • 更低的功耗
2. 如果使用浏览器，Chrome 是最佳选择

🚀 使用步骤

发送文件

1. 点击"发送"标签
2. 拖拽文件或点击选择文件
3. 选择编码模式：
   • B：稳定模式（默认推荐）
   • Bm：改进模式
   • Bu：高对比度模式
   • 4C：高密度模式（速度快但要求高）
4. 调整帧率（5-20 FPS，默认 15）
5. 点击"开始编码传输"
6. 将屏幕朝向接收端摄像头

接收文件

1. 点击"接收"标签
2. 点击"启动摄像头"
3. 授予摄像头权限
4. 将摄像头对准发送端屏幕
5. 等待自动解码和下载
6. 文件会自动保存到下载文件夹

💡 优化建议

提高传输速度

1. 选择合适的编码模式

   • 小文件（< 1MB）：使用 B 或 Bm 模式
   • 大文件：尝试 4C 模式（如果摄像头质量好）

2. 调整帧率

   • 高性能设备：15-20 FPS
   • 普通设备：10-15 FPS
   • 低性能设备：5-10 FPS

3. 优化环境

   • 确保充足的光线
   • 避免屏幕反光
   • 保持摄像头稳定
   • 清洁摄像头镜头

提高成功率

1. 对准技巧

   • 保持适当距离（20-50cm）
   • 确保二维码完整出现在画面中
   • 避免过度倾斜角度

2. 设备设置

   • 关闭自动亮度调节
   • 提高屏幕亮度
   • 启用摄像头自动对焦

🔧 技术细节

工作原理

1. 发送端将文件编码为动态二维码序列
2. 每个二维码包含一部分数据（使用喷泉码技术）
3. 接收端通过摄像头扫描二维码
4. 自动重组和解压缩文件

编码模式对比

模式	稳定性	速度	适用场景
B	⭐⭐⭐⭐⭐	⭐⭐⭐	通用场景，最稳定
Bm	⭐⭐⭐⭐	⭐⭐⭐⭐	平衡性能和稳定性
Bu	⭐⭐⭐⭐⭐	⭐⭐⭐	低对比度环境
4C	⭐⭐⭐	⭐⭐⭐⭐⭐	高质量摄像头，追求速度

❓ 常见问题

Q: 为什么传输速度慢？

A: 可能原因：

• 摄像头质量差或对焦慢
• 光线不足
• 选择了过于密集的编码模式
• 设备性能较低

Q: 为什么解码失败？

A: 可能原因：

• 摄像头未对准
• 距离太远或太近
• 屏幕反光或眩光
• 使用了不兼容的浏览器（如 iOS Safari）

Q: 文件传输中断怎么办？

A:

• 点击"重置"按钮重新开始
• 检查摄像头是否被遮挡
• 确保发送端持续显示二维码

Q: 支持多大的文件？

A: 理论上无限制，但建议：

• 小文件（< 10MB）：体验最佳
• 中等文件（10-50MB）：可以接受
• 大文件（> 50MB）：需要较长时间

📞 支持与反馈

• GitHub: sz3/libcimbar
• Android App: sz3/cfc
• 问题反馈: 请提供浏览器版本、设备型号和具体问题描述

📁 项目文件说明

cimbar-deps/

Cimbar 核心依赖库目录

包含 Cimbar 编解码所需的所有核心文件：

• cimbar_js.2026-01-20T0312.js - WebAssembly 模块（编码+解码）
• cimbar_js.2026-01-20T0312.wasm - WASM 二进制文件
• main.2026-01-20T0312.js - 发送端编码逻辑
• recv.2026-01-20T0312.js - 接收端解码逻辑
• recv-worker.2026-01-20T0312.js - Worker 解码进程
• zstd.2026-01-20T0312.js - Zstandard 压缩算法
• tailwind.min.js - Tailwind CSS 框架（本地化）
• vconsole.min.js - vConsole 调试工具（本地化）

💡 这些文件从原始 Cimbar 项目复制而来，进行了路径适配以支持本地部署。

cimbar-deps-start/

HTTPS 服务器证书目录

包含 HTTPS 服务所需的 SSL 证书：

• cert.pem - SSL 证书文件
• key.pem - SSL 私钥文件

⚠️ 重要：现代浏览器要求摄像头访问必须使用 HTTPS 协议。此目录中的自签名证书用于本地开发测试。

https_server.py

Python HTTPS 服务器脚本

一个简单的 Python HTTP 服务器，提供以下功能：

主要特性

1. HTTPS 支持 - 使用 SSL 证书加密通信
2. 静态文件服务 - 托管 cimbar-transfer.html 及相关资源
3. 状态管理 API - 提供文件传输进度跟踪接口

API 端点

• GET /get_status - 获取当前传输状态
• POST /update_progress - 更新接收进度
• POST /request_frame - 请求特定帧
• POST /reset - 重置传输状态

启动方式

python3 https_server.py

服务器将在 https://0.0.0.0:4443 启动，可通过以下地址访问：

• https://localhost:4443/cimbar-transfer.html
• https://<你的IP>:4443/cimbar-transfer.html

🔒 为什么需要 HTTPS？

• 浏览器安全策略要求摄像头访问必须使用 HTTPS
• 自签名证书会在首次访问时显示安全警告，点击"高级"→"继续访问"即可
• 生产环境应使用正式的 SSL 证书

📄 许可证

本项目基于 libcimbar 开发，遵循相应的开源许可证。

---

提示：为了获得最佳体验，请确保使用推荐的浏览器和设备配置。