Recordings

Record Real-time Streams for Archival or Future Video on Demand Playback

Recording enables users to capture the live stream for future playback with an option to store and download the media file. When you record your live broadcasts, the recorded files are automatically processed and saved for you.

This guide includes examples for recording a stream and managing the recordings:

Recording streams

When recording a stream, the video codec used during the stream will be reflected in the archived video file.

Video CodecMedia Container
H.264MP4
VP8, VP9, AV1WebM

The resolution and bitrate of the recording will be dependent and match that of the stream being broadcast. Typically, when a stream begins the resolution and bitrate may shift around due to network conditions.

When using multisource streams each source can be recorded as an independent video file. If you want a video that combines all of the sources as a single layout, you will need to handle the mixing with another tool.

❗️

Recording Availability and Pricing

Recording is not available for free accounts.

To record streams, upgrade your account to one of our plans from the Dolby.io Dashboard. There are storage fees for video recording based on the number of hours a GB of data is stored. See the Pricing section for more details.

Recording limitations

The maximum length of a recorded file is 12 hours. For continuous recording of streams, recording is restarted and a new file is created every 12 hours.

How-to record from the Dolby.io dashboard

👍

Getting Started

If you haven't already, begin by following the Getting Started tutorial to create a Dolby.io application and start your first broadcast. You'll need your publish token and stream name for the steps described below.

Recording must first be enabled on a publish tokens. You can enable recording either when creating a new token or by updating an existing token.

Enable Record broadcast when creating a token:

Enable Record for an existing publish token from the Settings section of Token details.

🚧

Updating Token Settings

The recording property cannot be updated while the token is being used in a live broadcast; you must stop broadcasting to update it.

Go into the Dolby.io Live broadcast dashboard and press on the Broadcast button. Once the record feature is active, a red Record indicator will show up next to the Start button. Click on the button to make sure the stream will be recorded either prior to beginning the stream or later while the event is already live.

Press the Start button to begin broadcasting with recording enabled.

Allow the broadcast to record for at least 10 seconds, then click the Stop button to stop the feed. Once you've stopped, go ahead and close the broadcaster interface. This will return you to the tokens page on the Live broadcast page.

Revisit the publish token's management screen used for this stream and enter into the Recordings tab to access all recording files.

How-to record from OBS

You can record your broadcasts even if you are using 3rd party applications like OBS or your own custom broadcaster application. If you have not broadcasted to Dolby.io Real-time Streaming from OBS, please read the Using OBS page to enable your first broadcast with the software.

If you are familiar with the steps, set up OBS by visiting the Settings button to add the token information required.

Back on the main page, click the Start Recording button under Start Streaming to start recording your screen. When you are done, select Stop Recording. Recordings are available only in your local video or movie folder.

How-to record using Client SDKs

To start recording a stream using any Client SDK, enable recording in your publish token in the dashboard and set an optional recording parameter to true in publisher options, as in the following examples:

millicast::Publisher::Option options;
options.record_stream = true;
publisher->connect();
// Wait for the on_connected callback
publisher->publish(options);
Publisher.Option publisherOption = new Publisher.Option();
publisherOption.recordStream = true;
publisher.connect();
// Wait for the onConnected callback
publisher.publish(publisherOption);
let publisherOptions = MCClientOptions()
publisherOptions.recordStream = true
publisher!.connect()
// Wait for the onConnected callback
publisher!.publish(with: publisherOptions)
const publishOptions = {
  // Other preferred options
  record: true,
};

// Start publishing a stream
try {
  await publisher.connect(publishOptions);
} catch (e) {
  console.error('Connection failed, handle error', e);
}

Accessing recordings using the dashboard

How-to find the recordings for a token

To search videos recorded from a specific token, go into your Publish token from the Live Broadcast section and click the Settings button to open the management screen, then select the Recordings tab from the top of the panel. Each thumbnail is displayed with a reference to your recording. A newly created recording can take a few seconds to several minutes to render, depending on length. Once the recording has been processed, you are able to view it.

