mirror of
https://github.com/ZLMediaKit/ZLMediaKit.git
synced 2026-03-04 05:00:54 +08:00
3fb43c5fef
- 增加客户端模式，支持主动拉流、推流： - addStreamProxy接口新增支持whep主动拉流，拉流地址目前只兼容zlm的whep url。 - addStreamPusherProxy接口新增支持whip主动推流，推流地址目前只兼容zlm的whip url。 - 以上推流url格式为webrtc[s]://server_host:server_port/app/stream_id?key=value, 内部会自动转换为http[s]://server_host:server_port/index/api/[whip/whep]?app=app&stream=stream_id&key=value。 - 增加WebRtc p2p 模式： - 增加 ICE FULL模式。 - 增加STUN/TURN 服务器。 - 增加websocket 信令。 - 增加P2P代理拉流。 --------- Co-authored-by: xia-chu <771730766@qq.com> Co-authored-by: mtdxc <mtdxc@126.com> Co-authored-by: cqm <cqm@97kid.com>
257 lines
8.3 KiB
Markdown
257 lines
8.3 KiB
Markdown
# 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代理推流
|