# sysdvr_websocket_webusb

**Repository Path**: sunshinewithmoonlight/sysdvr_websocket_webusb

## Basic Information

- **Project Name**: sysdvr_websocket_webusb
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-30
- **Last Updated**: 2025-12-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SysDVR WebSocket & WebUSB 客户端

这是 SysDVR 的现代化网页客户端实现，支持 WebSocket 和 WebUSB 两种连接方式，提供低延迟、高流畅度的 Switch 视频音频串流体验。

## 📋 项目概述

### 核心特性

- **🌐 WebSocket 连接** - 远程网络连接，支持跨网络访问
- **🔌 WebUSB 连接** - 本地 USB 连接，超低延迟（< 50ms）
- **🎬 H.264 视频解码** - 硬件加速，支持 30-60 FPS
- **🔊 AAC 音频播放** - 高保真音频，支持多采样率
- **📊 智能缓冲机制** - 自适应缓冲，吸收网络波动
- **🎚️ 音视频同步** - 基于时间戳的精确同步
- **📈 实时监控面板** - 显示缓冲帧数和视频帧率

### 架构设计

```
┌─────────────────────────────────────────────────────┐
│              Vue3 Web Application                    │
│  ┌─────────────────────────────────────────────┐   │
│  │         UI Components                        │   │
│  │  - ConnectionPanel (连接控制)                │   │
│  │  - StreamSettings (串流设置)                 │   │
│  │  - LatencyMonitor (延迟监控)                 │   │
│  └─────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────┐
│         Service Layer (核心服务)                    │
│  ┌──────────────┐  ┌──────────────┐                │
│  │ WebSocket    │  │ WebUSB       │                │
│  │ Connection   │  │ Connection   │                │
│  └──────────────┘  └──────────────┘                │
│         ↓                  ↓                         │
│  ┌──────────────────────────────────┐              │
│  │  ConnectionManager (单例)         │              │
│  │  - 连接管理                       │              │
│  │  - 统计信息                       │              │
│  │  - 音视频同步                     │              │
│  └──────────────────────────────────┘              │
│         ↓                  ↓                         │
│  ┌──────────────┐  ┌──────────────┐                │
│  │ VideoDecoder │  │ AudioPlayer  │                │
│  │ - H.264 解码 │  │ - AAC 播放   │                │
│  │ - 缓冲管理   │  │ - 缓冲管理   │                │
│  │ - 帧同步     │  │ - 音频同步   │                │
│  └──────────────┘  └──────────────┘                │
└─────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────┐
│         Browser APIs                                 │
│  - WebCodecs (视频解码)                             │
│  - Web Audio API (音频播放)                         │
│  - WebSocket (网络连接)                             │
│  - WebUSB (USB 连接)                                │
└─────────────────────────────────────────────────────┘
```

## 🚀 快速开始

### 前置要求

- Node.js 16+ 和 npm
- 现代浏览器（Chrome/Edge/Safari）
- SysDVR 服务端（Switch 上运行）

### 安装与运行

```bash
# 1. 安装依赖
npm install

# 2. 启动开发服务器
npm run dev

# 3. 打开浏览器访问
# http://localhost:5175

# 4. 输入 Switch IP 地址并连接
```

### 生产构建

```bash
# 构建生产版本
npm run build

# 预览生产构建
npm run preview
```

## 📁 项目结构

```
.
├── src/
│   ├── services/                    # 核心服务模块
│   │   ├── websocket.js             # WebSocket 连接管理
│   │   ├── webusb.js                # WebUSB 连接管理
│   │   ├── connectionManager.js     # 连接管理器（单例）
│   │   ├── videoDecoder.js          # H.264 视频解码
│   │   └── audioPlayer.js           # AAC 音频播放
│   ├── components/                  # Vue 组件
│   │   ├── ConnectionPanel.vue      # 连接控制面板
│   │   ├── StreamSettings.vue       # 串流设置
│   │   └── LatencyMonitor.vue       # 延迟监控
│   ├── App.vue                      # 主应用组件
│   └── main.js                      # 应用入口
├── SysDVR/                          # 服务端代码
│   ├── sysmodule/                   # Switch 模块
│   │   └── source/modes/
│   │       ├── WebSocketmode.c      # WebSocket 模式实现
│   │       └── WebUSBmode.c         # WebUSB 模式实现
│   └── SysDVRConfig/                # 配置工具 (NRO)
├── package.json                     # 项目配置
├── vite.config.js                   # Vite 配置
└── README.md                        # 本文件
```

