跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

连接模式

最后更新 查看 MarkdownAgent 设置

为你的端点选择任务。每个初始设置配方都从新的浏览器连接和匹配的 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 传输的媒体连接。

  1. 准备媒体 offer。 在浏览器中用 navigator.mediaDevices.getUserMedia() 采集轨道。创建一个此处称为 pc 的 RTCPeerConnection,并用 pc.addTransceiver(track, { direction: "sendonly" }) 添加每条轨道。用 await pc.createOffer() 创建 offer,再用 await pc.setLocalDescription(offer) 应用它。

    等待候选收集,然后读取每个 transceiver 的 mid。该标识符把此连接 SDP 中的媒体段与你发布的轨道关联起来。

  2. 创建 SFU 会话。 在后端调用无请求体的 POST /sessions/new。把返回的 sessionId 与此连接一起存储。

  3. 发布轨道。 在后端调用 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。参见批量资源操作。

  4. 应用 answer。 在浏览器中,用返回的 SFU answer 执行 await pc.setRemoteDescription(response.sessionDescription)。这会完成 offer/answer 交换。此 answer 不需要调用 /renegotiate。

  5. 让发布可被发现。 等待连接变为 connected。通过你的应用把成功发布的会话 ID 和轨道名称分享给已授权订阅者。

该发布已可供另一端点请求。使用接收已发布轨道验证播放。

接收已发布轨道

从通过应用获得的发布者会话 ID 和轨道名称开始。这个仅接收的浏览器不需要摄像头或麦克风访问。

  1. 创建接收连接。 创建一个新的 RTCPeerConnection(称为 pc),并安装 track 事件处理程序。在后端调用无请求体的 POST /sessions/new。将其 ID 保存为 subscriberSessionId。

  2. 请求该发布。 在后端调用 POST /sessions/{subscriberSessionId}/tracks/new,不带本地 offer:

    {
      "tracks": [
        { "location": "remote", "sessionId": "<PUBLISHER_SESSION_ID>", "trackName": "camera" }
      ]
    }

    要一起接收多个发布,在 tracks 中为每个发布放一项。它们可以来自不同发布者。此请求把它们全部添加到同一接收会话。

  3. 应答 SFU offer。 在应用返回的 offer 之前,把每个成功结果的接收 mid 映射到其发布。在浏览器中,先 await pc.setRemoteDescription(response.sessionDescription),再 pc.createAnswer() 和 pc.setLocalDescription(answer)。

    在 track 处理程序中,用 event.transceiver.mid 选择该发布的播放元素。对于一条接收轨道,设置 element.srcObject = new MediaStream([event.track])。

  4. 完成交换。 候选收集后,把 pc.localDescription 返回给后端。将其作为 sessionDescription 发送到 PUT /sessions/{subscriberSessionId}/renegotiate:

    {
      "sessionDescription": { "type": "answer", "sdp": "<LOCAL_ANSWER_SDP>" }
    }

    仅在 API 接受该 answer 后继续。

  5. 验证接收。 等待连接变为 connected,并确认所请求媒体可以播放。连接成功但无法播放时,使用媒体故障排除。

在两个端点之间发送消息

本配方连接发布者和订阅者,不使用音频或视频。它使用可靠、有序投递。先连接每个端点的 DataChannel 传输,再分配其上承载的应用通道。

  1. 创建两个连接。 在每个浏览器中创建新的 RTCPeerConnection。安装 datachannel 事件监听器,以保留 SFU 打开的通道并在拆除时关闭它们。在后端为每个连接调用无请求体的 POST /sessions/new。保存 publisherSessionId 和 subscriberSessionId。

  2. 连接 DataChannel 传输。 对每个会话调用一次 POST /sessions/{sessionId}/datachannels/establish:

    {
      "dataChannel": {
        "location": "remote",
        "dataChannelName": "server-events"
      }
    }

    检查返回的 dataChannel 分配。server-events 通道保留给传输设置。应用通道另行分配。

  3. 应答每个 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,再分配应用通道。

  4. 发布应用通道。 在后端调用 POST /sessions/{publisherSessionId}/datachannels/new:

    {
      "dataChannels": [{ "location": "local", "dataChannelName": "messages" }]
    }

    保留成功的发布者分配及其 id。

  5. 订阅该通道。 调用 POST /sessions/{subscriberSessionId}/datachannels/new:

    {
      "dataChannels": [
        {
          "location": "remote",
          "sessionId": "<PUBLISHER_SESSION_ID>",
          "dataChannelName": "messages"
        }
      ]
    }

    保留成功的订阅者分配及其 id。

  6. 创建浏览器通道。 把每个分配的 id 作为 channelId 返回给对应端点。在每个 PeerConnection 上用该 ID 创建通道:

    const channel = pc.createDataChannel("messages", {
      negotiated: true,
      id: channelId,
    });

    发布者和订阅者 ID 可以不同。此浏览器配置匹配可靠、有序的 API 默认值。在订阅者上安装 message 处理程序,并等待两个通道都打开。

  7. 发送并验证。 订阅者通过你的应用确认就绪后,在发布者上调用 channel.send("hello")。确认订阅者的 message 事件包含 hello。

