Clipping features docs

millicast/changelog/changelog-rest-apis.md

@@ -2,6 +2,12 @@
 
 Updates to [REST APIs](/millicast/api/analytics-account-total), and [Webhooks](/millicast/webhooks/).
 
+## 2026-03-20 | REST APIs
+
+### Features
+
+- Added live-to-VOD functionality and updated documentation to describe the wide array of recording capabilities and use-cases. See [Stream Recordings](/millicast/distribution/stream-recordings/) for more info
+
 ## 2026-03-12 | REST APIs
 
 ### Features

millicast/distribution/stream-recordings/how-to-get-media-assets.mdx

@@ -2,15 +2,23 @@
 title: How-to Get Media Assets
 ---
 
+Media assets are media recordings that are created one of several ways:
+
+- **[Stream Recordings](/millicast/distribution/stream-recordings/):** Media captured by enabling _recording_ on a token, the entire stream from first to last frame is stored in the cloud as a single-layer "mezzanine" recording, usually stored in an MP4 container
+- **[Live-to-VOD clips](/millicast/distribution/stream-recordings/live-clipping/):** These assets are "clipped" out of a live streaming workflow as a servable HLS manifest that can be used for distribution and replays of the stream. These are referred to as "live clips" or "live clipping". You can also extract a single MP4 mezzanine "clip" appropriate for social sharing or archive
+- **[Media Uploads](/millicast/distribution/stream-recordings/how-to-upload-media-assets/):** Files that are pre-transcoded before upload for distribution and are served over Dolby's CDN
+
 With [Stream Recordings](/millicast/distribution/stream-recordings/index.mdx) you will want to be able to retrieve and operate on any media assets that are created. You can do this manually using the [Streaming Dashboard](/millicast/streaming-dashboard/index.mdx) or automate workflows using the [Media Assets](/millicast/api/media-assets-list-media-assets.api.mdx) REST endpoints. There are also [Media Webhooks](/millicast/webhooks/media.md) available for building event-driven integrations.
 
-## Recordings in the Dashboard
+_Note: At this time, **Stream Recordings** are currently visible in the dashboard, for **live-to-vod** and **media uploads**, you must use the API to retrieve your assets. Creating live-to-vod assets requires consultation with the Dolby team to enable the workflow._
+
+## Stream Recordings in the Dashboard
 
 You can find recordings by visiting the [Streaming Dashboard](/millicast/streaming-dashboard/index.mdx).
 
-### Find Recordings by Token
+### Find Stream Recordings by Token
 
-To find recordings for a specific token, open your Publish token from the **Live Broadcast** section and click the **Settings** button to open the management screen. 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 can view it. You can click on the **More Files** button to see all the files recorded with the respective token.
+To find stream recordings for a specific token, open your Publish token from the **Live Broadcast** section and click the **Settings** button to open the management screen. Select the **Recordings tab** from the top of the panel. Each thumbnail is displayed with a reference to your stream recording. A newly created stream recording can take a few seconds to several minutes to render, depending on length. Once the stream recording has been processed, you can view it. You can click on the **More Files** button to see all the files recorded with the respective token.
 
 import RecTokenRecordings from '../../assets/img/0f4fe76-rec-token-recordings.png';
 
@@ -82,7 +90,7 @@ If you delete a recording or clip it is immediate and permanent. We are unable t
 
 ## Finding Media by API
 
-The [Media Assets](/millicast/api/media-assets-list-media-assets.api.mdx) API can help you with automating workflows with recordings and clips.
+The [Media Assets](/millicast/api/media-assets-list-media-assets.api.mdx) API can help you with automating workflows with stream recordings, live-to-vod clips, and media uploads.
 
 import GettingStartedRESTAPI from '../../callouts/_getting_started_rest_apis.md';
 
@@ -146,9 +154,9 @@ If you delete a recording or clip it is immediate and permanent. We are unable t
 
 Using the [Media Assets](/millicast/api/media-assets-list-media-assets.api.mdx) API you can identify the cloud storage location where recordings and clips are stored.
 
-### How-to Retrieve a Recording
+### How-to Retrieve a Media Asset
 
-Recordings will typically be stored on Dolby's servers and made available for retrieval. You'll need to know the `mediaAssetId` of the item you want to download.
+Media Assets are typically stored on Dolby's servers and made available for retrieval. You'll need to know the `mediaAssetId` of the item you want to download. This includes all media types including stream recordings, live-to-vod clips, and media uploads.
 
 #### Example GET Response
 
