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

WebSocket 适配器

最后更新 查看 MarkdownAgent 设置

WebSocket 适配器把一条 SFU 媒体轨道连接到你的服务,而无需该服务实现 WebRTC。可用它发送或接收音频,或以 JPEG 帧接收视频。

WebSocket 适配器已正式发布。每个适配器在一个方向上把一条 SFU 轨道连接到你的服务。

支持的媒体和方向

选择由你的服务向 SFU 发送音频,还是接收现有发布:

方向和 API location 路径 媒体
音频进入 SFU(location: "local") WebSocket 服务 → SFU → WebRTC 48 kHz 立体声 PCM 输入,发布为 Opus 音频
媒体离开 SFU(location: "remote") WebRTC → SFU → WebSocket 服务 Opus 音频解码为 48 kHz 立体声 PCM,或视频为 JPEG

API 对音频接入使用 buffer 模式,对媒体出站使用 stream 模式。双向音频请为每个方向各创建一个适配器。不支持视频接入。

JPEG 出站默认为每秒 1 帧 (FPS)。有 Enterprise 合同的客户可联系其 Cloudflare 客户团队,讨论更高帧率。

准备你的端点

你的服务托管 WebSocket 端点。无论接入还是出站,SFU 都会连接到它。

将 endpoint 设为可公开访问的 wss:// URL,该 URL 需接受 WebSocket 升级和二进制数据包格式。localhost 端点从 SFU 不可达,适配器也不会跟随 HTTP 重定向。

SFU API App Secret 应放在后端。你的 WebSocket 服务认证是另一条边界。适配器请求不支持自定义 WebSocket 头。在端点 URL 的路径或查询字符串中使用作用域令牌,是服务认证该连接的一种方式。

不要把端点令牌放进浏览器响应和日志。对于媒体出站恢复(stream 模式),会重用同一端点 URL。其凭据必须在重连尝试期间保持有效;在首次握手时永久消费该凭据会阻止恢复。

媒体格式

WebSocket 二进制格式

每条二进制 WebSocket 消息包含一个 Protocol Buffers 数据包:

message Packet {
  uint32 sequenceNumber = 1;
  uint32 timestamp = 2;
  bytes payload = 5;
}

PCM 载荷使用 48 kHz、立体声、有符号 16 位小端样本,左右样本交错。视频载荷包含完整 JPEG 图像。

音频接入数据包(buffer 模式)

接入只使用 payload。在 32 KB 序列化消息限制内发送小而频繁的音频块。选择块大小时要计入 protobuf 开销。

媒体出站数据包(stream 模式)

音频消息包含带时间戳和序列号的 PCM 帧。视频消息包含带时间戳的 JPEG 帧;视频序列号可能未设置。每一帧都是独立的 WebSocket 消息。

JPEG 路径支持 H.264、H.265、VP8 和 VP9 WebRTC 输入。更广的媒体轨道编解码器列表见支持的 SFU 编解码器。

创建适配器

你的后端向以下地址发送经过认证的 JSON 请求:

POST https://rtc.live.cloudflare.com/v1/apps/{appId}/adapters/websocket/new

包含 Authorization: Bearer <APP_SECRET> 和 Content-Type: application/json。在 tracks 中发送 1 到 4 项。OpenAPI schema 描述完整契约。

保存每个成功项的 adapterId,以便后端稍后关闭它。

向 SFU 发送音频

对于音频接入,使用 location: "local",从你的 WebSocket 服务创建发布:

{
	"tracks": [
		{
			"location": "local",
			"trackName": "generated-speech",
			"endpoint": "wss://example.com/audio-source",
			"inputCodec": "pcm"
		}
	]
}

接入必填字段为:

字段 值
location "local"
trackName 新发布的名称
endpoint 提供音频的 WebSocket URL
inputCodec "pcm"

接入使用 buffer 模式。API 根据 location 选择模式;mode 字段不会改变它。接入请求的 sessionId 会被忽略,因为 SFU 会分配发布会话。

成功项包含新的会话 ID:

{
	"tracks": [
		{
			"trackName": "generated-speech",
			"adapterId": "<ADAPTER_ID>",
			"sessionId": "<PUBLISHER_SESSION_ID>",
			"endpoint": "wss://example.com/audio-source"
		}
	]
}

你的应用把会话 ID 和轨道名称分享给已授权的 WebRTC 订阅者。订阅者可以遵循接收已发布轨道来播放该音频。WebSocket 服务发送包含 PCM 音频的 protobuf 数据包。每条序列化 WebSocket 消息(含 protobuf 开销)应保持在 32 KB 以内。

