轨道录制 · Cloudflare Realtime docs

轨道录制（Track recording）允许您将参与者音频录制为单独的 WebM 文件，而不是单个混合会议录制。当您需要对存储、处理或查看的内容进行发言者级别的控制时，请使用此功能。

使用轨道录制，您可以通过传递 user_ids 来录制特定参与者的轨道，这对于敏感内容或受监管的工作流非常有用，因为这些工作流中无需录制每个参与者。如果您不提供 user_ids，RealtimeKit 默认会将所有参与者的音频轨道录制为单独的 WebM 文件。

要为特定参与者轨道录制传递 user_ids，请使用以下最低 SDK 版本：

Web Core: @cloudflare/realtimekit 版本 1.4.0 或更高版本
Web UI Kit: @cloudflare/realtimekit-ui、@cloudflare/realtimekit-react-ui 或 @cloudflare/realtimekit-angular-ui 版本 1.1.2 或更高版本
Android Core 或 iOS Core：版本 2.0.0 或更高版本
Android UI Kit 或 iOS UI Kit：版本 1.1.0 或更高版本

轨道录制会为每个录制的参与者创建一个文件。

可用性和限制

轨道录制具有以下要求和限制：

限制	说明
活动会议	会议必须有一个处于活动状态的实时会话。
媒体类型	仅录制 `audio` 图层。
参与者选择	在 `user_ids` 中最多传递 100 个值。
存储	文件被上传到 RealtimeKit 托管的 R2 存储桶，零流出费用。
文件保留	RealtimeKit 存储桶的下载 URL 将在七天后过期。

开始轨道录制

录制特定参与者

要为特定参与者录制单独的音频轨道，请使用会议 ID 和参与者的 user_ids 调用 POST /recordings/track。

curl --request POST \
  --url https://api.cloudflare.com/client/v4/accounts/<account_id>/realtime/kit/<app_id>/recordings/track \
  --header 'Authorization: Bearer <api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "meeting_id": "97440c6a-140b-40a9-9499-b23fd7a3868a",
  "user_ids": ["user-123", "user-456"]
}'

RealtimeKit 会录制 user_id 与允许列表匹配的当前及未来的参与者。未列出 user_id 的参与者将不会被录制。

将所有参与者录制为单独的轨道

省略 user_ids 以便为实时会议中的所有参与者录制单独的音频轨道。RealtimeKit 会为每个录制的参与者创建一个 WebM 文件。

curl --request POST \
  --url https://api.cloudflare.com/client/v4/accounts/<account_id>/realtime/kit/<app_id>/recordings/track \
  --header 'Authorization: Bearer <api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "meeting_id": "97440c6a-140b-40a9-9499-b23fd7a3868a"
}'

响应包含一个录制 ID。使用此 ID 来停止或获取录制。

{
	"success": true,
	"data": {
		"recording": {
			"id": "fff40c6a-140b-40a9-9499-b23fd7a3868a",
			"meeting_id": "97440c6a-140b-40a9-9499-b23fd7a3868a",
			"status": "INVOKED",
			"type": "TRACK",
			"output_file_name": "{{file_name_prefix}}_{{user_id}}_{{peer_id}}_{{stream_kind}}_{{media_kind}}_{{date_time}}.webm"
		}
	}
}

使用前缀自定义文件名

使用 layers.default.file_name_prefix 为每个生成的轨道录制文件添加前缀。

{
	"meeting_id": "97440c6a-140b-40a9-9499-b23fd7a3868a",
	"layers": {
		"default": {
			"media_kind": "audio",
			"file_name_prefix": "speaker"
		}
	}
}

如果您省略 layers，RealtimeKit 将使用 default 作为文件名缀。

停止轨道录制

使用录制更新端点停止轨道录制。

curl --request PUT \
  --url https://api.cloudflare.com/client/v4/accounts/<account_id>/realtime/kit/<app_id>/recordings/<recording_id> \
  --header 'Authorization: Bearer <api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "action": "stop"
}'

当会议会话结束时，轨道录制也会停止。

轨道录制停止后，RealtimeKit 会上传每个参与者的 WebM 文件，并将录制移动到 UPLOADED。

下载轨道文件

轨道录制使用与混合录制相同的录制状态生命周期。要监控状态，请参阅监控录制状态。

当录制达到 UPLOADED 状态时，获取录制详情或监听 recording.statusUpdate Webhook。对于轨道录制，download_url 包含按图层分组的每个参与者的 WebM 文件 URL。

{
	"download_url": [
		{
			"layer_name": "default",
			"download_urls": {
				"speaker_user-123_peer-456_peer_audio_1760000000000.webm": {
					"download_url": "https://example.com/presigned-url"
				}
			}
		}
	]
}

文件名使用以下格式：

{{file_name_prefix}}_{{user_id}}_{{peer_id}}_{{stream_kind}}_{{media_kind}}_{{date_time}}.webm

date_time 值是生成文件时的 Unix 时间戳（以毫秒为单位）。