# WebRTC 直播组件说明

## 概述

`WebRTCVideo` 是一个基于 WebRTC 的实时视频直播 Vue 3 组件，用于从远端摄像头设备接收音视频流并在浏览器中播放。组件通过 WebSocket 信令服务器与设备建立 P2P 连接，支持自动重连、画面冻结检测、截图、扬声器/麦克风控制等功能。

技术栈：Vue 3 Composition API + TypeScript + Element Plus。

## 连接流程

整个直播连接分为三个阶段：**信令协商 → ICE 连接 → 媒体播放**。

```
组件挂载
  │
  ├─ 1. 建立 WebSocket 信令连接
  │     ws://{host}:{port}/wswebclient/{meid}
  │
  ├─ 2. WebSocket 打开后发送 __connectto（告诉服务器要连哪个设备）
  │
  ├─ 3. 服务器返回 _create（设备在线状态 + ICE 服务器配置）
  │
  ├─ 4. 发送 __call（发起呼叫，携带音视频方向、认证信息）
  │
  ├─ 5. 服务器返回 _call 或 _offer（SDP 协商开始）
  │     ├─ 收到 _call → 创建 PeerConnection → createOffer → 发送 __offer
  │     └─ 收到 _offer → 创建 PeerConnection → createAnswer → 发送 __answer
  │
  ├─ 6. 收到 _answer → setRemoteDescription（SDP 协商完成）
  │
  ├─ 7. ICE Candidate 交换（__ice_candidate / _ice_candidate）
  │
  ├─ 8. ICE 连接建立（checking → connected）
  │
  ├─ 9. 远端 Track 到达 → video.srcObject 赋值 → video.play()
  │
  └─ 10. 画面显示，进入稳定播放状态
```

正常情况下，从 WebSocket 打开到画面显示约 100-500ms。

## 信令消息说明

| 方向 | 消息 | 说明 |
|------|------|------|
| → 发送 | `__connectto` | 请求连接指定设备 |
| ← 接收 | `_create` | 设备状态（online/offline）及 ICE 配置 |
| → 发送 | `__call` | 发起呼叫，携带音视频方向和认证信息 |
| ← 接收 | `_call` / `_offer` | 服务器要求创建 Offer 或直接下发 Offer |
| → 发送 | `__offer` / `__answer` | SDP 协商 |
| ← 接收 | `_answer` | 远端 SDP 应答 |
| ↔ 双向 | `__ice_candidate` / `_ice_candidate` | ICE 候选地址交换 |
| → 发送 | `__ping` | 心跳保活（每 30 秒） |
| → 发送 | `__disconnected` | 主动断开通知 |
| ← 接收 | `_session_failed` | 会话失败，需要重新连接 |
| ← 接收 | `_session_disconnected` | 远端断开通知 |
| ← 接收 | `_connectinfo` | 连接信息（调试用） |

## 重要功能

### 自动重连机制

- **心跳保活**：每 2 秒检测 WebSocket 状态，断开后自动重建连接
- **WebSocket 握手超时**：超过设定时间未连接成功则关闭并重试
- **Session 失败重试**：收到 `_session_failed` 后立即用新 sessionId 重新发起连接
- **ICE 断连恢复**：ICE 状态变为 disconnected/failed 时，如果 WebSocket 还活着则立即重新发起信令协商
- **组件卸载通知**：离开页面或切换路由时主动发送 `__disconnected`，让服务器立即清理旧 session

### 画面冻结检测（Watchdog）

每 3 秒通过 `RTCPeerConnection.getStats()` 检查视频流的 `bytesReceived`：
- 如果连续 3 次（约 9 秒）没有新数据到达，判定为画面冻结
- 先尝试 ICE Restart（`createOffer({ iceRestart: true })`）恢复连接
- ICE Restart 失败则完全重连
- 同时检测 `<video>` 元素是否意外暂停，自动恢复播放

### 本地媒体按需获取

组件默认以 `recvonly` 模式连接（只接收远端音视频），不请求本地摄像头/麦克风权限，避免浏览器弹出权限弹窗影响连接速度。只有用户主动点击"开启麦克风"时才调用 `getUserMedia` 获取音频轨道，并动态添加到 PeerConnection。

### 调试日志

所有关键步骤带有时间戳日志，格式为 `[WebRTC][tag]+XXXms`，从 WebSocket 开始连接计时。示例：

```
[WebRTC][ws]+0ms connecting... ws://192.168.1.20:8080/wswebclient/xxx
[WebRTC][ws]+3ms opened
[WebRTC][signal]+3ms sendConnect to ANSJ-00-...
[WebRTC][msg]+5ms _create
[WebRTC][signal]+5ms callDevice
[WebRTC][msg]+20ms _offer
[WebRTC][pc]+21ms PeerConnection created
[WebRTC][track]+23ms remote track received, kind: video
[WebRTC][ice]+70ms checking
[WebRTC][ice]+120ms connected
[WebRTC][play]+120ms attempting video.play()
[WebRTC][play]+200ms playing!
```


