cloudflare / cloudflare/realtimekit-ui

Composite recorder loses connectivity mid-session and renders "You're offline" into the recorded video

Open
#165 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
64
Forks
22
Avg merge
1d 18h
Merged PRs (30d)
5

Description

## Summary

The composite recording bot loses connectivity repeatedly mid-session and
renders **"You're offline — Please ensure that you are connected to the
internet"** into the recorded video. The resulting MP4 has multiple stretches
of blank screen where the session content should be.

Both human participants had stable connections throughout and saw no
interruption in their own clients. This is the recorder's own view.

In a 3 minute 30 second recording we see **two full "You're offline" screens**
plus a further stretch where both participant tiles fall back to avatar
placeholders (video lost). Extrapolated, a 60-minute session would lose a
comparable proportion of its recording.

For our use case — one-to-one sessions where the recording is delivered to the
client afterwards — a recording with blank gaps in it is not usable.

## Environment

| | |
|---|---|
| `@cloudflare/realtimekit` | 2.0.1 |
| `@cloudflare/realtimekit-ui` | 2.0.1 |
| `@cloudflare/realtimekit-react-ui` | 2.0.1 |
| App ID | `8045350b-e530-4bf4-aa36-1587f8a489b3` |
| Workers plan | Paid |
| Recording storage | custom `storage_config` → our own R2 bucket |

Account ID available on request.

## Affected recording

```
meeting bbb057dd-4489-4fbd-b0fb-6d45b585110d
session 3771391f-fa65-49a7-aaef-1015b98af9de
recording fff42617-bac3-4b34-99be-e23d2f6597bd
started 2026-08-05T10:28:35.014Z
stopped 2026-08-05T10:32:05.372Z
duration 209.937 s
status UPLOADED
```

Two participants, distinct presets, distinct `custom_participant_id`s, both
present for the whole session:

```
Nick Bester [orykl_practitioner] 10:28:16 -> 10:31:01
Test Client [orykl_customer] 10:28:20 -> 10:30:58
```

## Timeline of the defect

Timestamps are offsets into the recorded MP4:

| Offset | What the recording shows |
|---|---|
| 00:05 | normal — both participant tiles, video and name tags |
| ~00:49 | **"You're offline"** full screen, no video |
| ~01:34 | **"You're offline"** full screen, no video |
| ~02:27 | both tiles fall back to avatar placeholders, no video |
| ~02:55 | normal again |

Sampling one frame every 7 seconds across the whole recording shows the
affected frames are entirely blank apart from the offline message — the
participant video is not merely degraded, it is absent.

## Expected

The recorder maintains its connection for the duration of the session, or
recovers without writing its own error UI into the output. A transient
reconnect should not be baked into the delivered artifact.

## Actual

The recorder's connection-lost UI is composited into the recording, replacing
the participant video for the duration of each episode.

## Notes

- Both participants were on stable connections and observed no interruption in
their own clients during these windows.
- `recording_status` is `UPLOADED` and the file is otherwise valid — there is
no error surfaced anywhere in the API to indicate the recording is degraded.
From `GET /recordings` this recording looks perfectly healthy.
- We use a custom `storage_config` pointing at our own R2 bucket. The recording
is also retained in RealtimeKit-managed storage (`download_url` and
`audio_download_url` are both populated), and the defect is present in the
file we receive.

## Questions

1. Is there a way to detect a degraded recording programmatically? Right now a
recording with blank stretches is indistinguishable from a clean one via the
API, so we cannot flag it for review or re-record.
2. Is the recorder's connection-lost UI suppressible, so that a transient drop
leaves a frozen or black frame rather than an error message addressed to a
user who does not exist?
3. Does per-participant **track recording** (`POST /recordings/track`) share
this failure mode? Our reading is that it captures server-side rather than
through a headless browser client, so it may be unaffected — if so it is a
viable workaround for the audio path, and worth documenting as such.

Contributor guide

Open the contributing guide

Research direction

Start by reproducing the affected composite recording and inspect the GET /recordings result alongside the delivered MP4. Compare the composite path with POST /recordings/track, then determine whether connection loss can be detected or prevented from rendering the offline UI. Done means transient recorder disconnects do not produce blank or user-facing error screens in the recording, with degraded status exposed if applicable.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api, audio-video-rtc
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.