You can click on the More Files button to see all the files recorded with the respective token.

How-to find all recordings for an account

All of your recorded videos will be listed in the Recordings section of the dashboard.

Here you can view either as a thumbnail grid or a basic list by clicking the List View button on the top right section menu. Additionally, you can see the current total storage used in the top right corner of the Recording page, or get your current billable storage in the Billing page.

How-to preview a recording and metadata

To view your recorded videos, click on the thumbnail image which will open the Preview Player and begin playing the video. The player also provides more information about your recording including length, quality, and dimensions. Click on the More Details button under the player to explore.

858

You can close the player using the close button located on the top right or you can scroll down to choose another video.

❗️

Audio Codec of Recordings

Recorded video downloaded will have audio codec as Opus. Playback on various media players may not support Opus and audio may not be heard. You can use VLC for playback and converting sound to AAC.

How-to download videos of recordings

You can download recordings from the icons on the thumbnail directly. You can also download your video using the icon menu under the preview player. Clicking the download icon (arrow icon here) will immediately initiate a download.

How-to remove and delete recordings

The retention policy for recordings is determined by your business rules for removing and deleting the files.

Located next to the download button, the delete icon will delete the recording of the video. To delete multiple videos you can select the checkboxes on the thumbnails and then click the Delete Selected button from the section menu on the top right.

1204

To delete all items at once click the Select All button from the same top section menu, this will select every thumb on the screen, then click the Delete Selected button to delete them all.

1179

🚧

Deleting Recordings is Permanent

If you delete a recording it is immediate and permanent. We are unable to recover a recording once it has been deleted and removed from the cloud servers.

Accessing recordings using the REST API

👍

Using the REST APIs

Review the REST API platform guide for more details on generating an API secret for authentication. You will need an API Secret from the dashboard in order to make requests.

The Recording API provides a REST API that can be used to automate workflows for downloading and removing recordings.

How-to find recordings using the REST API

You can use the List Files REST API to query all the recordings for your account. Additionally, you can find recordings using the publish token or the stream name using the List Files By Token or List Files By Stream REST APIs, respectively.

How-to download videos of recordings using the REST API

You can use the Read File REST API to generate a URL link to download a recorded video.

Here is an example using cURL:

curl --request GET \
     --url https://api.millicast.com/api/record_files/699690 \
     --header 'accept: application/json' \
     --header 'authorization: Bearer d47137c5c1fe0b52c43d9e00a7bafb11a60d4ad5b4e91fe06257e8c13aca01dd'

