Skip to content

Commit d6b2ecf

Browse files
ToxicityMaxToxicityMax
committed
[RealtimeKit]: add realtimekit track recording docs
1 parent 2795fe6 commit d6b2ecf

2 files changed

Lines changed: 153 additions & 6 deletions

File tree

‎src/content/docs/realtime/realtimekit/recording-guide/index.mdx‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
pcx_content_type: navigation
33
title: Recording
4-
description: Record audio and video from RealtimeKit meetings using composite recording mode.
4+
description: Record RealtimeKit meetings as composite recordings or separate participant audio tracks.
55
sidebar:
66
order: 8
77
label: Overview
@@ -11,18 +11,17 @@ products:
1111

1212
import { DirectoryListing } from "~/components";
1313

14-
Learn how RealtimeKit records the audio and video of multiple users in a meeting, as well as interacts with RealtimeKit plugins, in a single file using composite recording mode.
14+
Learn how RealtimeKit records meetings as a single composite file or as separate participant audio tracks.
1515

1616
Visit the following pages to learn more about recording meetings:
1717

1818
<DirectoryListing />
1919

20-
RealtimeKit records the audio and video of multiple users in a meeting, as well as
21-
interactions with RealtimeKit plugins, in a single file using composite recording mode.
20+
RealtimeKit can record the audio and video of multiple users in a meeting, as well as interactions with RealtimeKit plugins, in a single file using composite recording mode. RealtimeKit can also record separate participant audio tracks using track recording.
2221

23-
## How does RealtimeKit recording work?
22+
## How does composite recording work?
2423

