为你的端点选择任务。每个初始设置配方都从新的浏览器连接和匹配的 SFU 会话开始。你的应用可以把这些端点组合成房间、直播和设备界面。
在准备开始该连接的 SDP 交换时创建 SFU 会话。未连接的会话可能在首次操作前过期。
| 任务 | 结果 | 可运行示例 |
|---|---|---|
| 发布音频或视频 | 让本地媒体可供订阅者使用 | 视频房间 |
| 接收已发布轨道 | 播放另一端点的媒体 | 视频房间 |
| 在两个端点之间发送消息 | 在不使用媒体轨道的情况下交换应用数据 | DataChannel 示例 ↗ |
| 接收媒体并发送控制 | 观看发布端并回传已授权输入 | 云游戏 |
对于已有连接,参见添加媒体、添加 DataChannels 或关闭媒体轨道。若要在实现这些交换前先运行应用,请遵循快速入门。
创建一个 SFU 应用。后端持有其 App Secret,并发起此处展示的每一次 SFU API 请求。使用 Connection API 认证。路径相对于 https://rtc.live.cloudflare.com/v1/apps/{appId}。
在浏览器中,RTCPeerConnection 管理到 SFU 的一条连接。匹配的 sessionId 在 API 调用中标识该连接。Session Description Protocol (SDP) 描述连接的媒体和传输设置。浏览器和 SFU 交换 offer 和 answer 以就这些设置达成一致。
每次 API 调用都检查 HTTP 状态、公开错误和逐资源结果。保留成功的分配以便清理。在同一会话上下一次变更开始前,完成每个请求及其所需的 SDP 交换。不同会话可以独立进行。协商和会话生命周期说明如何协调重叠处理程序。
WebRTC 使用 Interactive Connectivity Establishment (ICE) 查找可用网络路径。按端点支持的网络进行配置。Cloudflare 的公共 STUN 服务器是 stun.cloudflare.com:3478。STUN 帮助发现网络地址。当端点网络需要中继时,TURN 可以转发流量。
安装连接状态处理程序,并为连接等待设置会报告失败的超时。设置本地描述后,在把 pc.localDescription 发送到后端之前收集网络候选。云游戏 WebRTC 辅助函数 ↗演示了有界候选收集。
本配方发布浏览器摄像头或麦克风。它创建不含 DataChannel 传输的媒体连接。
-
准备媒体 offer。 在浏览器中用
navigator.mediaDevices.getUserMedia()采集轨道。创建一个此处称为pc的RTCPeerConnection,并用pc.addTransceiver(track, { direction: "sendonly" })添加每条轨道。用await pc.createOffer()创建 offer,再用await pc.setLocalDescription(offer)应用它。等待候选收集,然后读取每个 transceiver 的
mid。该标识符把此连接 SDP 中的媒体段与你发布的轨道关联起来。 -
创建 SFU 会话。 在后端调用无请求体的
POST /sessions/new。把返回的sessionId与此连接一起存储。 -
发布轨道。 在后端调用
POST /sessions/{sessionId}/tracks/new,把浏览器的pc.localDescription作为sessionDescription:{ "sessionDescription": { "type": "offer", "sdp": "<LOCAL_SDP>" }, "tracks": [ { "location": "local", "mid": "<TRANSCEIVER_MID>", "trackName": "camera" } ] }用生成的 SDP 和已分配的
mid替换占位符。要同时发布摄像头和麦克风,在此请求中包含两条轨道。每项使用自己的mid和trackName。参见批量资源操作。 -
应用 answer。 在浏览器中,用返回的 SFU answer 执行
await pc.setRemoteDescription(response.sessionDescription)。这会完成 offer/answer 交换。此 answer 不需要调用/renegotiate。 -
让发布可被发现。 等待连接变为
connected。通过你的应用把成功发布的会话 ID 和轨道名称分享给已授权订阅者。
该发布已可供另一端点请求。使用接收已发布轨道验证播放。
从通过应用获得的发布者会话 ID 和轨道名称开始。这个仅接收的浏览器不需要摄像头或麦克风访问。
-
创建接收连接。 创建一个新的
RTCPeerConnection(称为pc),并安装track事件处理程序。在后端调用无请求体的POST /sessions/new。将其 ID 保存为subscriberSessionId。 -
请求该发布。 在后端调用
POST /sessions/{subscriberSessionId}/tracks/new,不带本地 offer:{ "tracks": [ { "location": "remote", "sessionId": "<PUBLISHER_SESSION_ID>", "trackName": "camera" } ] }要一起接收多个发布,在
tracks中为每个发布放一项。它们可以来自不同发布者。此请求把它们全部添加到同一接收会话。 -
应答 SFU offer。 在应用返回的 offer 之前,把每个成功结果的接收
mid映射到其发布。在浏览器中,先await pc.setRemoteDescription(response.sessionDescription),再pc.createAnswer()和pc.setLocalDescription(answer)。在
track处理程序中,用event.transceiver.mid选择该发布的播放元素。对于一条接收轨道,设置element.srcObject = new MediaStream([event.track])。 -
完成交换。 候选收集后,把
pc.localDescription返回给后端。将其作为sessionDescription发送到PUT /sessions/{subscriberSessionId}/renegotiate:{ "sessionDescription": { "type": "answer", "sdp": "<LOCAL_ANSWER_SDP>" } }仅在 API 接受该 answer 后继续。
-
验证接收。 等待连接变为
connected,并确认所请求媒体可以播放。连接成功但无法播放时,使用媒体故障排除。
本配方连接发布者和订阅者,不使用音频或视频。它使用可靠、有序投递。先连接每个端点的 DataChannel 传输,再分配其上承载的应用通道。
-
创建两个连接。 在每个浏览器中创建新的
RTCPeerConnection。安装datachannel事件监听器,以保留 SFU 打开的通道并在拆除时关闭它们。在后端为每个连接调用无请求体的POST /sessions/new。保存publisherSessionId和subscriberSessionId。 -
连接 DataChannel 传输。 对每个会话调用一次
POST /sessions/{sessionId}/datachannels/establish:{ "dataChannel": { "location": "remote", "dataChannelName": "server-events" } }检查返回的
dataChannel分配。server-events通道保留给传输设置。应用通道另行分配。 -
应答每个 SFU offer。 在对应浏览器中,
await pc.setRemoteDescription(response.sessionDescription),创建 answer,并await pc.setLocalDescription(answer)。候选收集后,把pc.localDescription返回给后端,并发送PUT /sessions/{sessionId}/renegotiate:{ "sessionDescription": { "type": "answer", "sdp": "<THIS_ENDPOINT_ANSWER_SDP>" } }等待每个 answer 被接受,并且两个 PeerConnection 都变为
connected,再分配应用通道。 -
发布应用通道。 在后端调用
POST /sessions/{publisherSessionId}/datachannels/new:{ "dataChannels": [{ "location": "local", "dataChannelName": "messages" }] }保留成功的发布者分配及其
id。 -
订阅该通道。 调用
POST /sessions/{subscriberSessionId}/datachannels/new:{ "dataChannels": [ { "location": "remote", "sessionId": "<PUBLISHER_SESSION_ID>", "dataChannelName": "messages" } ] }保留成功的订阅者分配及其
id。 -
创建浏览器通道。 把每个分配的
id作为channelId返回给对应端点。在每个 PeerConnection 上用该 ID 创建通道:const channel = pc.createDataChannel("messages", { negotiated: true, id: channelId, });发布者和订阅者 ID 可以不同。此浏览器配置匹配可靠、有序的 API 默认值。在订阅者上安装
message处理程序,并等待两个通道都打开。 -
发送并验证。 订阅者通过你的应用确认就绪后,在发布者上调用
channel.send("hello")。确认订阅者的message事件包含hello。
现在已有发布者到订阅者的消息。要添加回传路径,使用 DataChannel 回复。若需另一种投递策略,发布独立的具名通道,并让其订阅者镜像该策略。参见投递设置。
本配方用一条浏览器连接接收媒体并发送控制。发布端已经提供一条媒体轨道和一条可靠、有序的 controls DataChannel。你的后端已有这两个发布定位符,并已授权此浏览器作为控制者。
-
创建接收连接。 创建一个新的
RTCPeerConnection(称为pc)。安装track和datachannel监听器。在后端调用无请求体的POST /sessions/new,并保存subscriberSessionId。在这次首次媒体交换期间不要创建浏览器 DataChannels。 -
请求媒体。 调用
POST /sessions/{subscriberSessionId}/tracks/new,不带本地 offer:{ "tracks": [ { "location": "remote", "sessionId": "<MEDIA_PUBLISHER_SESSION_ID>", "trackName": "camera" } ] }把成功的接收
mid值映射到其发布。在track处理程序中用event.transceiver.mid把每条接收轨道附加到其播放元素。 -
完成媒体协商。 依次
await pc.setRemoteDescription(response.sessionDescription)、pc.createAnswer()和pc.setLocalDescription(answer)。候选收集后,通过后端把pc.localDescription发送到PUT /sessions/{subscriberSessionId}/renegotiate:{ "sessionDescription": { "type": "answer", "sdp": "<MEDIA_ANSWER_SDP>" } }等待 API 接受它,并在继续前确认媒体播放。
-
添加 DataChannel 传输。 保持同一个 PeerConnection 和会话。调用一次
POST /sessions/{subscriberSessionId}/datachannels/establish:{ "dataChannel": { "location": "remote", "dataChannelName": "server-events" } }保留成功的分配和预留的
server-events通道以便清理。 -
完成新的协商。 用
pc.setRemoteDescription()应用这个新的 SFU offer。创建并设置新的本地 answer。候选收集后,通过后端把pc.localDescription提交到PUT /sessions/{subscriberSessionId}/renegotiate:{ "sessionDescription": { "type": "answer", "sdp": "<DATACHANNEL_ANSWER_SDP>" } }等待每个浏览器操作以及 API 接受该 answer。在分配控制订阅前,等待 PeerConnection 变为
connected。 -
以回复权限订阅。 调用
POST /sessions/{subscriberSessionId}/datachannels/new:{ "dataChannels": [ { "location": "remote", "sessionId": "<CONTROL_PUBLISHER_SESSION_ID>", "dataChannelName": "controls", "canReply": true } ] }检查结果。此发布者通道最多由一名订阅者持有回复权限。授予此订阅者会替换先前持有者。谁获得该权限由你的后端控制。
-
打开并验证控制。 把订阅的
id作为channelId返回给浏览器:const controls = pc.createDataChannel("controls", { negotiated: true, id: channelId, });等待
open。发送你的应用定义的命令,并确认发布者收到它,同时媒体继续播放。
云游戏指南展示了同一条浏览器连接上的媒体和输入,包括控制权归属,以及离散输入与可替换输入的不同投递设置。
从已连接的 PeerConnection 开始,并保持其 SFU 会话。与该会话上的其他操作串行添加。
- 发布更多媒体: 为新轨道添加 transceiver,然后创建并设置新的本地 offer。从
tracks/new起遵循发布配方,把新的本地项与已收集的pc.localDescription一起发送。 - 接收更多媒体: 在同一会话上调用
tracks/new,并在接收请求格式中加入额外的远程项。完成任何返回的 SFU offer。
在下一次变更前完成所需的 SDP 交换。
当现有 PeerConnection 已完成仅媒体协商且没有 DataChannel 传输时,从这里开始。保持其 SFU 会话,并先完成任何未完成操作。
- 安装
datachannel监听器,以保留预留通道供拆除使用。调用POST /sessions/{sessionId}/datachannels/establish,并设置dataChannel: { location: "remote", dataChannelName: "server-events" }。 - 检查分配并应用返回的 offer。等待创建并本地应用新的 answer。候选收集后,通过后端把
pc.localDescription作为sessionDescription提交到PUT /sessions/{sessionId}/renegotiate。 - 等待 API 接受以及 PeerConnection 变为
connected。现在可以用datachannels/new添加应用通道。
这些配方使用已知起始状态。现有集成可能以不同顺序协商传输:
- 先 DataChannels 后媒体: 完成消息配方的传输交换,再在同一会话上添加媒体。在下一次操作前完成每次交换。
- 首次 offer 中同时包含媒体和 DataChannels: 端点可以在初始
tracks/newoffer 中同时协商两者。该交换完成后,跳过datachannels/establish,并通过datachannels/new分配应用通道。Pocket Radio 固件演练 ↗演示了这种设置。 - DataChannel 设置已经开始: 完成其未完成的 offer/answer 交换和连接等待。已协商的传输可以承载额外的应用通道。不要把
datachannels/establish当作重复的初始化检查。
返回 sessionDescription.type: "offer" 且 requiresImmediateRenegotiation: true 的操作,需要在该会话上下一次变更前给出 answer。配方已包含此交换。实现其他操作时使用此参考。
- 在浏览器中
await pc.setRemoteDescription(response.sessionDescription)。 await pc.createAnswer()并pc.setLocalDescription(answer)。候选收集后,把pc.localDescription返回给后端。- 发送
PUT /sessions/{sessionId}/renegotiate,并带上sessionDescription: { type: "answer", sdp: "<LOCAL_ANSWER_SDP>" }。 - 在开始另一次变更前,确认 API 已接受该 answer。浏览器的
signalingState变为stable并不表示后端已提交 answer。
使用你正在修改的连接上的 mid。关闭接收轨道会停止该订阅。关闭发布轨道会停止源。成功关闭双向 transceiver 会停止两个方向。订阅者的 PeerConnection 可以保持连接,已经缓冲的媒体仍可能继续播放。
从已建立连接且没有未完成的 offer/answer 交换开始。
-
准备端点的 offer。 在浏览器中保存每个要关闭的 transceiver 的
mid,然后调用其stop()方法。用await pc.createOffer()创建 offer,并用await pc.setLocalDescription(offer)应用它。 -
关闭轨道。 候选收集后,从后端发送
PUT /sessions/{sessionId}/tracks/close,带上这些 mid,并把浏览器的pc.localDescription作为sessionDescription:{ "tracks": [{ "mid": "<TRANSCEIVER_MID>" }], "sessionDescription": { "type": "offer", "sdp": "<LOCAL_SDP>" }, "force": false } -
应用 answer。 检查请求级和逐轨道错误。在浏览器中,即使用个别轨道失败,也要用返回的 answer 执行
await pc.setRemoteDescription(response.sessionDescription)。其他轨道可能已经关闭。 -
处理未完成工作。 在下一次变更前完成此交换。保留失败的关闭以便重试。如果没有可用 answer,遵循恢复指南。
使用关闭结果区分成功关闭、已经关闭的轨道,以及未解决的失败。
设置 force: true 可在不交换 SDP 的情况下关闭所选媒体流。这在端点无法提供关闭 offer 时有用。在后端发送 PUT /sessions/{sessionId}/tracks/close:
{
"tracks": [{ "mid": "<TRANSCEIVER_MID>" }],
"force": true
}检查每个轨道结果。不需要调用 /renegotiate。强制关闭可能在会话信息中留下记录。对未完成的协商或请求遵循拆除顺序。
停止接受新操作,并从发现中撤回已结束的发布。关闭已分配的媒体轨道和 DataChannels,然后在不再需要时关闭端点的 PeerConnection 并停止采集。如果端点在完成前离开,遵循清理职责。