# ws-server

**Repository Path**: huanf/ws-server

## Basic Information

- **Project Name**: ws-server
- **Description**: 本项目实现了一个基于 Spring Boot + WebSocket 的实时视频推流/播放服务，前端提供了发送端页面与播放端页面，用于视频数据的采集与播放。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-15
- **Last Updated**: 2025-08-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# WebSocket 视频传输

本项目实现了一个基于 **Spring Boot + WebSocket** 的实时视频推流/播放服务，前端提供了发送端页面与播放端页面，用于视频数据的采集与播放。

## 📖 使用场景

1. **分支说明**
  - master分支存放最简版的代码，建议基于master分支进行二次开发
  - param_deviceId分支是二次开发分支，示例如何携带deviceId参数
  - param_deviceId_netty分支是二次开发分支，示例如何携带deviceId参数，并把websocket替换为netty

2. **发送端**
  - 硬件模块或其它接入方与 `ws://localhost:6011/video/sender` 建立连接后，即成为发送端
  - 可以直接发送二进制视频帧数据

3. **播放端**
  - 硬件模块或其它接入方与 `ws://localhost:6011/video/viewer` 建立连接后，即成为播放端
  - 可以实时接收到二进制视频帧并播放

4. **多端支持**
  - 多个发送端：播放端会同时接收来自多个发送端的数据
  - 多个播放端：所有播放端都会接收到所有发送端的数据

---

## 🚀 快速使用

- **发送端**：[http://localhost:6011/sender.html](http://localhost:6011/sender.html)
- **播放端**：[http://localhost:6011/viewer.html](http://localhost:6011/viewer.html)
- **注意！注意！注意！**：param_deviceId_netty分支的html页面端口不是6011，是6012

操作步骤：
1. 打开一个浏览器标签页，进入 **发送端** 页面
  - 上传视频
  - 点击 **“连接 WebSocket”**
  - 点击 **“开始发送”**
2. 打开另一个浏览器标签页，进入 **播放端** 页面
  - 可以直接看到实时播放的视频（边传边播）

---

## 🔍 工作原理

- 发送端将视频切分为一帧帧的 **二进制数据**
- 通过 WebSocket 推送给服务端
- 服务端将二进制帧广播给所有连接的播放端
- 播放端接收帧并解码渲染，实现实时播放

---

## 🌟 项目优点

- **结构简洁**：整个项目只有两个类，逻辑清晰易读，自带前端页面秒上手
- **轻量化**：没有心跳、鉴权或复杂参数传递，启动快速
- **高可扩展性**：可根据需求轻松添加功能，例如多通道管理、鉴权、带参数的消息处理等
- **实时性能好**：支持多发送端、多播放端的实时视频推流

---

## ⚙️ 后端说明

### 1. 启动类

`WsServerApplication.java`  
标准 Spring Boot 启动类，运行后启动 WebSocket 服务。

### 2. WebSocket 配置

`RawWebSocketConfig.java`
- 注册两个端点：
    - `/video/sender` → 发送端
    - `/video/viewer` → 播放端
- 设置了大容量缓冲区与超时参数：
    - 文本/二进制消息最大 `2MB`
    - 发送超时 `60s`
    - session 不自动过期

### 3. WebSocket 处理器

`VideoWebSocketHandler.java`
- **会话角色判定**：根据连接路径区分 **sender** 和 **viewer**。
- **发送端**：上传二进制帧数据（图片帧）。
- **播放端**：接收并显示来自发送端的最新帧。
- **广播逻辑**：
    - 最近一帧数据会缓存（`lastFrameBytes`）
    - 新 viewer 连接时会立即下发最近一帧
    - 使用线程池异步广播，避免阻塞 IO

---

## 🖥️ 前端说明

### 1. 发送端 `sender.html`

- 功能：
    - 选择本地视频文件
    - 将视频逐帧转换为 `JPEG` 图像并通过 WebSocket 推送到 `/video/sender`
- 特性：
    - 支持 **requestVideoFrameCallback**（兼容 Fallback setInterval 捕获）
    - 实时显示发送状态、速率、帧数
    - 日志面板支持过滤、批量刷新、清空

### 2. 播放端 `viewer.html`

- 功能：
    - 连接 `/video/viewer`
    - 接收二进制帧（JPEG）并绘制到 `<canvas>`
- 特性：
    - 使用 `createImageBitmap` 提升绘制效率
    - 实时显示接收帧率、带宽
    - 日志支持批量刷新和过滤

---