Skip to main content

Merge Recordings

Endpoint: /recording/mergeRecordings

In long-running sessions, it's common for administrators or presenters to stop and restart a recording, resulting in multiple separate video files. This API provides a powerful solution to consolidate these segments into one continuous recording, improving the viewing experience.

Using FFmpeg's append feature, this endpoint stitches together recording files into a new recording with a unique record_id. The original recording files are not deleted, giving you the flexibility to manage or discard them as needed. This is ideal for creating a polished, final version of a session that was recorded in parts.

Asynchronous Operation & Webhook Notification​

This API operation is asynchronous. When you call this endpoint, the request is immediately assigned to a plugnmeet-recorder instance to be processed in the background. This requires you to have at least one active recorder running in either both or transcoderOnly mode. The API will instantly return a confirmation that the job has been scheduled.

Because the merging happens in the background, the final result is delivered via a webhook. Once the new recording file is ready, your server will receive a recording_proceeded event containing the record_id and other metadata for the newly merged file, just like a standard recording.

Use Cases​

  • Creating a single file for long webinars: If you pause a recording during a break, you can merge the parts for a seamless replay.
  • Combining training session modules: Merge separate recorded modules into one comprehensive training video.
  • Post-production simplification: Provide a single file for easier editing and distribution.

Request Parameters​

The request body must contain one of the following scopes: by_session or by_ids.

by_session​

Merge all recordings from a single room session. The recordings are appended chronologically in ascending order (ASC) as they were saved, ensuring a natural sequence.

FieldTypeRequiredDescription
room_sidstringYesThe unique session identifier (sid) of the room whose recordings you want to merge. All recordings under this room_sid will be considered for the merge.
exclude_recording_idsarray (string)NoAn array of record_ids to exclude from the merge. This is useful if you need to omit specific segments, such as a false start or an unwanted portion of the session.

by_ids​

Merge a specific list of recordings. The final video will be generated by appending recordings in the order they are provided in the recording_ids array.

FieldTypeRequiredDescription
room_idstringYesThe room_id that all recording_ids belong to.
recording_idsarray (string)YesA list of record_ids to merge. All recordings must belong to the specified room_id, but can be from different sessions. The list must contain at least two record_ids.

Example Requests​

Example 1: Merge by Session​

This example merges all recordings from the session c5b79ab5... except for one excluded recording.

{
  "by_session": {
    "room_sid": "c5b79ab5-b832-4972-9f9b-ba1f1e3369bd",
    "exclude_recording_ids": [
      "c5b79ab5-b832-4972-9f9b-ba1f1e3369bd-1779521611869"
    ]
  }
}

Example 2: Merge by IDs​

This example merges two specific recordings from the room room01 in the specified order.

{
  "by_ids": {
    "room_id": "room01",
    "recording_ids": [
      "c5b79ab5-b832-4972-9f9b-ba1f1e3369bd-1779521611869",
      "c5b79ab5-b832-4972-9f9b-ba1f1e3369bd-1779521613869"
    ]
  }
}

Response​

The API provides an immediate response indicating that the merge job has been successfully scheduled. The final result of the merge operation will be delivered via a recording_proceeded webhook event once the process is complete.

FieldTypeDescription
statusbooleanIndicates if the request was successful.
msgstringA message confirming the job was queued.
status_codenumberResponse status code.