## 🔧 核心功能说明

### WebSocket 连接

**特点**：
- 远程网络连接，支持跨网络访问
- 自动心跳检测（Ping-Pong）
- 双通道设计（视频 + 音频）

**使用场景**：
- 远程串流
- 不同网络环境
- 公网访问

**连接流程**：
```
1. 输入 Switch IP 地址
2. 创建视频 WebSocket 连接
3. 创建音频 WebSocket 连接
4. 服务端验证并返回数据
5. 客户端接收并处理数据
```

### WebUSB 连接

**特点**：
- 本地 USB 连接，超低延迟
- 直接 USB 通信，无网络开销
- 仅支持本地连接

**使用场景**：
- 本地直连
- 极低延迟需求
- 游戏操作

**连接流程**：
```
1. 点击"选择 USB 设备"
2. 浏览器显示 USB 设备列表
3. 选择 Switch 设备
4. 建立 USB 连接
5. 开始数据传输
```

### 视频解码

**支持格式**：
- H.264 (AVC)
- 分辨率：1280×720 (720p)
- 帧率：30-60 FPS
- 比特率：自适应

**解码流程**：
```
1. 接收视频数据包
2. 提取 NAL 单元
3. 识别 SPS/PPS（参数集）
4. 等待 IDR 帧（关键帧）
5. 初始化解码器（AVCC 格式）
6. 解码视频帧
7. 缓冲管理（10 帧缓冲）
8. 基于时间戳渲染
```

**缓冲策略**：
- 最小缓冲：2 帧
- 最大缓冲：10 帧
- 渲染延迟：66-330ms（取决于缓冲）

### 音频播放

**支持格式**：
- AAC (Advanced Audio Coding)
- 采样率：48kHz
- 声道：立体声
- 比特率：128-256 kbps

**播放流程**：
```
1. 接收音频数据包
2. 验证包头（Magic: 0xCCCCCCCC）
3. 提取音频数据
4. 缓冲管理（10 块缓冲）
5. 调度播放时间
6. Web Audio API 播放
```

**缓冲策略**：
- 最小缓冲：1 块
- 最大缓冲：10 块
- 自动同步：延迟 > 100ms 时触发
- 积压清理：缓冲 > 5 块时清理

### 音视频同步

**同步机制**：
1. **时间戳同步** - 基于视频帧时间戳
2. **缓冲同步** - 根据视频缓冲帧数调整音频延迟
3. **自动同步** - 延迟过大时自动调整
4. **用户调节** - 通过滑杆手动调整缓冲帧数

**同步参数**：
- 最小缓冲帧数：1-10 帧（用户可配置）
- 每帧延迟：33ms（30 FPS）
- 同步延迟：66-330ms

## 📊 性能指标

### 延迟分析

| 场景 | 延迟 | 说明 |
|------|------|------|
| 本地 USB | < 50ms | WebUSB 直连 |
| 局域网 | 100-200ms | WebSocket + 缓冲 |
| 互联网 | 200-500ms | WebSocket + 缓冲 |

### 缓冲配置

| 配置 | 缓冲帧数 | 延迟 | 流畅度 | 网络抗性 |
|------|---------|------|--------|---------|
| 激进 | 3 帧 | 100ms | ★★★☆☆ | ★★☆☆☆ |
| 平衡 | 5 帧 | 165ms | ★★★★☆ | ★★★☆☆ |
| 保守 | 10 帧 | 330ms | ★★★★★ | ★★★★★ |

**当前配置**：10 帧（保守，优先流畅度）

### 系统要求

| 指标 | 要求 |
|------|------|
| CPU | 双核 2GHz+ |
| 内存 | 2GB+ |
| 网络 | 5Mbps+ |
| 浏览器 | Chrome 94+, Safari 15+, Edge 94+ |

## 🎮 使用指南

### 连接到 Switch

1. **启动 SysDVR 服务端**
   - 在 Switch 上运行 SysDVR 应用
   - 选择 WebSocket 或 WebUSB 模式
   - 记下 Switch 的 IP 地址

2. **打开网页客户端**
   - 访问 http://localhost:5175
   - 或部署到服务器后访问

3. **连接设备**
   - **WebSocket**：输入 Switch IP 地址，点击"连接"
   - **WebUSB**：点击"选择 USB 设备"，选择 Switch

4. **调整设置**
   - 使用"串流设置"卡片调整缓冲帧数
   - 观察"延迟监控"面板的实时数据

### 故障排查