25-
RealtimeKit recordings are powered by anonymous virtual bot users who join your
24+
Composite recordings are powered by anonymous virtual bot users who join your
2625
meeting, record it, and then upload it to RealtimeKit's Cloudflare R2 bucket. For video files,
2726
we currently support the
2827
[H.264](https://en.wikipedia.org/wiki/Advanced_Video_Coding) and
@@ -60,3 +59,5 @@ A typical workflow for recording a meeting involves the following steps:
6059
1. Start a recording using the [Start Recording API](/api/resources/realtime_kit/subresources/recordings/methods/start_recordings/) or client side SDK.
6160
2. Manage the recording using the [Pause, resume, or stop recording API](/api/resources/realtime_kit/subresources/recordings/methods/pause_resume_stop_recording/) or client side SDK.
6261
3. Fetch the download URL for downloading the recording using the [Fetch details of a recording API](/api/resources/realtime_kit/subresources/recordings/methods/get_one_recording/), webhook, or from the Developer Portal.
62+
63+
For separate participant audio files, refer to [Track recording](/realtime/realtimekit/recording-guide/track-recording/).

‎src/content/docs/realtime/realtimekit/recording-guide/track-recording.mdx‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
---
2+
title: Track recording
3+
description: Record separate audio tracks for selected RealtimeKit participants and download per-participant WebM files.
4+
pcx_content_type: how-to
5+
sidebar:
6+
order: 9
7+
products:
8+
- realtime
9+
---
10+
11+
Track recording records each participant's audio as a separate WebM file in RealtimeKit's Cloudflare R2 bucket. Use track recording when you need isolated speaker tracks for post-processing, transcription, compliance workflows, or audio analysis.
12+
13+
Composite recording creates one mixed meeting recording. Track recording creates one file per recorded participant peer.
14+
15+
:::note
16+
17+
Track recording currently supports audio tracks only. Video track recording is in development.
18+
19+
:::
20+
21+
## Availability and limits
22+
23+
Track recording has the following requirements and limits:
24+
25+
| Limit | Description |
26+
| --------------------- | ----------------------------------------------------- |
27+
| Active meeting | The meeting must have an active live session. |
28+
| Media kind | Only `audio` layers are recorded. |
29+
| Participant selection | Pass up to `100` values in `user_ids`. |
30+
| Storage | Files are uploaded to the RealtimeKit bucket. |
31+
| File retention | RealtimeKit bucket download URLs expire after 7 days. |
32+
33+
## Start track recording
34+
35+
To start track recording, call `POST /recordings/track` with the meeting ID.
36+
37+
If you omit `layers`, RealtimeKit records all participant audio. You can pass an audio layer to set a file name prefix for generated files.
38+
39+
```bash
40+
curl --request POST \
41+
--url https://api.cloudflare.com/client/v4/accounts/<account_id>/realtime/kit/<app_id>/recordings/track \
42+
--header 'Authorization: Bearer <api_token>' \
43+
--header 'Content-Type: application/json' \
44+
--data '{
45+
"meeting_id": "97440c6a-140b-40a9-9499-b23fd7a3868a",
46+
"layers": {
47+
"default": {
48+
"media_kind": "audio",
49+
"file_name_prefix": "speaker"
50+
}
51+
}
52+
}'
53+
```
54+
55+
The response includes a recording ID. Use this ID to stop or fetch the recording.
56+
57+
```json
58+
{
59+
"success": true,
60+
"data": {
61+
"recording": {
62+
"id": "fff40c6a-140b-40a9-9499-b23fd7a3868a",
63+
"meeting_id": "97440c6a-140b-40a9-9499-b23fd7a3868a",
64+
"status": "INVOKED",
65+
"type": "TRACK",
66+
"output_file_name": "{{file_name_prefix}}_{{user_id}}_{{peer_id}}_{{stream_kind}}_{{media_kind}}_{{date_time}}.webm"
67+
}
68+
}
69+
}
70+
```
71+
72+
## Record selected participants
73+
74+
Pass `user_ids` to record only specific participants. RealtimeKit records current and future participant peers whose `user_id` matches the allowlist.
75+
76+
```json
77+
{
78+
"meeting_id": "97440c6a-140b-40a9-9499-b23fd7a3868a",
79+
"user_ids": ["user-123", "user-456"]
80+
}
81+
```
82+
83+
## Set file name prefix
84+
85+
Use `file_name_prefix` to prefix every generated track recording file.
86+
87+
```json
88+
{
89+
"meeting_id": "97440c6a-140b-40a9-9499-b23fd7a3868a",
90+
"layers": {
91+
"default": {
92+
"media_kind": "audio",
93+
"file_name_prefix": "speaker"
94+
}
95+
}
96+
}
97+
```
98+
99+
If you omit `layers`, RealtimeKit uses `default` as the file name prefix.
100+
101+
## Stop track recording
102+
103+
Use the recording update endpoint to stop a track recording.
104+
105+
```bash
106+
curl --request PUT \
107+
--url https://api.cloudflare.com/client/v4/accounts/<account_id>/realtime/kit/<app_id>/recordings/<recording_id> \
108+
--header 'Authorization: Bearer <api_token>' \
109+
--header 'Content-Type: application/json' \
110+
--data '{
111+
"action": "stop"
112+
}'
113+
```
114+
115+
Track recording also stops when the meeting session ends.
116+
117+
After track recording stops, RealtimeKit uploads the per-participant WebM files and moves the recording to `UPLOADED`.
118+
119+
## Download track files
120+
121+
Track recording uses the same recording status lifecycle as composite recording. To monitor status, refer to [Monitor Recording Status](/realtime/realtimekit/recording-guide/monitor-status/).
122+
123+
When the recording reaches `UPLOADED`, fetch the recording details or listen for the `recording.statusUpdate` webhook. The `download_url` field contains the recorded WebM files for participant peers.
124+
125+
```json
126+
{
127+
"download_url": [
128+
{
129+
"layer_name": "default",
130+
"download_urls": {
131+
"speaker_user-123_peer-456_peer_audio_1760000000000.webm": {
132+
"download_url": "https://example.com/presigned-url"
133+
}
134+
}
135+
}
136+
]
137+
}
138+
```
139+
140+
File names use this format:
141+
142+
```txt
143+
{{file_name_prefix}}_{{user_id}}_{{peer_id}}_{{stream_kind}}_{{media_kind}}_{{date_time}}.webm
144+
```
145+
146+
The `date_time` value is the Unix timestamp in milliseconds when the file was generated.

0 commit comments

Comments
 (0)