@@ -201,10 +209,114 @@ This is an example of a JSON response from the [/media/asset/\{mediaAssetId\}](/
     },
     "download": {
       "downloadUrl": "string",
-      "downloadExpiresOn": "2024-10-01T18:47:26.836Z"
+      "downloadExpiresOn": "2024-10-01T18:47:26.836Z",
+      "url": "string"
     }
   }
 }
 ```
 
-The `downloadUrl` gives you the storage location where a file is available to download using whichever software or libraries are most appropriate for your application needs.
+The `downloadUrl` gives you the storage location where a file is available to download using whichever software or libraries are most appropriate for your application needs. Generally this is a short-lived encrypted link intended for a one-time download.
+
+After your `downloadUrl` expires call the [/media/asset/\{mediaAssetId\}](/millicast/api/media-assets-read-media-asset.api.mdx) endpoint to retrieve a new one.
+
+## Managing Media Security
+
+If you want to construct download URLs without repeated API calls, or want fine-grain control over access to media assets, use the base `url` field and media distributions. These links are usually of the form `https://cdn.optiview.dolby.com/vod/...` and are intended to be served over Dolby's CDN. In order to use this you need to configure a **Media Distribution**.
+
+### Media Distributions
+
+A _media distribution_ is an object defining security settings for a subset of media assets on your account.
+You may have multiple media distributions with different security settings.
+Create and manage media distributions using the [Media Distributions](/millicast/api/media-distributions-create-media-distribution.api.mdx) API.
+
+Each media asset can be associated with one media distribution in one of the following ways:
+
+1. Specify the `mediaDistributionId` when creating a live-to-vod clip using the [Create Media Asset](/millicast/api/media-assets-create-media-asset.api.mdx) endpoint.
+2. Update the `mediaDistributionId` on an existing media asset using the [Update Media Asset](/millicast/api/media-assets-update-media-asset.api.mdx) endpoint.
+3. Set a default media distribution for your account using the [Create Media Distribution](/millicast/api/media-distributions-create-media-distribution.api.mdx) or [Update Media Distribution](/millicast/api/media-distributions-update-media-distribution.api.mdx) endpoint. Any new media assets created on your account will be associated with the default media distribution.
+
+If a media asset is not associated with a media distribution it cannot be viewed using the base `url`. There is no default media distribution created for you. This is because your assets would be unsecured if we made the distribution public and in order to create secure playback (assets protected by a JWT viewer token), you must provide a secret when creating the media distribution.
+
+### Unsecured Playback
+
+An unsecured media distribution is one with no security keys. Create an unsecured media distribution using the following curl command.
+
+```curl
+curl --request POST \
+  --url https://api.millicast.com/api/v3/media/distributions \
+  --header 'Authorization: Bearer abc123' \
+  --data '
+{
+  "name": "myUnsecuredDistribution"
+}
+'
+```
+
+To view a media asset associated with this distribution, simply use the `url` field from the [Read Media Asset](/millicast/api/media-assets-read-media-asset.api.mdx) response. You will see that the asset `url` is publicly readable by anyone with the link.
+
+### Secured Playback
+
+If you want to secure your media assets so that a signed JWT is required to view them, create a secured media distribution with your secret key.
+
+```curl
+curl --request POST \
+  --url https://api.millicast.com/api/v3/media/distributions \
+  --header 'Authorization: Bearer abc123' \
+  --data '
+{
+  "name": "mySecuredDistribution",
+  "security": {
+    "keys": [
+      {
+        "name": "mySecurityKey",
+        "key": "abcdefghijklmnopqrstuvwxyz1234567890"
+      }
+    ]
+  }
+}
+'
+```
+
+Retrieve the `id` of your security key from the response. Keep a record of your secret key since you will not be able to retrieve it again via the OptiView APIs.
+
+Any media assets associated with a media distribution with a security key cannot be viewed without a valid JWT.
+
+Create a JWT with a payload including the `id` of your media distribution security key as `mediaKeyId`, an expiry time and optionally a mediaAssetId. Use your secret key to sign the JWT.
+Below is an example JWT payload.
+
+```
+{
+  "mediaKeyId": "4d2ec682-12aa-4d20-b7d2-ffcf1825f735",
+  "mediaAssetId": "718f44d9319044fa908a5c6e6f70e26d",
+  "exp": 1770330326
+}
+```
+
+You may omit the `mediaAssetId` if you wish to create a token that is valid for all media assets associated with this media distribution.
+
+Retrieve the base download `url` from the [Read Media Asset](/millicast/api/media-assets-read-media-asset.api.mdx) response.
+Append the JWT as a `token` query parameter. The resulting url will look like
+
+```
+https://cdn.optiview.dolby.com/vod/{organisationId}/{mediaAssetId}/{filename}.{fileExtension}?token={jwt}
+```
+
+You may add a second security key to a media distribution for the purpose of key rotation. Either key can be used to sign your JWTs.
+
+## Predictable Paths
+
+Generally the url to download a media asset looks like
+
+```
+https://cdn.optiview.dolby.com/vod/{organisationId}/{mediaAssetId}/{filename}.{fileExtension}
+```
+
+When creating or uploading a media asset you may provide a `customPath` that will replace the `mediaAssetId` in the download path.
+The resulting url will look like
+
+```
+https://cdn.optiview.dolby.com/vod/{organisationId}/{customPath}/{filename}.{fileExtension}
+```
+
+Using custom paths enables prediction of the download url path without reading the `mediaAssetId` from the API response. This is commonly used in order to give 3rd parties predicable access to regular recordings without having them integrate with an API. In this case the `customPath` might be a date or `eventName-date`.

