Overview
When a video is ingested into Mux we store a version of the video that's equivalent in quality to the original video (currently up to 1920x1080 pixels in frame size). We call this "the master version", or just The Master™. All of the streamed versions of the video are created from the master, and the master itself is never streamed to a video player because it's not optimized to be.
There's a few common use cases where Mux may have the only copy of the original video:
- You're using Mux live streaming and the only copy is the recorded asset after the event
- You're using Mux's Direct Upload feature so Mux has the only copy
- You deleted the original version from your own cloud storage, because Mux is already storing a high quality version for you
When this is the case, there's a number of reasons you may want to retrieve the master version from Mux, including:
- Allowing users to download the video and edit it in a tool like Final Cut Pro
- Archiving the video for the future, for example if you're un-publishing (deleting) a video asset from Mux
- Moving your videos to another service
Enabling master access will create a temporary URL to the master version as an MP4 file. You can use this URL to download the video to your own hosting, or provide the URL to a user to download directly from Mux.
The URL will expire after 24 hours, but you can enable master access on any asset at any time, and as many times as you need.
Enabling when an asset is created
If you want the master be available soon after a video is uploaded, use the master_access
property when creating an asset.
// POST https://api.mux.com/video/v1/assets
{
"input": "VIDEO_URL",
"playback_policy": "public",
"master_access": "temporary"
}
Enabling when a live stream finishes
If you want to allow users to download the recorded version of a live stream soon after the live stream is finished, use the master_access
property in the new_asset_settings
of a live stream.
// POST https://api.mux.com/video/v1/live-streams
{
"playback_policy": "public",
"new_asset_settings": {
"playback_policy": "public",
"master_access": "temporary"
}
}
Enable any time after an asset is created
Send a PUT request to the master-access
endpoint to add master access at any point after an asset is created and ready.
// PUT https://api.mux.com/video/v1/assets/{ASSET-ID}/master-access
{
"master_access": "temporary"
}
Retrieving the URL to the Master
After master access has been requested, a new object called master
will exist on the asset details object.
{
...all asset details...
"master_access": "temporary",
"master": {
"status": "preparing"
}
}
Making the master available is an asynchronous process that happens after an Asset is ready
, or in the case of a live streamed asset, after the live_stream_completed
event. Because of this, the master
object has a status
property that gives the current state of the master, starting with preparing
.
In most cases it should only take a few seconds to make the master available. When it's ready the status
will be updated to ready
, and a new url
property will exist on the object. This is the URL you can use to download the master yourself, or to let a user download the master.
{
...all asset details...
"master_access": "temporary",
"master": {
"status": "ready",
"url": "https://temporary.url.to.the.master.mp4"
}
}
Webooks for Master Access
Your application can be automatically updated with the status of master access for an asset through Webhooks.
There are four related events you can receive.
video.asset.master.preparing
Received when master access is first requested.
video.asset.master.ready
Received when the URL to the master is available.
video.asset.master.deleted
Received if master access has been set to none
via a PUT to the master-access
endpoint.
video.asset.master.errored
Received if an unexpected error happens while making the master available.
What else?
Did we miss any use cases for this feature, or leave any questions unanswered? Let us know so we can improve this guide.
Updated 2 years ago