向你的服务发送音频或视频

从现有媒体发布开始。要创建一个发布,请遵循发布音频或视频。

对于媒体出站,使用 location: "remote" 把该发布发送到你的服务:

{
	"tracks": [
		{
			"location": "remote",
			"sessionId": "<PUBLISHER_SESSION_ID>",
			"trackName": "microphone",
			"endpoint": "wss://example.com/audio-consumer",
			"outputCodec": "pcm"
		}
	]
}

媒体出站必填字段为:

字段 值
location "remote"
sessionId 拥有该发布的会话
trackName 现有发布的名称
endpoint 接收媒体的 WebSocket URL
outputCodec Opus 音频发布用 "pcm",视频用 "jpeg"

stream 模式会自动选择。PCM 输出需要 Opus 源轨道。对于 JPEG 输出,使用视频发布并设置 outputCodec: "jpeg"。

成功的媒体出站项包含适配器 ID、轨道名称和端点。它不会返回新的会话 ID:

{
	"tracks": [
		{
			"trackName": "microphone",
			"adapterId": "<ADAPTER_ID>",
			"endpoint": "wss://example.com/audio-consumer"
		}
	]
}

部分批次结果

创建和关闭会为各个请求项返回结果。HTTP 200 响应表示至少一项成功。其中也可以包含失败项:

{
	"tracks": [
		{
			"trackName": "microphone",
			"adapterId": "<ADAPTER_ID>",
			"endpoint": "wss://example.com/audio-consumer"
		},
		{
			"trackName": "camera",
			"errorCode": "websocket_handshake_failed",
			"errorDescription": "The handshake with the provided endpoint failed."
		}
	]
}

检查每一项。即使另一项失败,也要保存成功的分配。重试整个部分成功的创建批次可能分配重复资源。

如果所有尝试项都失败,外层响应为 HTTP 503。项错误包含 errorCode 和 errorDescription;不包含各自的 HTTP 状态码。

关闭适配器

关闭是幂等的。你可以安全地重复关闭请求,包括对已经关闭的适配器。

把每项结果与其请求的 adapterId 匹配。保留失败或未报告项,以便用有界退避重试。部分批次响应规则同样适用。

从后端发送 1 到 4 个适配器 ID:

POST https://rtc.live.cloudflare.com/v1/apps/{appId}/adapters/websocket/close
{
	"tracks": [
		{ "adapterId": "<ADAPTER_ID_1>" },
		{ "adapterId": "<ADAPTER_ID_2>" }
	]
}

此 HTTP 200 响应中的两次关闭都成功。两项都不包含 errorCode:

{
	"tracks": [
		{
			"adapterId": "<ADAPTER_ID_1>",
			"bytesProcessed": 83492
		},
		{
			"adapterId": "<ADAPTER_ID_2>"
		}
	]
}

bytesProcessed 在不可用时会省略,而不是报告为零。它是运行统计,不是权威的计费用量总计。参见用量和定价。

流式传输的自动重连

对于媒体出站(location: "remote"),SFU 会在断开后最多 15 秒内重试同一端点。无需额外 API 设置。

如果重连窗口过期,适配器会关闭。要恢复流式传输,请创建新适配器。

音频接入(location: "local")不会自动重连。终态断开后请重新创建适配器。把返回的 sessionId 和轨道名称分享给已授权订阅者,以便他们订阅新发布。

重连期间的媒体缓冲

音频使用短而有界的积压。积压填满时可能丢弃较旧的帧。视频只保留最新可用的 JPEG 帧,并替换较旧的已缓冲帧。

恢复不保证无间隙或恰好一次投递。它重试同一端点,不会故障转移到另一个 URL。

故障排除

请求失败见错误代码,WebSocket 连接和关闭结果见适配器错误。在决定重试什么之前检查每一项。

如果连接已打开但缺少媒体,检查所选方向、源会话和轨道、protobuf 分帧、PCM 格式和消息大小。记录应用资源 ID 和连接转换,但不要记录端点令牌、SDP 或媒体内容。

用量和定价

WebSocket 适配器用量计入 Realtime 账单。到 WebSocket 端点的出站遵循 Realtime 定价;接入 SFU 的音频不按入站收费。参见定价和共用免费额度。

通过示例学习

AI 音频指南覆盖独立的语音生成和麦克风转写路径。WebRTC 转 JPEG 示例 ↗演示把视频发布作为 JPEG 帧投递给 Worker。

这些示例在公开使用前需要应用层认证和授权。仓库指南描述了设置、生命周期行为和限制。

这篇文档对您有帮助吗?