Desktop Recording SDK Safe Shutdown and Recovery

The Desktop Recording SDK can recover from short network interruptions: up to two minutes for local recordings and up to 60 seconds for Raw Media recordings. How well it recovers depends on network conditions outside the SDK's control, and media loss is always possible on slow or unstable networks.

This page explains what happens when the SDK shuts down, which moments are risky, and how to shut down without losing media.

Recommended shutdown sequence

To avoid losing media in local recordings, call shutdown() only after all of the following are true:

No recording is active. Call stopRecording for any active recording, or let the meeting end.
You have received recording-ended for every recording. stopRecording resolving only means the command was handled, so don't treat it as completion.
You have given pending uploads time to drain. recording-ended does not mean the upload is finished, and the SDK emits it after at most 5 minutes even if uploads are still pending. On slow or unstable networks, uploads take longer, so wait longer before shutting down. There is no client-side upload-completion or progress signal, and no recommended fixed grace period.

If the user quits your app while a recording or upload is in progress, keep the SDK process running until these steps are done, or tell the user the upload is still in progress.

Recordings that use Raw Media are not interrupted by shutdown(). Check recording-started.rawMedia to see which mode a recording is using. After shutdown, you lose the recording handle and the Raw Media recording continues indefinitely. If you intend to end it, call stopRecording before shutdown().

If you also receive SDK upload webhooks on your backend, sdk_upload.complete confirms that an upload finished. The SDK's client-side events alone do not confirm upload completion.

How shutdown works

You can call shutdown() at any time, but calling it indiscriminately can destroy media. See Risky shutdown stages.
shutdown() does not wait for uploads to finish. See the shutdown force-exit timer.
Slow networks make uploads take longer. Calling shutdown() soon after stopRecording is more likely to cut off an upload that is still in progress.
After shutdown(), call init() again before using the SDK. The shutdown event fires on a normal exit. An unexpected exit surfaces as an error event of type process.

Risky shutdown stages

Stage	What happens if you call `shutdown()`
Recording in progress, between `startRecording` and `stopRecording`	Local capture stops mid-stream.
After `stopRecording`, before `recording-ended`	`stopRecording` resolving means the command was handled, not that capture is complete. Finalization may still be running.
After `recording-ended`, while uploads are still draining	`recording-ended` does not mean the upload has finished. Calling `shutdown()` kills any remaining upload partway through.
Raw Media recording	The recording continues indefinitely after `shutdown()`, and you lose the handle used to control it. Call `stopRecording` before `shutdown()` if you intend to end it.
Local realtime streaming	Callbacks to your app (`realtime-event`, `desktop_sdk_callback`) stop when the SDK shuts down. Raw Media uses a server-side pipeline, which continues after SDK shutdown.

Timeouts

Timer	Starts when	What happens
5 seconds: network notification (macOS)	Connectivity is lost or restored	On macOS, debounces the `network-status` event (`disconnected` / `reconnected`). Windows emits the event as soon as its network monitor detects the change, without this debounce.
5 seconds: shutdown force-exit	The native shutdown command is acknowledged	The JS wrapper waits for the process to exit, then tries to terminate it. This is not an upload-drain timeout, and it does not cap how long shutdown takes overall.
60 seconds: network disconnection (Raw Media)	Connectivity becomes unavailable	If connectivity stays unavailable, active Raw Media recordings stop automatically. The 5-second notification is part of this 60 seconds. An upload endpoint stalling while the machine is still online is a different condition.
2 minutes: network disconnection (local)	Connectivity becomes unavailable	If connectivity stays unavailable, active local recordings stop automatically. An upload endpoint stalling while the machine is still online is a different condition. The timeout starts when the SDK detects connectivity loss; on macOS, the 5-second notification delay is included in these 2 minutes.
5 minutes: recording-end fallback	A stopped recorder starts waiting for finalization	`recording-ended` is emitted even if uploads are still pending.
20 minutes: stale-upload finalization (server side)	The server last received a heartbeat for the upload	The upload becomes eligible for backend recovery. The job runs every minute and can finalize media the server already received. It cannot recover data the client never sent.

Recommended shutdown sequence

How shutdown works

Risky shutdown stages

Timeouts

Related