breeze/ZLMediaKit
1
0
Fork 0
mirror of https://github.com/ZLMediaKit/ZLMediaKit.git synced 2026-01-12 00:04:03 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
feature/python
ZLMediaKit/webrtc/USAGE.md
baigao-X 3fb43c5fef feat: 增加webrtc代理拉流 (#4389) 
- 增加客户端模式，支持主动拉流、推流：
   - 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>
2025-09-20 16:23:30 +08:00

8.3 KiB
Raw Permalink Blame History

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

请求示例:

# 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

请求示例:

# 将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] 配置段：

[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

注意事项

  1. 防火墙配置: 确保 WebRTC 相关端口已开放
    • 信令端口: 3000 (默认)
    • STUN/TURN 端口: 3478 (默认)
    • TURN Alloc 端口范围: 50000-65000(默认)

暂未实现的功能:

  • Webrtc信令服务的安全校验
  • 自定义外部STUN/TURN 服务器的配置
  • webrtc代理推流