Recording Videos

Overview

The Vonage Video archiving API lets you record a session's audio and video in two formats:

  • Composed archives (default) produces MP4 files that are ready for immediate playback.
  • Individual stream archives bundle every published stream into a ZIP of per-stream media files plus metadata for post-processing.

You can decide which format to use when you call the archiving REST API or Server SDK. See the Individual stream and composed archives comparison to choose the mode that fits your workflow.

Archiving requires both client-side and server-side code. In order to archive sessions, you need to have an HTTP server set up. You can pick the right server SDK for your sever setup. The Server SDK on receiving data from the client SDK will perform the actual archiving functionality. Your client-side code will then invoke your server-side code through HTTP calls.

  • In most applications, control of the archive recording would not be granted to every end-user.

  • You can have automatically archived sessions, which are recorded whenever a client starts publishing a stream.

  • You will want to set up an Amazon S3 or Microsoft Azure target for storage of your archive recordings.

This how-to will go over:

  • Starting an archive recording
  • Stopping an archive recording
  • How to retrieve archive recording information

Before you start

Before you begin to add recording to your application, ensure that you have a basic video application already running.

If you do not want to write your own server, you can use a pre-built server deployed to Vonage's Code Hub. Head on over to the Vonage Video Learning Server (PHP) and click on "Deploy Code." This will download our learning server and automatically launch it for you.

If you want to explore the code, you can instead click on "Get Code" or head on over to GitHub and download the code to your local machine.

You can only archive sessions that use the Vonage Video Media Router (sessions with the media mode set to routed)

Starting an Archive Recording

Unless your session is set to auto-archive, you will need to tell our system to start recording your session. In practice, this means that your front-end will present recording options to a moderator (or other appropriate role), and your front-end will send a request to a back-end server that will talk to the API to start the recording.

  1. Have your front-end send a request to your server to start the archiving.
var myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");

var raw = JSON.stringify({
  "sessionId": "value goes here"
});

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

var serverURL = "server-url.com/archive/start" // replace this with your HTTP server URL

fetch(serverUrl, requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));
  1. Have your back-end server accept the request, and contact the REST API to start the archiving.
try {
    const archive = await vonage.video.startArchive(sessionId);
    // The id property is useful to save off into a database
    console.log("new archive:", archive.id);
} catch(error) {
    console.error("Error starting archive: ", error);
}

If you are using the REST API directly, you will get a response similar to the following:

If you are using an SDK, it will return the above information in a format appropriate for the SDK. Please check the reference for your Server SDK on the exact return value you will get.

Stopping an Archive Recording

A recording will continue until one of the following conditions are met:

  • 4 hours of recording time
  • 1 hour of inactivity (no clients are publishing streams)
  • 12 total hours of active and "paused" publishing. A stream will pause when no clients are publishing.

We do not recommend that you let an archive recording stop based on the thresholds above. You should stop an archive whenever you know that an archive is finished. This works similiarly to starting an archive where your front-end should send a request to the back-end to tell the API to stop recording.

  1. Have your front-end send a request to your server to stop the archive recording.
var myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");

var raw = JSON.stringify({
  "archiveId": "value goes here"
});

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

var serverURL = "server-url.com/archive/stop" // replace this with your HTTP server URL

fetch(serverURL, requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));
  1. Your back-end server will send a request to the REST API to stop the recording.
try {
    const archiveResponse = await vonage.video.stopArchive(archiveId);
    console.log("Successfully stopped archive:", archiveResponse.id);
} catch(error) {
    console.error("Error stopping archive: ", error);
}

You will get back a response similar to the following:

This response may not have the final recording URL, especially if you are archving to your own S3 or Azure storage, or if the archive recording is not finalized. We will send a callback to your server when the archive is ready for download.

Getting Archive Recording Information

You can also get information about any archive recording at any time. This is useful to get statistics about the archive, and to check the status of the archive itself. For example, when you stop an archive it may take a few moments before the archive itself is ready. You can check the information of an archive to see when the archive is done and ready for download.

try {
    const archive = await vonage.video.getArchive(archiveId);
    console.log("Successfully retrieved archive:", archive.id);
} catch(error) {
    console.error("Error retrieving archive: ", error);
}

You will get back a response similar to when you stop the archive recording.

See also