## 组件 API

### Props

| 属性 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `serno` | `string` | ✅ | — | 设备序列号 |
| `wsUrl` | `string` | — | 自动推导 | 信令 WebSocket 地址，不传则根据环境变量拼接 |
| `iceServers` | `RTCIceServer[]` | — | Google STUN | ICE 服务器配置，通常由信令服务器下发 |
| `mode` | `string` | — | `'live'` | 连接模式：`live`（直播）/ `playback`（回放） |
| `source` | `string` | — | `'MainStream'` | 码流：`MainStream`（主码流）/ `SubStream`（子码流） |
| `enableDataChannel` | `boolean` | — | `true` | 是否启用 DataChannel |
| `dragFlag` | `boolean` | — | `false` | 是否允许鼠标拖拽和滚轮缩放 |
| `sessionType` | `string` | — | `'IE'` | 会话类型标识 |
| `user` | `string` | — | `'admin'` | 设备认证用户名 |
| `pwd` | `string` | — | `'admin'` | 设备认证密码 |

### Events

| 事件 | 参数 | 说明 |
|------|------|------|
| `connected` | — | ICE 连接建立成功 |
| `disconnected` | — | 连接断开 |
| `error` | `Error \| string` | 连接或播放错误 |
| `datachannel-message` | `any` | 收到 DataChannel 消息 |

### Expose（通过 ref 调用）

| 方法/属性 | 类型 | 说明 |
|-----------|------|------|
| `reconnect()` | `function` | 手动断开并重新连接 |
| `captureSnapshot()` | `function` | 截取当前画面并下载为 PNG |
| `sendDataChannelMessage(msg)` | `function` | 通过 DataChannel 发送消息 |
| `toggleSpeaker()` | `function` | 切换扬声器开关 |
| `toggleMic()` | `function` | 切换麦克风开关（首次会请求权限） |
| `isPlaying` | `Ref<boolean>` | 是否正在播放（只读） |
| `speakerEnabled` | `Ref<boolean>` | 扬声器是否开启（只读） |
| `micEnabled` | `Ref<boolean>` | 麦克风是否开启（只读） |
| `connectionStatus` | `Ref<string>` | 连接状态（只读）：`idle` / `connecting` / `connected` / `disconnected` / `failed` |

## 使用示例

### 基础用法

```vue
<template>
  <WebRTCVideo serno="ANSJ-00-I7N3-QINU-00000027" />
</template>

<script setup>
import WebRTCVideo from '@/components/WebRTCVideo.vue'
</script>
```

### 完整配置

```vue
<template>
  <WebRTCVideo
    ref="videoRef"
    :serno="deviceSerno"
    mode="live"
    source="MainStream"
    session-type="IE"
    user="admin"
    pwd="admin123"
    :drag-flag="true"
    :enable-data-channel="true"
    @connected="onConnected"
    @disconnected="onDisconnected"
    @error="onError"
    @datachannel-message="onMessage"
  />
</template>

<script setup>
import { ref } from 'vue'
import WebRTCVideo from '@/components/WebRTCVideo.vue'

const videoRef = ref()
const deviceSerno = ref('ANSJ-00-I7N3-QINU-00000027')

function onConnected() {
  console.log('直播已连接')
}

function onDisconnected() {
  console.log('直播已断开')
}

function onError(err) {
  console.error('直播错误:', err)
}

function onMessage(msg) {
  console.log('DataChannel 消息:', msg)
}

// 通过 ref 调用组件方法
function handleScreenshot() {
  videoRef.value?.captureSnapshot()
}

function handleReconnect() {
  videoRef.value?.reconnect()
}
</script>
```

### 通过 URL 参数指定设备

访问 `http://localhost:3333/preview?serno=YOUR_DEVICE_SERNO` 即可连接指定设备。

## 环境变量

在 `.env.development` 和 `.env.production` 中配置：

```env
# WebRTC 信令服务器 IP（开发环境使用）
VITE_WEBRTC_SIGNAL_IP=192.168.1.20

# WebRTC 信令服务器端口
VITE_WEBRTC_SIGNAL_PORT=8080
```

- 开发环境：WebSocket 连接到 `VITE_WEBRTC_SIGNAL_IP:VITE_WEBRTC_SIGNAL_PORT`
- 生产环境：自动使用当前页面 host + 配置的端口，协议跟随 http/https 自动切换 ws/wss

## 文件结构

```
src/
├── components/
│   └── WebRTCVideo.vue      # WebRTC 直播组件
├── views/
│   └── preview/
│       └── index.vue         # 直播预览页面（使用 WebRTCVideo）
```