现在已有发布者到订阅者的消息。要添加回传路径,使用 DataChannel 回复。若需另一种投递策略,发布独立的具名通道,并让其订阅者镜像该策略。参见投递设置。

接收媒体并发送控制

本配方用一条浏览器连接接收媒体并发送控制。发布端已经提供一条媒体轨道和一条可靠、有序的 controls DataChannel。你的后端已有这两个发布定位符,并已授权此浏览器作为控制者。

  1. 创建接收连接。 创建一个新的 RTCPeerConnection(称为 pc)。安装 track 和 datachannel 监听器。在后端调用无请求体的 POST /sessions/new,并保存 subscriberSessionId。在这次首次媒体交换期间不要创建浏览器 DataChannels。

  2. 请求媒体。 调用 POST /sessions/{subscriberSessionId}/tracks/new,不带本地 offer:

    {
      "tracks": [
        { "location": "remote", "sessionId": "<MEDIA_PUBLISHER_SESSION_ID>", "trackName": "camera" }
      ]
    }

    把成功的接收 mid 值映射到其发布。在 track 处理程序中用 event.transceiver.mid 把每条接收轨道附加到其播放元素。

  3. 完成媒体协商。 依次 await pc.setRemoteDescription(response.sessionDescription)、pc.createAnswer() 和 pc.setLocalDescription(answer)。候选收集后,通过后端把 pc.localDescription 发送到 PUT /sessions/{subscriberSessionId}/renegotiate:

    {
      "sessionDescription": { "type": "answer", "sdp": "<MEDIA_ANSWER_SDP>" }
    }

    等待 API 接受它,并在继续前确认媒体播放。

  4. 添加 DataChannel 传输。 保持同一个 PeerConnection 和会话。调用一次 POST /sessions/{subscriberSessionId}/datachannels/establish:

    {
      "dataChannel": {
        "location": "remote",
        "dataChannelName": "server-events"
      }
    }

    保留成功的分配和预留的 server-events 通道以便清理。

  5. 完成新的协商。 用 pc.setRemoteDescription() 应用这个新的 SFU offer。创建并设置新的本地 answer。候选收集后,通过后端把 pc.localDescription 提交到 PUT /sessions/{subscriberSessionId}/renegotiate:

    {
      "sessionDescription": { "type": "answer", "sdp": "<DATACHANNEL_ANSWER_SDP>" }
    }

    等待每个浏览器操作以及 API 接受该 answer。在分配控制订阅前,等待 PeerConnection 变为 connected。

  6. 以回复权限订阅。 调用 POST /sessions/{subscriberSessionId}/datachannels/new:

    {
      "dataChannels": [
        {
          "location": "remote",
          "sessionId": "<CONTROL_PUBLISHER_SESSION_ID>",
          "dataChannelName": "controls",
          "canReply": true
        }
      ]
    }

    检查结果。此发布者通道最多由一名订阅者持有回复权限。授予此订阅者会替换先前持有者。谁获得该权限由你的后端控制。

  7. 打开并验证控制。 把订阅的 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 交换。

向媒体连接添加 DataChannels