**问题**：无法连接到 Switch
- 检查 Switch IP 地址是否正确
- 确保 Switch 和电脑在同一网络
- 检查防火墙设置

**问题**：视频卡顿或延迟高
- 增加缓冲帧数（通过滑杆）
- 检查网络连接质量
- 关闭其他占用带宽的应用

**问题**：音频不同步
- 调整缓冲帧数
- 等待 0.5 秒让缓冲稳定
- 重新连接

**问题**：WebUSB 不可用
- 确保浏览器支持 WebUSB（Chrome/Edge）
- 检查 USB 连接是否正常
- 尝试重新插拔 USB 线

## 🔌 服务端编译

### 编译 WebSocket 和 WebUSB 模块

```bash
cd /Users/shine/t29/SysDVR
bash ReleaseSysmodule.sh
```

**输出文件**：
- `SysmoduleRelease/SysDVR.zip` - 完整版（包含所有模式）
- `SysmoduleRelease/USB.zip` - USB 专用版

### 编译配置工具

```bash
cd /Users/shine/t29/SysDVR/SysDVRConfig
cargo build --release
```

**输出文件**：
- `target/release/SysDVRConfig.nro` - 配置工具

## 📝 开发指南

### 添加新功能

1. **创建新的服务模块**
   ```javascript
   // src/services/myService.js
   class MyService extends EventEmitter {
     constructor() {
       super();
       // 初始化
     }
     
     myMethod() {
       // 实现功能
       this.emit("event-name", data);
     }
   }
   
   export default new MyService();
   ```

2. **在 ConnectionManager 中集成**
   ```javascript
   import myService from './myService.js';
   
   class ConnectionManager {
     constructor() {
       myService.on("event-name", (data) => {
         // 处理事件
       });
     }
   }
   ```

3. **创建 UI 组件**
   ```vue
   <template>
     <div class="my-component">
       <!-- 组件内容 -->
     </div>
   </template>
   
   <script>
   import connectionManager from '../services/connectionManager.js';
   
   export default {
     name: 'MyComponent',
     // 组件逻辑
   };
   </script>
   ```

### 调试技巧

1. **打开浏览器开发者工具**
   - F12 打开控制台
   - 查看日志输出
   - 使用 Network 标签页检查连接

2. **启用详细日志**
   - 所有服务都有详细的日志输出
   - 日志格式：`[服务名] 事件描述`
   - 使用 emoji 快速识别日志类型

3. **性能分析**
   - 使用浏览器的 Performance 标签页
   - 监控 CPU 和内存使用
   - 检查帧率（FPS）

## 🐛 已知问题和限制

### 浏览器兼容性

| 浏览器 | WebSocket | WebUSB | 状态 |
|--------|-----------|--------|------|
| Chrome | ✅ | ✅ | 完全支持 |
| Safari | ✅ | ❌ | 不支持 WebUSB |
| Firefox | ✅ | ❌ | 不支持 WebUSB |
| Edge | ✅ | ✅ | 完全支持 |

### 已知限制

- WebUSB 仅支持 Chrome 和 Edge
- 单个浏览器标签页只能连接一个设备
- 后台标签页可能被限流
- 某些防火墙可能阻止 WebSocket 连接

## 📚 相关文档

### 客户端文档
- `AUDIO_BUFFER_IMPLEMENTATION_GUIDE.md` - 音频缓冲实现
- `VIDEO_BUFFER_TIMESTAMP_SYNC_IMPLEMENTATION.md` - 视频缓冲实现
- `WEBSOCKET_PING_PONG_REMOVAL_GUIDE.md` - WebSocket 心跳机制

### 服务端文档
- `SysDVR/Readme/` - 服务端完整文档
- `SysDVR/SysDVRConfig/` - 配置工具文档

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

### 提交 Issue

请包含以下信息：
- 问题描述
- 复现步骤
- 浏览器和操作系统版本
- 控制台日志输出

### 提交 PR

1. Fork 本仓库
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📄 许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

## 🔗 相关链接

- [SysDVR 原始项目](https://github.com/exelix11/SysDVR)
- [WebCodecs API 文档](https://www.w3.org/TR/webcodecs/)
- [Web Audio API 文档](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API)
- [WebUSB 文档](https://wicg.github.io/webusb/)

## 📞 支持

如有问题，请：
1. 查看本 README 的故障排查部分
2. 查看相关文档
3. 提交 Issue
4. 联系开发者

---

**最后更新**：2025 年 11 月 30 日
**版本**：1.0.0