millicast/distribution/stream-recordings/how-to-setup-media-storage.md

@@ -4,9 +4,11 @@ title: How-to Setup Storage Profiles
 
 With [Live Clipping](live-clipping.mdx) you can have clips stored directly to your preferred third-party cloud storage provider. This gives you additional control over storage costs and manage usage of media clips.
 
-:::caution Not Available for Recordings
+:::caution Not Available for Recordings or live-to-VOD assets
 At this time, [Recordings](start-recording.mdx) cannot be configured to use a third-party cloud storage provider directly. You should follow the [How-to Get Media Assets](how-to-get-media-assets.mdx) guide to identify recordings for download and then you can upload them to your preferred provider of choice.
 
+Additionally, if you are using our workflow for [live-to-VOD clipping](/theolive/platform/live-clipping/) with a CDN servable HLS asset, this must be stored to Dolby's cloud storage in order to orchestrate the CDN.
+
 Similarly, **timelines** will always be stored in Dolby's storage subject to expiration rules.
 :::
 

millicast/distribution/stream-recordings/how-to-upload-media-assets.mdx

@@ -0,0 +1,78 @@
+---
+title: How-to Upload Media Assets
+---
+
+You can upload your own media assets to OptiView storage to be played back via the OptiView CDN. These are files that are pre-transcoded before upload for distribution and are served over Dolby's CDN and can be a single asset such as an MP4 or a multi-file asset such as an HLS asset that has a series of manifests and media files.
+
+The steps are as follows.
+
+1. Generate Upload Credentials
+1. Upload to Dolby's S3-Compatible Storage
+1. Register Media Asset
+
+## Generate Upload Credentials
+
+Use the [Generate Upload Credentials](/millicast/api/media-assets-get-upload-credentials.api.mdx) endpoint to generate credentials and an S3 compatible upload location.
+These credentials will last for 1 hour. Please upload and register media assets within the hour.
+
+This is an example response.
+
+```json
+{
+  "status": "success",
+  "data": {
+    "path": "string",
+    "bucketName": "string",
+    "objectPrefix": "string",
+    "accessKeyId": "string",
+    "secretAccessKey": "string",
+    "sessionToken": "string",
+    "expiration": "2026-01-12T01:27:13Z"
+  }
+}
+```
+
+## Upload to Dolby's S3-Compatible Storage
+
+Using the response fields _from the previous API call_, upload the media asset files to the specified S3 location.
+
+```
+$ AWS_ACCESS_KEY_ID=<from-above> AWS_SECRET_ACCESS_KEY=<from-above> AWS_SESSION_TOKEN=<from-above> aws s3 cp <filepath> s3://<bucketName>/<objectPrefix>
+```
+
+## Register Media Asset
+
+After completing upload make a [registration call](/millicast/api/media-assets-register-media-asset.api.mdx).
+
+The `mediaAssetId` returned in the response body can be used for inspecting, retrieving and deleting the media asset.
+
+This endpoint does not give immediate feedback on whether the media asset has been successfully created. Please use the [Read Media Asset](/millicast/api/media-assets-read-media-asset.api.mdx) endpoint to inspect the outcome of registration and retrieve the download url.
+
+### Example Usage 1 - Upload A Single File Asset
+
+If your asset has a single file such as an mp4 file, append the filename to the `objectPrefix` obtained from the [Generate Upload Credentials](/millicast/api/media-assets-get-upload-credentials.api.mdx) response.
+The [Register Media Asset](/millicast/api/media-assets-register-media-asset.api.mdx) request would look like
+
+```json
+{
+  "objectPrefix": "<object-prefix-from-above>/user-file.mp4"
+}
+```
+
+Assuming on inspection our service finds an object key that is an exact match of `objectPrefix`, OptiView will obtain and serve that single file.
+If there are any additional files uploaded to `s3://<bucketName>/<objectPrefix>/*` they will be ignored.
+
+### Example Usage 2 - Upload A Multi File Asset
+
+If your asset has multiple files such as an HLS asset with a main manifest and related manifests/media files, the [Register Media Asset](/millicast/api/media-assets-register-media-asset.api.mdx) request should look like this.
+
+```json
+{
+  "objectPrefix": "<object-prefix-from-api-response>",
+  "entrypoint": "main.m3u8"
+}
+```
+
+Since the `entrypoint` is specified, the discovery url for downloading the media asset via the CDN will be a link to a copy of `main.m3u8`.
+
+Assuming on inspection our service _does not_ find an object key which exactly matches the `objectPrefix`, OptiView will obtain and serve all the contents uploaded to `s3://<bucketName>/<objectPrefix>/*`.

