Manage recordings

Once a recording exists, you manage it through the Fishjam Server API the same way, whether it was created with a template or from a composition output. Every call below is a method on the FishjamClient of the JS and Python server SDKs.

export FISHJAM_URL="https://fishjam.io/api/v1/connect/<YOUR_FISHJAM_ID>"
export TOKEN="<YOUR_MANAGEMENT_TOKEN>"
export RECORDING="<RECORDING_ID>"

Check the status

Typescript

const { status } = await fishjamClient.getRecording(recording.id);

Python

status = fishjam_client.get_recording(recording.id).status

curl

curl "$FISHJAM_URL/recordings/$RECORDING" \
  -H "Authorization: Bearer $TOKEN"

A recording has four statuses:

Status	Meaning
active	Media 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.

Instead of polling, you can subscribe to server notifications: every status change emits a RecordingStatusChanged message containing the recording's id, its new status, and its metadata, delivered over your configured webhook or a websocket.

Stop the recording

Typescript

await fishjamClient.stopRecording(recording.id);

Python

fishjam_client.stop_recording(recording.id)

curl

curl -X POST "$FISHJAM_URL/recordings/$RECORDING/stop" \
  -H "Authorization: Bearer $TOKEN"

Finalization is asynchronous: the recording remains active until capture has ended, then transitions to finished. Stopping a recording that is no longer active has no effect.

Stopping a recording explicitly is optional. Capture also ends when the composition ends, so deleting the composition finalizes its recordings. A recording of a composition output also ends when that output ends.

Download the MP4

Once the status is available, the recording's files field lists its media files in playback order as direct HTTPS URLs:

{
  "data": {
    "id": "<RECORDING_ID>",
    "status": "available",
    "files": [{ "url": "https://media.fishjam.io/.../index.mp4" }],
    "source": { "...": "..." },
    "metadata": { "show": "weekly-standup" }
  }
}

You can download the file or serve the URL to your users directly. Until the recording is available, files is empty.

Fishjam keeps recordings for 3 months after they are created, so download any file you need for longer. See Retention.

List your recordings

GET /recordings lists every recording in your app and accepts filters on status and metadata. A metadata filter matches recordings whose metadata contains all of the given pairs. Values are compared as strings, so numeric and boolean metadata values cannot be matched this way.

Typescript

const recordings = await fishjamClient.getAllRecordings({
  show: "weekly-standup",
});

Python

recordings = fishjam_client.get_all_recordings({"show": "weekly-standup"})

curl

curl -g "$FISHJAM_URL/recordings?status=available&metadata[show]=weekly-standup" \
  -H "Authorization: Bearer $TOKEN"

The -g flag prevents curl from interpreting the square brackets.

The SDK methods filter by metadata only. To filter by status as well, call the REST endpoint directly.

Delete a recording

Recordings persist independently of the composition for 3 months. To remove one sooner, delete it. Deleting a recording also removes its files:

Typescript

await fishjamClient.deleteRecording(recording.id);

Python

fishjam_client.delete_recording(recording.id)

curl

curl -X DELETE "$FISHJAM_URL/recordings/$RECORDING" \
  -H "Authorization: Bearer $TOKEN"

An active recording cannot be deleted. Stop it first and delete it once its status is no longer active.

See the Server REST API reference for the complete request and response schemas.