esdreiem/usb-endoscope

# USB-Endoscope **一款可安装的、完全本地化的 Web 应用，通过 WebUSB 直接在浏览器中串流 i4season / "Usee Plus" USB 内窥镜画面——这是一个开放、注重隐私的替代方案，用于取代设备专有的配套应用程序。** 🇬🇧 英文 | [🇩🇪 德文](README.de.md) [](LICENSE) [](manifest.webmanifest) [](sw.js) [](index.html) [](#how-it-works)  ## 它是什么 廉价的 USB 内窥镜通常需要依赖专有的配套应用程序才能工作。本项目是它的一个完全本地化的替代方案：**一款可安装的 Web 应用，无需构建步骤，无依赖，且没有任何网络请求。** 摄像头画面永远不会离开您的设备。 它只做一件事：通过 **WebUSB** 连接 **i4season / "Usee Plus"** USB 内窥镜（USB `VID 0x2ce3` / `PID 0x3828`，以 "Geek szitman useepluscam" 名称销售）并显示其实时视频——无需原生应用，无需厂商软件。 ## 工作原理 这款内窥镜**不是**标准的 **UVC** (USB Video Class) 设备。正因如此，您的操作系统绝不会将其视为网络摄像头，浏览器也无法使用常规的 camera API 打开它——这正是厂商转而提供专有 Android 应用的原因。 因此，该应用采取了不同的路径：它通过 **WebUSB** 声明了设备的厂商接口，并直接在浏览器中使用**逆向工程的厂商协议**进行通信。在实践中，这意味着通过两个简单的厂商 **control transfers** 来启动流，然后通过 bulk endpoint `0x82` 读取原始的 **YUYV422** 帧，并将它们转换为 canvas 上的 RGB。 完整的故事、截图以及精确的协议常量位于 **[docs/REVERSE_ENGINEERING.md](docs/REVERSE_ENGINEERING.md)** 和 **[PROTOCOL_NOTES.md](PROTOCOL_NOTES.md)**。 ## 将其安装为应用 USB-Endoscope 是一款可安装的 **Progressive Web App (PWA)**： - 出现时点击页眉中的 **⤓ Installieren** 按钮，或使用浏览器地址栏中的**安装图标**。 - 安装后，它可以运行在主屏幕/桌面上，并支持**完全离线**工作——service worker 会缓存应用外壳，并且依然没有任何外部请求。 - 在 **iOS / iPadOS** 上，您可以通过 Safari 的**“添加到主屏幕”**将其添加到主屏幕，但请注意，它**无法进行串流**——iOS 上没有任何浏览器支持 WebUSB（请参阅[平台支持](#platform-support)）。 ## 功能 - **实时预览** —— 插入已知的内窥镜时会自动连接 - 📷 **照片拍摄** —— JPEG，带有时间戳的文件名 - ⏺ **视频录制** —— WebM - ⏸ **定格画面** —— 在探头晃动时非常实用 - ↻ **旋转** / ⇋ **镜像** —— 内窥镜图像经常是倒置的；变换也会应用于保存的照片 - 🔍 **数字变焦** - ⛶ **全屏** - ⤓ **可安装/离线工作** —— 作为 PWA ## 快速开始 WebUSB 需要**基于 Chromium 的浏览器**和**安全上下文**：`https://` 或 `http://localhost`。双击直接打开 `index.html`（`file://`）会被浏览器阻止，因此请在本地提供托管服务。 ### 在 PC / 笔记本电脑上 插入内窥镜，然后运行： ``` git clone https://github.com/esdreiem/usb-endoscope.git cd usb-endoscope python3 -m http.server 8000 # → 在 Chrome / Edge / Brave 中打开 http://localhost:8000 ``` 按 **Verbinden** (连接) 开始串流，按 **Stopp** 停止串流。 ### 或者使用托管版本 该应用通过 **GitHub Pages** 进行静态托管——它依然不会发出任何网络请求，因此图像会保留在本地： **** ## 平台支持 WebUSB 是一个**仅限 Chromium** 的 API，因此支持与否完全取决于浏览器引擎。 | 平台 | 浏览器 | WebUSB 串流 | 备注 | |---|---|---|---| | **桌面端** (Windows / macOS / Linux) | Chrome, Edge, Brave, Opera | ✅ 可用 | 推荐的使用方式。 | | **桌面端** | Firefox | ❌ 不支持 | Mozilla 拒绝实现 WebUSB。 | | **桌面端** | Safari | ❌ 不支持 | 无 WebUSB 支持。 | | **Android** | Chrome / Chromium | ✅ 可用 | 任何基于 Chromium 的 Android 浏览器均可。 | | **iOS / iPadOS** | 任何浏览器 | ❌ 不支持 | 所有 iOS 浏览器都被强制使用 WebKit，因此都不支持 WebUSB——您可以安装该 PWA 但无法串流。 | 在非 Chromium 浏览器中，该应用会显示明确的**“在 Chrome / Edge / Brave 中打开”**消息，而不是毫无反应的 UI。无论哪种情况，都需要**安全上下文**（`https://` 或 `http://localhost`）。 ## 支持的设备 | 设备 | VID / PID | 接口 | 状态 | |---|---|---|---| | i4season "Usee Plus" — "Geek szitman useepluscam" (型号 `su4p-002`) | `0x2ce3` / `0x3828` | WebUSB 厂商协议 | ✅ 已测试 | 有**不同厂商的内窥镜**？请帮助我们添加它——请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## WebUSB 协议是如何被逆向工程的 "Usee Plus" 内窥镜的 USB descriptors 公布了名为 `iAP Interface` 和 `com.useeplus.protocol` 的厂商接口——而不是 UVC——这使得调查经历了一些复杂的死胡同（旧版的 "BB AA" / MJPEG bulk protocol，然后又深入绕道至 Apple 的 iAP2 配件握手）。突破来自于一部已 root 的手机和对原生 `USBDEVFS` ioctl 接口的 Frida hook，捕获了**真正的** Android 应用实际上通过 USB 发送的内容。结果发现它只是两个简单的厂商 control transfers，随后是原始的 YUYV422 bulk 读取——花哨的握手协议一直都是障眼法。 完整的故事、截图以及精确的协议常量位于 **[docs/REVERSE_ENGINEERING.md](docs/REVERSE_ENGINEERING.md)** 和 **[PROTOCOL_NOTES.md](PROTOCOL_NOTES.md)**。 ## 隐私 隐私是本项目的核心目标，而不是事后补充： - **自包含** —— 没有外部或第三方请求，没有 CDN 字体，没有分析工具。所有 assets 都是同源的 (same-origin)。 - **完全离线可用** —— 一旦作为 PWA 安装，它完全不需要网络即可工作。 - **摄像头图像永远不会离开您的设备。** - 照片 (JPEG) 和视频 (WebM) **仅作为本地下载**保存。 - 整个源代码都是可读且可审计的——从 [`index.html`](index.html) 开始查看。 ## 免责声明 这是一个独立的、非官方的项目——**不附属于、未受认可于，也未与** i4season、"Usee Plus"、"Geek szitman" 或任何内窥镜制造商有关联。产品和公司名称是其各自所有者的商标，仅用于识别兼容硬件（ nominative fair use ）。 此处的 WebUSB 协议是为了**互操作性**而逆向工程的——以便您使用受您自己控制的软件来操作您拥有的内窥镜。不包含任何专有的厂商代码。该软件在 GPL-3.0-or-later 许可下“按原样”提供，不提供任何形式的担保；您需自行承担使用风险。 ## 许可证 基于 **GPL-3.0-or-later** 获得许可。完整文本请参见 [LICENSE](LICENSE)。 Copyright © 2026 [esdreiem](https://github.com/esdreiem).

标签：WebUSB, 云资产清单, 前端工具, 可安装网页应用, 后端开发, 图像处理, 数据可视化, 本地应用, 视频流, 逆向工程