millicast/distribution/stream-recordings/index.mdx

@@ -5,10 +5,11 @@ sidebar_position: 7
 
 import DocCardList from '@theme/DocCardList';
 
-With **_Stream Recording_** you can keep a copy of a real-time stream where media can be used for a variety of use cases such as video on demand (VOD) playback, archiving and auditing, event highlights and instant replay, etc. To support this variety of purposes there are options for the type of media assets that you will create from a stream.
+With **_Media Assets_** you can keep a copy of a real-time stream where media can be used for a variety of use cases such as video on demand (VOD) playback, archiving and auditing, event highlights and instant replay, etc. To support this variety of purposes there are options for the type of media assets that you will create from a stream. Here are the different types of media assets on the platform:
 
-- **Recordings** are full-length copies of a stream that will be processed and made available shortly after a broadcast is complete.
-- Live **Clips** are media files from a broadcast stream that can be processed and retrieved immediately while the live stream is still in progress.
+- **[Stream Recordings](/millicast/distribution/stream-recordings/):** Media captured by enabling _recording_ on a token, the entire stream from first to last frame is stored in the cloud as a single-layer "mezzanine" recording, usually stored in an MP4 container
+- **[Live-to-VOD clips](/millicast/distribution/stream-recordings/live-clipping/):** These assets are "clipped" out of a live streaming workflow as a servable HLS manifest that can be used for distribution and replays of the stream. These are referred to as "live clips" or "live clipping"
+- **[Media Uploads](/millicast/distribution/stream-recordings/how-to-upload-media-assets/):** Files that are pre-transcoded before upload for distribution and are served over Dolby's CDN
 
 You can work with recordings and clips either from the [Streaming Dashboard](/millicast/streaming-dashboard/index.mdx) or using the [Media Assets](/millicast/api/media-assets-list-media-assets.api.mdx) REST API.
 

millicast/distribution/stream-recordings/live-clipping.mdx

@@ -56,6 +56,8 @@ curl --request POST \
 
 The **stopTime** is optional and if not specified will use the last segment from the timeline (ie. "now"). The precise start and stop times of the resulting clip may vary slightly depending on encoding settings. We recommend that encoding settings use an **I-Frame** period of `1s` when using the service to increase precision when aligning keyframes with media segments.
 
+_Note: It is possible to generate CDN servable VOD assets with the service but requires advanced configuration with transcoding and packaging. Please contact your Dolby Account Team to learn about this workflow. You can [read more](/theolive/platform/live-clipping/) on how this feature is enabled._
+
 :::tip Enable Live Clipping
 Before beginning a broadcast, you must enable the `clip` setting on the [Publish Token](/millicast/streaming-dashboard/managing-your-tokens.mdx) being used for the stream. You will not be able to clip media until your broadcast with this setting has started.
 :::

millicast/getting-started/index.mdx

@@ -7,7 +7,7 @@ import DocCard from '@theme/DocCard';
 
 # Getting started with Millicast
 
-**Dolby.io Real-time Streaming APIs** make it easier to globally stream your high-value content with broadcast-quality color and sound to massive audiences all with sub 500ms latency. Use this tutorial to quickly set up and run your own private stream and begin building applications for a variety of use cases such as remote production, sports, gaming & betting, live events, etc.
+**Dolby's Real-time Streaming APIs make it easier to globally stream your high-value content with broadcast-quality picture and sound to massive audiences all with subsecond latency. Use this tutorial to quickly set up and run your own private stream and begin building applications for a variety of use cases.**
 
 :::tip[Dolby.io Account]
 Sign in into your [Dolby.io account](https://streaming.dolby.io) to access the Streaming Dashboard.

src/components/HomepageFeatures/index.tsx

@@ -49,8 +49,8 @@ const FeatureList: FeatureItem[] = [
     description: (
       <>
         <p>
-          Dolby OptiView&apos;s Live-streaming solution enables you to stream in ultra-low delay to any audience size with the best quality of
-          experience, whether it’s for sports betting, iGaming or interactive entertainment.
+          Dolby OptiView&apos;s Live-streaming solution enables you to stream with consistency to any audience size with the best quality of
+          experience, whether it&apos;s for a large live broadcast event, sports betting, or interactive entertainment.
         </p>
         <p>
           With this solution, choose Real-time for interactive latency or manage latency targets from 1 second and up with Live. Use both with the