Deliver Video Conference Recordings with Webhooks and AWS Lambda

Capturing recordings of a video conference meeting, classroom lecture, medical consultation, or webinar is a valuable feature of the Interactivity APIs. When building an in-flow application that includes real-time audio and video you may need to preserve the content to repurpose or replay it later. We’ll demonstrate how to enable recordings in a session and configure a webhook triggered when media is ready for download.

There are many tools you can choose from but for this project we’ll show how to do this with a serverless cloud function (AWS Lambda) which is a great option when combined with other services like cloud storage (AWS S3) and an email notification service (AWS SES).

Enabling Recordings

Not every conference is recorded unless you enable it. There are a few requirements in order to enable the creation of downloadable files.

1. You should enable liveRecording if you want to have a file generated at the end of a conference
2. You need to start() and stop() recording capture

A quick way to get started is with the voxeet-sdk-browser-gettingstarted repository on GitHub.

1. Enable liveRecording when creating a conference

When you create() a conference with the JavaScript Web SDK there are a few ConferenceParameters that can be passed to this method. One of those params is liveRecording which signifies that you want a recording to be generated at the conclusion of a conference session.

For example, your initialization may look like this:

// You can search in the Monitor Dashboard for conferences by name
let conferenceAlias = 'recording-demo';

// Set liveRecording to true if you want to generate media at the
// end of a live session.
VoxeetSDK.conference.create({ alias: conferenceAlias, params: {
    liveRecording: true,
}});

If you add this setting before participants join() a conference, the recording will be generated live during the conference for later download. In the event that this setting was not enabled, the Remix API is a REST endpoint that can be called to trigger the encoding of media again at the conclusion of a session.

If you are using the voxeet-sdk-browser-gettingstarted example you’ll need to make this change to the ui.js as liveRecording is not enabled in that repository by default. You’ll also need to input your own consumerKey and consumerSecret to the client.js.

2. Start recording during the session

When a conference session is created with liveRecording a call to start() will begin capturing the audio and video inputs. Regardless of which JavaScript library or framework you choose for your projects (React, Angular, Vue, Ember, etc.) you will need to wire an event to the user action that toggles this behavior.

The Getting Started walks through a complete sample application including the instructions for how to record the conference. The VoxeetSDK has a RecordingService with start() and stop()methods to respond to the press of a record button to capture the streaming audio and video coming from all participants.

It could look something like this:

// User wants to start recording now
VoxeetSDK.recording.start()

That’s it. Any additional behavior you want to add is entirely up to the user experience you want to create. A few best practices include things like an announcement that recording has begun, a visual indicator recording is happening, etc.

The voxeet-sdk-browser-gettingstarted already has the “start recording” button wired up to call this function.

Recording is Complete

A user may decide to terminate recording or when the session closes you’ll want to stop recording the meeting. The RecordingService has a stop() method for this.

// Stop recording
VoxeetSDK.recording.stop()

The voxeet-sdk-browser-gettingstarted already has the “stop recording” button wired up to call this function.

How do you get the recording? Log into your developer account and you can find it in the dashboard. You’ll need to select your app, then the Interactivity API monitor section. You can find the session by alias, id, or date. When you select your event you’ll find a recording section with a download button that looks like:

Since not all participants will have access to your account dashboard it is necessary to implement a solution.

Webhooks

A webhook is a mechanism you can configure to receive callbacks from the Dolby.io servers when an event of interest occurs. For instance, the Recording.MP4.Available event lets you know an MP4 recording is available for download.

To use webhooks you need two components:

1. Your endpoint that can receive an HTTP request.
2. Your account must be configured in the dashboard to enable calling your endpoint as a webhook.

Whenever a conference with liveRecording enabled completes, the server will check for any configured webhooks and then send a request. This request can serve as a notification to handle whatever behavior your application requires. A convenient way to implement this logic is with a cloud function such as running AWS Lambda.

Creating an AWS Lambda Function

AWS Lambda is Amazon’s function as a service. Instead of worrying about any infrastructure, we can focus on the logic required to receive a request. While these instructions are specific to AWS Lambda, the process should be similar for other cloud solutions.

There are also a few ways to create a function including using the aws CLI, but the steps I’ll outline are done from the AWS Management Console when selecting the Lambda service.

