THENG
/
a-zlm
6
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
a-zlm/webrtc/USAGE.md

257 lines
8.3 KiB
Markdown
Raw Permalink Normal View History

first commit
2026-01-14 15:38:20 +08:00
# WebRTC 使用说明
## WebRTC 架构
### 1. SFU 模式架构 (WHIP/WHEP)
SFU 模式通过服务器中继媒体流，支持多路复用和转码：
```
WebRTC SFU 模式 (WHIP/WHEP)
推流端 (WHIP) 拉流端 (WHEP)
+----------------+ +-----------------+
| Encoder | | Player |
| (Browser/ZLM) | | (Browser/ZLM) |
+----------------+ +-----------------+
| |
| WHIP Protocol | WHEP Protocol
| (WebRTC ingest) | (WebRTC playback)
| |
v v
+-------------------------------------------------------------------+
| ZLMediaKit Server |
+-------------------------------------------------------------------+
- WHIP: WebRTC-HTTP Ingestion Protocol (推流)
- WHEP: WebRTC-HTTP Egress Protocol (拉流)
```
### 2. P2P 模式架构
P2P 模式允许客户端之间直接建立连接，减少服务器负载：
基于Websocket的自定义信令协议
```
WebRTt WC P2P 模式
客户端 A 客户端 B
+------------+ +-------------+
| Browser/ZLM| | Browser/ZLM |
+------------+ +-------------+
| |
| 1. 信令交换 (SDP Offer/Answer) |
| 2. ICE Candidate 交换 |
+---------------- -----+-----------------------+
| | |
| +-----------------------+ |
| | ZLMediaKit Server | |
| | 信令服务器 (WebSocket) | |
| | STUN 服务器 | |
| | TURN 服务器 | |
| +-----------------------+ |
| |
+-----------------------------------------------+
直接P2P连接
```
## HTTP API 接口
### 1. WebRTC 房间管理
#### `/index/api/addWebrtcRoomKeeper`
添加WebRTC到指定信令服务器，用于在信令服务器中维持房间连接。
**请求参数:**
- `secret`: 接口访问密钥
- `server_host`: 信令服务器主机地址
- `server_port`: 信令服务器端口
- `room_id`: 房间ID，信令服务器会对该ID进行唯一性检查
#### `/index/api/delWebrtcRoomKeeper`
删除指定的信令服务器。
**请求参数:**
- `secret`: 接口访问密钥
- `room_key`: 房间保持器的唯一标识符
#### `/index/api/listWebrtcRoomKeepers`
列出所有信令服务器。
**请求参数:**
- `secret`: 接口访问密钥
### 2. WebRTC 房间会话管理
#### `/index/api/listWebrtcRooms`
列出所有活跃的WebRTC Peer会话信息。
**请求参数:**
- `secret`: 接口访问密钥
### 3. WebRTC 推流和拉流接口
ZLMediaKit 支持通过标准的流代理接口来创建WebRTC推流和拉流，支持两种信令模式：
##### `/index/api/addStreamProxy` - WebRTC 拉流代理
通过此接口可以创建WebRTC拉流代理，支持两种信令协议模式。
**请求参数:**
- `secret`: 接口访问密钥
- `vhost`: 虚拟主机名，默认为 `__defaultVhost__`
- `app`: 应用名
- `stream`: 流ID
- `url`: WebRTC源URL，支持两种格式
**WebRTC URL 格式:**
1. **WHIP/WHEP 模式 (SFU)** - 标准HTTP信令协议:
```
# HTTP
webrtc://server_host:server_port/app/stream_id?signaling_protocols=0
# HTTPS (暂未实现）
webrtcs://server_host:server_port/app/stream_id?signaling_protocols=0
```
2. **WebSocket P2P 模式** - 自定义信令协议:
```
# WebSocket
webrtc://signaling_server_host:signaling_server_port/app/stream_id?signaling_protocols=1&peer_room_id=target_room_id
# WebSocket Secure (暂未实现)
webrtcs://signaling_server_host:signaling_server_port/app/stream_id?signaling_protocols=1&peer_room_id=target_room_id
```
**请求示例:**
```bash
# WHIP/WHEP 模式拉流
curl -X POST "http://127.0.0.1/index/api/addStreamProxy" \
-d "secret=your_secret" \
-d "vhost=__defaultVhost__" \
-d "app=live" \
-d "stream=test" \
-d "url=webrtc://source.server.com:80/live/source_stream?signaling_protocols=0"
# P2P 模式拉流
curl -X POST "http://127.0.0.1/index/api/addStreamProxy" \
-d "secret=your_secret" \
-d "vhost=__defaultVhost__" \
-d "app=live" \
-d "stream=test" \
-d "url=webrtc://signaling.server.com:3000/live/source_stream??signaling_protocols=1%26peer_room_id=target_room_id"
```
#### `/index/api/addStreamPusherProxy` - WebRTC 推流代理 (暂未实现)
通过此接口可以创建WebRTC推流代理，将现有流推送到WebRTC目标服务器。
**请求参数:**
- `secret`: 接口访问密钥
- `schema`: 源流协议 (如: rtmp, rtsp, hls等)
- `vhost`: 虚拟主机名
- `app`: 应用名
- `stream`: 源流ID
- `dst_url`: WebRTC目标推流URL
**WebRTC 推流 URL 格式:**
1. **WHIP 模式 (SFU)** - 推流到支持WHIP的服务器:
```
# HTTP
webrtc://target_server:port/app/stream_id?signaling_protocols=0
# HTTPS (暂未实现)
webrtcs://target_server:port/app/stream_id?signaling_protocols=0
```
2. **WebSocket P2P 模式** - 推流到P2P房间
```
# WebSocket
webrtc://signaling_server:port/app/stream_id?signaling_protocols=1&peer_room_id=target_room
# WebSocket Secure
webrtcs://signaling_server:port/app/stream_id?signaling_protocols=1&peer_room_id=target_room
```
**请求示例:**
```bash
# 将RTSP流推送到WHIP服务器
curl -X POST "http://127.0.0.1/index/api/addStreamPusherProxy" \
-d "secret=your_secret" \
-d "schema=rtsp" \
-d "vhost=__defaultVhost__" \
-d "app=live" \
-d "stream=test" \
-d "dst_url=webrtc://target.server.com:80/live/target_stream?signaling_protocols=0"
# 将RTSP流推送到P2P房间
curl -X POST "http://127.0.0.1/index/api/addStreamPusherProxy" \
-d "secret=your_secret" \
-d "schema=rtsp" \
-d "vhost=__defaultVhost__" \
-d "app=live" \
-d "stream=test" \
-d "dst_url=webrtc://signaling.server.com:3000/live/room_stream?signaling_protocols=1%26peer_room_id=target_room_id"
```
#### URL 参数说明
- `signaling_protocols`: 信令协议类型
- `0`: WHIP/WHEP 模式（默认）
- **协议**: 基于HTTP的标准WebRTC信令协议
- **应用场景**: SFU（选择性转发单元）模式，适合广播和多人会议
- `1`: WebSocket P2P 模式
- **协议**: 基于WebSocket的自定义信令协议
- **应用场景**: 点对点直连，适合低延迟通话和私人通信
- `peer_room_id`: P2P模式下的目标房间ID（仅P2P模式需要）
### 4. WebRTC 代理播放器信息查询
#### `/index/api/getWebrtcProxyPlayerInfo`
获取WebRTC代理播放器的连接信息和状态。
**请求参数:**
- `secret`: 接口访问密钥
- `key`: 代理播放器标识符
## WebRTC 相关配置项
在 `config.ini` 中的 `[rtc]` 配置段：
``` ini
[rtc]
#webrtc 信令服务器端口
signalingPort=3000
#STUN/TURN服务器端口
icePort=3478
#STUN/TURN端口是否使能TURN服务
enableTurn=1
#TURN服务分配端口池
portRange=50000-65000
#ICE传输策略：0=不限制(默认)，1=仅支持Relay转发，2=仅支持P2P直连
iceTransportPolicy=0
#STUN/TURN 服务Ice密码
iceUfrag=ZLMediaKit
icePwd=ZLMediaKit
```
## Examples
- [zlm_peerconnection](https://gitee.com/libwebrtc_develop/libwebrtc/tree/feature-zlm/examples/zlm_peerconnection)
一个基于libwebrtc 实现的zlm p2p 代理拉流简单示例
## 注意事项
1. **防火墙配置**: 确保 WebRTC 相关端口已开放
- 信令端口: 3000 (默认)
- STUN/TURN 端口: 3478 (默认)
- TURN Alloc 端口范围: 50000-65000(默认)
## 暂未实现的功能:
- Webrtc信令服务的安全校验
- 自定义外部STUN/TURN 服务器的配置
- webrtc代理推流