Recordings
Understanding how Fishjam captures composed streams as files
A recording captures the media published by one of a composition's outputs and stores it as an MP4 file. A composition is a live process: it produces media while it runs and leaves nothing behind once it is deleted. A recording is the persistent artifact of that process. It remains available after the composition, the room, and the livestream it was created from are gone, and it is stored in Fishjam until you delete it.
composition ──output──▶ livestream / RTMP ──▶ [viewers] │ └──recording──▶ MP4 ──▶ [download]
Recorders and outputs
A composition produces media through its outputs, and outputs are the unit that is recorded. To create a recording, you specify a composition and one of its registered outputs, and Fishjam attaches a recorder to that output. The recorder captures the output as it is published: the same layout and resolution, including every scene update, encoded separately from the live stream. There is no separate recording scene. If the recorded file should differ from the live stream, register a dedicated output with its own scene and record that output instead.
Besides composition URL and output ID, the recording API accepts a single option, scaleRatio, which sets the recording resolution as a fraction or multiple of the output's resolution. For example, 0.5 stores the recording at half the output resolution.
An output can have at most one recording at a time. To record the same output again, wait until the current recording is no longer active.
Composition API and Server API
Compositions are managed through the Composition API, while recordings are created and managed through the Fishjam Server API, either directly or with the JS and Python server SDKs. This split reflects ownership: a composition is a running session that you configure, whereas a recording is a resource of your Fishjam app, stored alongside your rooms and livestreams and managed with the same management token. You do not interact with the composition to record it; the Server API controls the capture inside the composition on your behalf.
Lifecycle
A recording has four statuses:
| Status | Meaning |
|---|---|
active | The output is being captured. |
finished | Capture has ended and the file is being prepared. |
available | The MP4 is ready and files contains the download URL. |
failed | An error occurred and no file will be produced. |
Capture starts as soon as the recording is created. It ends when you stop the recording explicitly, or automatically when the recorded output ends or the composition is deleted, so deleting a composition also finalizes its recordings. Finalization is asynchronous: the recording remains active until capture has ended, then transitions through finished to available once the file is ready.
Every status change emits a RecordingStatusChanged server notification over your configured webhook or a websocket, so you can react to a file becoming available without polling.
Once a recording is available, its files field lists the media files in playback order as direct HTTPS URLs that you can download or serve to your users. The recording and its files persist until you delete the recording. Deleting the recording is the only way to remove them, and a recording cannot be deleted while it is active.
Metadata
A recording carries optional free-form metadata, set at creation and returned with every read. Because recordings accumulate over time, metadata also serves as the primary way to locate them: listing recordings supports filtering by metadata pairs, for example to retrieve every recording for a given show or customer.
Where to go next
- Record a composition: start, stop, and download a recording step by step.
- Compositions: the sessions that recordings capture.
- Server REST API: the complete request and response schemas.