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.

Mux

The Mux Developer Hub

Master Access