In the URL request (https://api.millicast.com/api/record_files/{recordFileId}), the recordFileld being asked for is the reference number allocated after a new recording is registered. As for the Bearer, it is the token associated not with a publish token but with your Dolby.io account. To find this information, visit Settings on the left panel. Here under Security, it holds the account's API secrets. Tap on the + Create button and label it as you wish. Copy the token and replace it on the code above. If the response was 200, then your JSON should look like this:

{
  "status": "success",
  "data": {
    "download": {
      "downloadUrl": "https://milli-recording-storage-prd-02.s3.us-west-2.amazonaws.com/GCNQRh/5273f8407a72467196523e553c61442f/feed5e107691-825a-4a8e-936c-ce595529c4d0_full.webm?X-Amz-Expires=3600&response-content-disposition=attachment%3B%20filename%20%3D%20sxsw_1678731801.webm&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA4AHCQMSNIFIRHREE/20230720/us-west-1/s3/aws4_request&X-Amz-Date=20230720T201021Z&X-Amz-SignedHeaders=host&X-Amz-Signature=aa156f50a6c28fe907702ae6e8275f695ea8579b2da6a1c5d6503731c5b317bc",
      "downloadExpiresOn": "2023-07-20T21:10:21.6860061Z"
    },
    "id": 644690,
    "tokenId": 4369072,
    "token": "d4eff62e5e2761c1767c95e8ba460eca3cc354338539e41dbd9bb94c860e7ce",
    "streamName": "sxsw",
    "recordedOn": "2023-03-13T18:23:21Z",
    "status": "Complete",
    "metadata": {
      "format": "WEBM",
      "sizes": {
        "concat": 25701067,
        "dash": 25747521,
        "thumbnails": 463570
      },
      "duration": 85,
      "tracks": [
        {
          "type": "video",
          "codec": "VP8",
          "bitrate": 3577036,
          "width": 1280,
          "height": 720,
          "framerate": 0
        },
        {
          "type": "audio",
          "codec": "Opus",
          "bitrate": 24367,
          "channels": 2,
          "samplerate": 48000
        }
      ],
      "thumbnails": [
        "https://milli-recording-storage-prd-02.s3.us-west-2.amazonaws.com/GCNQRh/5273f8407a72467196523e553c61442f/thumbs/feed5e107691-825a-4a8e-936c-ce595529c4d0-002.jpg",
        "https://milli-recording-storage-prd-02.s3.us-west-2.amazonaws.com/GCNQRh/5273f8407a72467196523e553c61442f/thumbs/feed5e107691-825a-4a8e-936c-ce595529c4d0-003.jpg",
        "https://milli-recording-storage-prd-02.s3.us-west-2.amazonaws.com/GCNQRh/5273f8407a72467196523e553c61442f/thumbs/feed5e107691-825a-4a8e-936c-ce595529c4d0-004.jpg",
        "https://milli-recording-storage-prd-02.s3.us-west-2.amazonaws.com/GCNQRh/5273f8407a72467196523e553c61442f/thumbs/feed5e107691-825a-4a8e-936c-ce595529c4d0-005.jpg",
        "https://milli-recording-storage-prd-02.s3.us-west-2.amazonaws.com/GCNQRh/5273f8407a72467196523e553c61442f/thumbs/feed5e107691-825a-4a8e-936c-ce595529c4d0-006.jpg",
        "https://milli-recording-storage-prd-02.s3.us-west-2.amazonaws.com/GCNQRh/5273f8407a72467196523e553c61442f/thumbs/feed5e107691-825a-4a8e-936c-ce595529c4d0-007.jpg"
      ]
    }
  }
}

The response will not only contain the downloadURL but the metadata about the fetched file like codec, bitrate, format, and framerate. It will also display the information related to the Publish token under which it was recorded. To learn more about the recordings API and how to manage the calls yourself see the Recording API documentation.

How-to delete recordings using the REST API

You can use the Delete File REST API to delete one or more recordings associated with your account by specifying the record file ID. You can delete all recordings using the Delete All Files REST API.

🚧

Deleting Recordings is Permanent

If you delete a recording it is immediate and permanent. We are unable to recover a recording once it has been deleted and removed from the cloud servers.

How-to get notification when recording is available

There is a Recording Webhook that can be used so that your application receives a notification when a recording becomes available.

Troubleshooting

To diagnose recording issues, such as missing recordings, it can be helpful to review the details about the publish settings:

  • Protocol: RTMP, SRT, WebRTC, WHIP
  • Encoder: Hardware software type with version details
  • Settings: Bitrate, FPS, Resolution, if Simulcast enabled, etc.
  • Network: Details about the network used, for example a cellular connection may create issues with fluctuations in the network.

Troubleshooting dashboard recording errors

If the dashboard displays errors with the a recording, please contact the Dolby support team to open a support ticket, and provide the above details.

Troubleshooting missing audio

When publishing streams using 5.1 audio format, the audio will be present on the viewer live stream, but is not preserved in the recording. Multi-channel audio is currently not preserved in the recording archive. The audio will only be present in the recording archive if using stereo and mono formats. Multi-source stream audio will also be affected if the URL is set to &videoOnly.

Learn more

Learn more by exploring the developer blog and code samples.