当现有 PeerConnection 已完成仅媒体协商且没有 DataChannel 传输时,从这里开始。保持其 SFU 会话,并先完成任何未完成操作。

  1. 安装 datachannel 监听器,以保留预留通道供拆除使用。调用 POST /sessions/{sessionId}/datachannels/establish,并设置 dataChannel: { location: "remote", dataChannelName: "server-events" }。
  2. 检查分配并应用返回的 offer。等待创建并本地应用新的 answer。候选收集后,通过后端把 pc.localDescription 作为 sessionDescription 提交到 PUT /sessions/{sessionId}/renegotiate。
  3. 等待 API 接受以及 PeerConnection 变为 connected。现在可以用 datachannels/new 添加应用通道。

其他初始协商顺序

这些配方使用已知起始状态。现有集成可能以不同顺序协商传输:

  • 先 DataChannels 后媒体: 完成消息配方的传输交换,再在同一会话上添加媒体。在下一次操作前完成每次交换。
  • 首次 offer 中同时包含媒体和 DataChannels: 端点可以在初始 tracks/new offer 中同时协商两者。该交换完成后,跳过 datachannels/establish,并通过 datachannels/new 分配应用通道。Pocket Radio 固件演练 ↗演示了这种设置。
  • DataChannel 设置已经开始: 完成其未完成的 offer/answer 交换和连接等待。已协商的传输可以承载额外的应用通道。不要把 datachannels/establish 当作重复的初始化检查。

完成 SFU offer

返回 sessionDescription.type: "offer" 且 requiresImmediateRenegotiation: true 的操作,需要在该会话上下一次变更前给出 answer。配方已包含此交换。实现其他操作时使用此参考。

  1. 在浏览器中 await pc.setRemoteDescription(response.sessionDescription)。
  2. await pc.createAnswer() 并 pc.setLocalDescription(answer)。候选收集后,把 pc.localDescription 返回给后端。
  3. 发送 PUT /sessions/{sessionId}/renegotiate,并带上 sessionDescription: { type: "answer", sdp: "<LOCAL_ANSWER_SDP>" }。
  4. 在开始另一次变更前,确认 API 已接受该 answer。浏览器的 signalingState 变为 stable 并不表示后端已提交 answer。

关闭媒体轨道

使用你正在修改的连接上的 mid。关闭接收轨道会停止该订阅。关闭发布轨道会停止源。成功关闭双向 transceiver 会停止两个方向。订阅者的 PeerConnection 可以保持连接,已经缓冲的媒体仍可能继续播放。

带协商关闭

从已建立连接且没有未完成的 offer/answer 交换开始。

  1. 准备端点的 offer。 在浏览器中保存每个要关闭的 transceiver 的 mid,然后调用其 stop() 方法。用 await pc.createOffer() 创建 offer,并用 await pc.setLocalDescription(offer) 应用它。

  2. 关闭轨道。 候选收集后,从后端发送 PUT /sessions/{sessionId}/tracks/close,带上这些 mid,并把浏览器的 pc.localDescription 作为 sessionDescription:

    {
      "tracks": [{ "mid": "<TRANSCEIVER_MID>" }],
      "sessionDescription": { "type": "offer", "sdp": "<LOCAL_SDP>" },
      "force": false
    }
  3. 应用 answer。 检查请求级和逐轨道错误。在浏览器中,即使用个别轨道失败,也要用返回的 answer 执行 await pc.setRemoteDescription(response.sessionDescription)。其他轨道可能已经关闭。

  4. 处理未完成工作。 在下一次变更前完成此交换。保留失败的关闭以便重试。如果没有可用 answer,遵循恢复指南。

使用关闭结果区分成功关闭、已经关闭的轨道,以及未解决的失败。

不协商地停止转发

设置 force: true 可在不交换 SDP 的情况下关闭所选媒体流。这在端点无法提供关闭 offer 时有用。在后端发送 PUT /sessions/{sessionId}/tracks/close:

{
  "tracks": [{ "mid": "<TRANSCEIVER_MID>" }],
  "force": true
}

检查每个轨道结果。不需要调用 /renegotiate。强制关闭可能在会话信息中留下记录。对未完成的协商或请求遵循拆除顺序。

清理

停止接受新操作,并从发现中撤回已结束的发布。关闭已分配的媒体轨道和 DataChannels,然后在不再需要时关闭端点的 PeerConnection 并停止采集。如果端点在完成前离开,遵循清理职责。

这篇文档对您有帮助吗?