注意

这是最新开发分支配套的文档，可能包含已发布版本中尚未提供的功能。如果您要查看特定版本的文档，请使用左侧的下拉菜单并选择所需要的版本。

webrtc 模块 API 手册

概述

webrtc 是 CanMV 对 libpeer 的原生 MicroPython 封装。它提供后台协议工作线程，处理 ICE、DTLS-SRTP 和 RTP；Python 应用负责 HTTP/其他信令、视频编码以及媒体发送。

模块由 CONFIG_ENABLE_MODULE_WEBRTC 控制，默认启用并依赖 libpeer。每个 MicroPython 运行时最多只能同时创建一个 PeerConnection；已有连接未关闭时再次创建会抛出 OSError(EBUSY)。

随附的局域网摄像头示例见 WebRTC Camera。

常量

SDP 类型

常量	含义
SDP_TYPE_OFFER	SDP Offer
SDP_TYPE_ANSWER	SDP Answer

编码类型

常量	含义
CODEC_NONE	不启用对应媒体类型
CODEC_H264	H.264 视频
CODEC_H265	H.265 视频
CODEC_OPUS	Opus 音频负载
CODEC_PCMA	G.711 A-law 音频负载
CODEC_PCMU	G.711 u-law 音频负载

设置音频编码类型不会把 PCM 自动编码为 Opus/PCMA/PCMU；send_audio() 的数据必须已经完成编码。

连接状态

常量	含义
STATE_CLOSED	已关闭
STATE_NEW	已创建，尚未完成 SDP 协商
STATE_CHECKING	ICE 连通性检查中
STATE_CONNECTED	ICE 已连接，DTLS 握手进行中
STATE_COMPLETED	DTLS-SRTP 已完成，可发送媒体
STATE_FAILED	ICE 或 DTLS 失败
STATE_DISCONNECTED	连接中断

PeerConnection

构造函数

import webrtc

peer = webrtc.PeerConnection(
    video_codec=webrtc.CODEC_H265,
    audio_codec=webrtc.CODEC_NONE,
    audio_sample_rate=48000,
    ice_server=None,
    ice_username=None,
    ice_credential=None,
)

参数	含义	默认值
video_codec	CODEC_NONE、CODEC_H264 或 CODEC_H265	CODEC_H265
audio_codec	CODEC_NONE、CODEC_OPUS、CODEC_PCMA 或 CODEC_PCMU	CODEC_NONE
audio_sample_rate	音频采样率，必须大于 0	48000
ice_server	可选 STUN/TURN 服务地址	None
ice_username	可选 ICE 服务用户名	None
ice_credential	可选 ICE 服务凭据	None

构造完成后，模块会启动后台协议线程。局域网视频通常不需要配置 ice_server。

SDP 和 ICE

offer = peer.create_offer()
answer = peer.create_answer()
peer.set_remote_description(answer_sdp, webrtc.SDP_TYPE_ANSWER)
result = peer.add_ice_candidate(candidate_sdp)

方法	说明
create_offer()	创建本地 SDP Offer，返回 str。再次调用会关闭当前连接并开始新的 Offer。
create_answer()	在已设置远端 Offer 后创建 SDP Answer，返回 str。
set_remote_description(sdp, type=SDP_TYPE_ANSWER)	设置远端 SDP；非 trickle 场景的候选地址可直接包含在 SDP 中。
add_ice_candidate(candidate)	解析并添加一个远端候选，成功返回 0。

媒体发送

peer.send_video(venc_data, timestamp_us)
peer.send_audio(encoded_audio, timestamp_us)

方法	参数	说明
send_video(data, timestamp_us)	缓冲区、微秒时间戳	发送 Annex-B H.264/H.265 VENC 码流，返回底层发送结果。
send_audio(data, timestamp_us)	已编码缓冲区、微秒时间戳	发送与 audio_codec 对应的音频负载。

仅在 is_connected() 返回 True 后发送媒体。新接收端需要关键帧和编码参数集：H.264 发送 SPS/PPS，H.265 发送 VPS/SPS/PPS，然后发送 I 帧。

状态和关闭

print(peer.state())       # 整数状态常量
print(peer.state_name())  # 例如 "COMPLETED"
if peer.is_connected():
    pass
peer.close()

方法	说明
state()	返回当前状态整数。
state_name()	返回当前状态名称。
is_connected()	仅在状态为 STATE_COMPLETED 时返回 True。
close()	停止后台线程、销毁 PeerConnection 并释放 libpeer 资源；可重复调用。

PeerConnection 被垃圾回收时也会关闭，但应用应在 finally 中显式调用 close()。

典型信令流程

下面展示最小的板端 Offer 流程。HTTP 服务器的实现由应用决定。

peer = webrtc.PeerConnection(video_codec=webrtc.CODEC_H265)
try:
    offer_sdp = peer.create_offer()
    # 将 offer_sdp 返回给浏览器。
    # 接收浏览器 POST 的 answer_sdp 后：
    peer.set_remote_description(answer_sdp)

    while not peer.is_connected():
        time.sleep_ms(10)

    # 从 Encoder.GetStream() 取得 H.265 Annex-B 数据后发送。
finally:
    peer.close()

完整示例还会处理浏览器 mDNS 候选地址、HTTP 客户端提前断开、编码参数集缓存、连接建立时请求 IDR，以及网络接口选择。

注意事项

• WebRTC 摄像头示例默认 H.265、512 Kbit/s、无音频。浏览器不支持 H.265 时，将示例的 VIDEO_CODEC 改为 "h264"。

• 该模块不创建摄像头、VENC 或 HTTP 服务；应用必须自行管理这些资源。

• send_video() 发送时会与后台协议线程同步。不要在持有其他长时间锁的情况下调用它。

• 对于公网或复杂 NAT 场景，请配置 STUN/TURN，并实现带鉴权的信令服务；示例的 HTTP 服务只适合可信局域网。