https://console.aws.amazon.com/

From the AWS Lambda Dashboard or Functions list you can click the orange Create function button. For this project I made the following selections:

• Author from scratch
• Function name: conference-recording-ready
• Runtime: Node.js 12.x

When you click the orange Create function button this time you’ll be in the main Function Designer.

Add Trigger

If you click the Add trigger button you can select other AWS services that enable your function to execute. By choosing API Gateway we can expose a URL that can trigger the execution of your function.

• Create an API
• API type: HTTP API
• Security: Open

For this demo we’re going to leave this endpoint open to make it reachable for testing. Once you are back in the Function Designer, selecting API Gateway will allow you to view the API endpoint. You’ll want to keep this handy as we’ll add it to our Dolby.io dashboard next.

Configuring Your Webhook

Back over on Dolby.io, you’ll need to make a change in your account dashboard.

1. Log in and select your app.
2. Select Interactivity APIs
3. In Settings, scroll down to the Webhooks section and click “Add Webhook”.
4. Paste the API endpoint from the API Gateway into the “URL Endpoint” field.
5. Check the box for Recording.MP4.Available

Now, the next time you have a conference, once the recording is available that URL endpoint will be called. You can add additional events, change the url endpoint, or delete the webhook at any time as your requirements evolve.

Implement Your Function

Back in the AWS Lambda Function editor we can implement our function. There are alternative methods of creating a function including with the aws CLI but since this function won’t be too complex we can go ahead and “Edit code inline” directly from our browser.

There is a boilerplate index.handler that was created when generating the function but we’ll make a few edits so the code looks like the following listing:

exports.handler = async (event) => {

    // The Dolby.io payload from the webhook will be in the body
    // which is a string.  We'll need to parse it to
    // reconstruct json.
    const webhook = JSON.parse(event.body);    

// Print this out to the console to inspect in CloudWatch.
    console.log(JSON.stringify(webhook, null, 4));

    // The most interesting elements we'll need are the
    // conference id and alias.  Also included is the 
    // URL we can retrieve the recording.
    const id = webhook.conference.confId;
    const alias = webhook.conference.confAlias;
    const url = webhook.url;

    // The webhook just wants the OK that we received the
    // request.
    const response = {
        statusCode: 200,
        body: 'Hello from Lambda!',
    };
    return response;
};

At this point, all we’re doing is extracting the conference session metadata we care about and logging them so that we can review it in the logs.

Record a Conference

Now to test this out, you can start your app or use the voxeet-sdk-browser-gettingstarted project to create a session. If you enable recording for a few minutes it should trigger the webhook to fire.

If you click on the “Monitoring” tab for your function, you can scroll down to see recent invocations.

Clicking on the LogStream will open CloudWatch for inspection. We should be able to see an entry that includes output that looks something like this:

{
    "conference": {
        "confId": "51c341c5-56e4-4489-81d4-e22588fa3055",
        "confAlias": "Webhook Demo"
    },
    "thirdPartyId": "your-consumer-key",
    "splits": null,
    "region": "ca",
    "duration": 10002,
    "eventType": "Recording.MP4.Available",
    "url": "https://s3.ca-central-1.amazonaws.com/dlb-prd-mixer-mpx-ca/{your-consumer-key/{confId}"
}

To recap, at this point we are in a Node.js environment, have access to a conference id and alias, along with the URL where we can fetch the recording. This function will be called at the conclusion of any conference session that had a recording.

Summary

Capturing a recording from a video conference can be a valuable piece of media. Some common use cases include:

• distribution to those absent and unable to attend a meeting
• broadcasting to another video platform
• archiving important meetings
• post-processing and editing content

In order to accomplish any of those use cases, you need to configure Webhooks with an URL endpoint that can listen for events. We’ve demonstrated how to do this with AWS Lambda and configuring the Interactivity API dashboard. The next step is to configure that function to automate your workflow whether it is storing the media in your own private S3 bucket or sending an email notification with SES. If you use Google Cloud Functions, IBM Cloud Functions, Mailgun or Mandrill you’d follow the same pattern for implementing and configuring your webhook.

Go check out the Recording and Webhooks documentation to learn more details about how to use these Dolby.io Interactivity API features in your projects.