This is a complete collection of developer guides for Mux.
# Stream videos in five minutes
Upload and play back your video files in your application using Mux in five minutes or less.
## 1. Get an API Access Token
The Mux Video API uses a token key pair that consists of a **Token ID** and **Token Secret** for authentication. If you haven't already, generate a new Access Token in the [Access Token settings](https://dashboard.mux.com/settings/access-tokens) of your Mux account dashboard.
You'll be presented with a form to create your new Access Token.
* **Access Tokens** belong to an **Environment** — a container for the various Access Tokens, Signing Keys, and assets that you'll come to add to Mux. For this guide, you can keep the **Production** environment selected.
* **Access Tokens** can have varying permissions to control what kinds of changes they have the ability to make. For this guide, your **Access Token** should have Mux Video **Read** and **Write** permissions.
* You can give your **Access Token** an internal-only name like "Onboarding" so you know where you've used it within your application.
Now, click the **Generate token** button.
You'll be presented with your new **Access Token ID** and **Secret Key**.
Once you have your new **Access Token ID** and **Secret Key**, you're ready to upload your first video.
## 2. POST a video
Videos stored in Mux are called assets. To create your first video asset, you need to send a POST request to the /assets endpoint and set the `input` value to the URL of a video file that's accessible online.
Here are a few demo videos you can use that are stored on common cloud storage services:
* Amazon S3: https://muxed.s3.amazonaws.com/leds.mp4
* Google Drive: https://drive.google.com/uc?id=13ODlJ-Dxrd7aJ7jy6lsz3bwyVW-ncb3v
* Dropbox: https://www.dropbox.com/scl/fi/l2sm1zyk6pydtosk3ovwo/get-started.mp4?rlkey=qjb34b0b7wgjbs5xj9vn4yevt\&dl=0
To start making API requests to Mux, you might want to install one of our officially supported API SDKs. These are lightweight wrapper libraries that use your API credentials to make authenticated HTTP requests to the Mux API.
```elixir
# mix.exs
def deps do
[
{:mux, "~> 1.8.0"}
]
end
```
```go
go get github.com/muxinc/mux-go
```
```node
# npm
npm install @mux/mux-node --save
# yarn
yarn add @mux/mux-node
```
```php
# composer.json
{
"require": {
"muxinc/mux-php": ">=0.0.1"
}
}
```
```python
# Via pip
pip install git+https://github.com/muxinc/mux-python.git
# Via source
git checkout https://github.com/muxinc/mux-python.git
cd mux-python
python setup.py install --user
```
```ruby
gem 'mux_ruby'
```
For an example of how to make API Requests from your local environment, see the [Make API Requests](/docs/core/make-api-requests) guide.
The response will include an **Asset ID** and a **Playback ID**.
* Asset IDs are used to manage assets using `api.mux.com` (e.g. to read or delete an asset).
* Playback IDs are used to stream an asset to a video player through `stream.mux.com`. You can add multiple playback IDs to an asset to create playback URLs with different viewing permissions, and you can delete playback IDs to remove access without deleting the asset.
```json
{
"data": {
"status": "preparing",
"playback_ids": [
{
"policy": "public",
"id": "TXjw00EgPBPS6acv7gBUEJ14PEr5XNWOe"
}
],
"video_quality": "basic",
"mp4_support": "none",
"master_access": "none",
"id": "01itgOBvgjAbES7Inwvu4kEBtsQ44HFL6",
"created_at": "1607876845"
}
}
```
Mux does not store the original file in its exact form, so if your original quality files are important to you, don't delete them after submitting them to Mux.
## 3. Wait for \`ready\`
As soon as you make the `POST` request, Mux begins downloading and processing the video. For shorter files, this often takes just a few seconds. Very large files over poor connections may take a few minutes (or longer).
When the video is ready for playback, the asset `status` changes to `ready`. You should wait until the asset status is `ready` before you attempt to play the video.
The best way to be notified of asset status updates is via **webhooks**. Mux can send a webhook notification as soon as the asset is ready. See the [webhooks guide](/docs/core/listen-for-webhooks) for details.
If you can't use webhooks for some reason, you can manually **poll** the asset API to see asset status. Note that this only works at low volume. Try this example:
## Try an example request
Please don't poll this API more than once per second.
## 4. Watch your Video
To play back an asset, create a playback URL using the `PLAYBACK_ID` you received when you created the asset.
```curl
https://stream.mux.com/{PLAYBACK_ID}.m3u8
```
## Preview in a player
```android
implementation 'com.google.android.exoplayer:exoplayer-hls:2.X.X'
// Create a player instance.
SimpleExoPlayer player = new SimpleExoPlayer.Builder(context).build();
// Set the media item to be played.
player.setMediaItem(MediaItem.fromUri("https://stream.mux.com/{PLAYBACK_ID}.m3u8"));
// Prepare the player.
player.prepare();
```
```embed
```
```html
```
```react
import MuxPlayer from '@mux/mux-player-react';
export default function VideoPlayer() {
return (
);
}
```
```swift
import SwiftUI
import AVKit
let playbackID = "qxb01i6T202018GFS02vp9RIe01icTcDCjVzQpmaB00CUisJ4"
struct ContentView: View {
private let player = AVPlayer(
url: URL.makePlaybackURL(
playbackID: playbackID
)
)
var body: some View {
// VideoPlayer comes from SwiftUI
// Alternatively, you can use AVPlayerLayer or AVPlayerViewController
VideoPlayer(player: player)
.onAppear() {
player.play()
}
}
}
struct ContentView_Previews: PreviewProvider {
static var previews: some View {
ContentView()
}
}
extension URL {
static func makePlaybackURL(
playbackID: String
) -> URL {
guard let baseURL = URL(
string: "https://stream.mux.com"
) else {
preconditionFailure("Invalid base URL string")
}
guard let playbackURL = URL(
string: "\(playbackID).m3u8",
relativeTo: baseURL
) else {
preconditionFailure("Invalid playback URL component")
}
return playbackURL
}
}
```
See the [playback guide](/docs/guides/play-your-videos) for more information about how to integrate with a video player.
## Preview with `stream.new`
[Stream.new](https://stream.new/) is an open source project by Mux that allows you to add a video and get a shareable link to stream it.
Go to `stream.new/v/{PLAYBACK_ID}` to preview your video streaming. This URL is shareable and automatically generated using the video playback ID. Copy the link below and open it in a browser to view your video.
```
https://stream.new/v/{PLAYBACK_ID}
```
After you have everything working [integrate Mux Data](/docs/guides/track-your-video-performance) with your player for monitoring playback performance.
## 5. Manage your Mux assets
After you have assets created in your Mux environment, you may find some of these other endpoints handy:
* Create an asset
* List assets
* Retrieve an asset
* Delete an asset
* Retrieve asset input info
* Create asset playback ID
* Retrieve asset playback ID
* Delete asset playback ID
* Update MP4 support on asset
* Update master access on asset
* Update asset track
* Delete an asset track
More Video methods and descriptions are available at the API Docs.
# Next Steps
# Mux fundamentals
A reference guide covering the essential concepts, terminology, and components you need to understand when building with Mux.
Whether you're just getting started with Mux or need a quick refresher on how the pieces fit together, this guide covers the fundamental concepts you'll encounter when building video, audio, and live streaming applications.
# Quick reference
| Term | Description |
| :--- | :---------- |
| [**Organization**](#organizations) | The top-level account container. You can belong to multiple organizations, each with its own billing, team members, and environments. |
| [**Environment**](#environments) | A container within an organization for organizing your Mux resources (assets, live streams, API tokens, etc.). Each organization can have multiple environments. |
| [**Access Token**](#access-tokens) | A credential pair (Token ID + Token Secret) used to authenticate API requests. Scoped to a single environment. |
| [**Asset**](#assets) | A video or audio file that has been uploaded to Mux and processed for streaming playback. |
| [**Playback ID**](#playback-ids) | A unique identifier used to stream an asset or live stream to viewers. |
| [**Live Stream**](#live-streams) | A resource representing a live broadcast that can receive RTMP/SRT input and deliver to viewers. |
| [**Stream Key**](#live-streams) | A secret credential that allows a broadcaster to push video to a specific live stream. |
| [**Signing Key**](#signing-keys) | A public/private key pair used to create signed tokens (JWTs) for secure playback. |
| [**Webhook**](#webhooks) | An HTTP callback that Mux sends to your server when events occur (e.g., asset ready, live stream started). |
# Organizations
An **organization** is your top-level Mux account. It's the highest container in the Mux hierarchy and contains everything else: environments, team members, and billing settings.
Key things to know about organizations:
* **You can belong to multiple organizations.** This is useful if you work with different companies or clients, each with their own Mux account.
* **Each organization has its own billing.** Usage charges are tracked and billed per organization.
* **Team members are managed at the organization level.** You can invite collaborators and assign roles (Admin, Member) within each organization.
* **Organizations contain environments.** All your media resources live inside environments, which live inside organizations.
You can switch between organizations and create new ones from the [Mux Dashboard](https://dashboard.mux.com/organizations).
# Environments
An **environment** is a container within an organization for organizing your Mux resources. Each environment has its own isolated set of assets, live streams, access tokens, signing keys, and webhooks.
Common use cases for multiple environments:
* Separate **development** and **production** resources
* Isolate resources for different websites or domains (e.g., `site1.com`, `site2.com`)
* Organize by project or use case (e.g., CMS media, marketing site, customer uploads)
* Keep test data separate from production content
Resources are scoped to their environment. An access token created in Development cannot be used to manage assets in Production, and webhooks configured for one environment won't fire for events in another.
You can view and manage environments in the [Mux Dashboard](https://dashboard.mux.com/organizations).
# Access Tokens
**Access tokens** are credentials that authenticate your API requests to Mux. Each token consists of two parts:
| Part | Description |
| :--- | :---------- |
| **Token ID** | The "username" portion of your credential. Safe to log (but not expose publicly). |
| **Token Secret** | The "password" portion. Keep this secure and never expose it in client-side code. |
Mux only stores a hash of your token secret. If you lose it, you'll need to create a new access token.
Mux API requests must be made from a server, not from client-side code. The API does not support CORS, and exposing your credentials in a browser or mobile app is a security risk.
## Token permissions
When creating an access token, you configure which permissions it has:
| Permission | Use case |
| :--------- | :------- |
| **Mux Video Read** | Retrieve information about assets and live streams |
| **Mux Video Write** | Create, update, and delete assets and live streams |
| **Mux Data Read** | Access playback performance metrics |
| **Mux Data Write** | Create Data annotations |
| **System Read** | View signing keys and other system resources |
| **System Write** | Create and manage signing keys |
For most use cases when getting started, you'll want **Mux Video Read** and **Write** permissions.
You can create and manage access tokens in the [Mux Dashboard](https://dashboard.mux.com/settings/access-tokens).
**Learn more:** [Make API requests](/docs/core/make-api-requests) | [Use an SDK](/docs/core/sdks)
# Assets
An **asset** is a video or audio file that has been ingested into Mux and processed for adaptive bitrate streaming. When you create an asset, Mux:
1. Downloads the file from your provided URL (or receives it via [direct upload](/docs/guides/upload-files-directly))
2. Transcodes it into multiple quality levels
3. Packages it for HLS streaming
4. Generates a unique **asset ID**
```json
// Example asset response
{
"data": {
"id": "01itgOBvgjAbES7Inwvu4kEBtsQ44HFL6",
"status": "ready",
"playback_ids": [
{
"id": "TXjw00EgPBPS6acv7gBUEJ14PEr5XNWOe",
"policy": "public"
}
],
"duration": 120.5,
"aspect_ratio": "16:9"
}
}
```
## Asset status lifecycle
Assets progress through several statuses:
| Status | Description |
| :----- | :---------- |
| `preparing` | Mux is downloading and processing the file |
| `ready` | The asset is ready for playback |
| `errored` | Something went wrong during processing |
Rather than polling the API to check status, use [webhooks](/docs/core/listen-for-webhooks) to be notified when an asset is ready.
**Learn more:** [Stream videos in five minutes](/docs/core/stream-video-files) | Assets API
# Playback IDs
A **playback ID** is what you use to actually stream content to viewers. While asset IDs are used to *manage* your content (via `api.mux.com`), playback IDs are used to *stream* your content (via `stream.mux.com`).
```
https://stream.mux.com/{PLAYBACK_ID}.m3u8
```
## Playback policies
Each playback ID has a policy that controls how it can be accessed:
| Policy | Description |
| :----- | :---------- |
| `public` | Anyone with the URL can access the content |
| `signed` | Viewers need a valid JWT token to watch |
An asset can have multiple playback IDs with different policies. This lets you, for example, have a public playback ID for trailers and a signed playback ID for the full content.
You can add and remove playback IDs without affecting the underlying asset. This is useful for revoking access without re-encoding your content.
**Learn more:** [Play your videos](/docs/guides/play-your-videos) | [Secure video playback](/docs/guides/secure-video-playback)
# Live streams
A **live stream** represents a live broadcast channel. Unlike assets (which are created from existing files), live streams receive real-time input and deliver it to viewers with low latency.
## Key live stream components
| Component | Description |
| :-------- | :---------- |
| **Stream Key** | A secret credential broadcasters use to connect their encoder to Mux |
| **RTMP URL** | The ingest endpoint (`rtmp://global-live.mux.com:5222/app`) |
| **SRT URL** | Alternative ingest endpoint for SRT protocol |
| **Playback ID** | Used to stream to viewers (same concept as asset playback IDs) |
Anyone with your stream key can broadcast to your live stream. Treat it like a password.
## Live stream lifecycle
| Status | Description |
| :----- | :---------- |
| `idle` | No one is broadcasting; waiting for input |
| `active` | A broadcaster is connected and viewers can watch |
| `disabled` | The live stream has been disabled and won't accept connections |
When a live stream ends, Mux automatically creates a new asset from the recording (if recording is enabled).
**Learn more:** [Configure broadcast software](/docs/guides/configure-broadcast-software) | [Handle disconnections](/docs/guides/handle-live-stream-disconnects) | Live Streams API
# Signing keys
**Signing keys** are cryptographic key pairs used to generate JWTs (JSON Web Tokens) for [secure video playback](/docs/guides/secure-video-playback). When you have assets or live streams with `signed` playback policies, you need signing keys to create valid playback tokens.
| Component | Description |
| :-------- | :---------- |
| **Key ID** | A unique identifier for the signing key |
| **Private Key** | Used by your server to sign JWTs. Keep this secret. |
Your server uses the private key to create short-lived tokens that grant access to specific content. The token can include claims for:
* **Expiration time** - When the token becomes invalid
* **Playback restrictions** - Additional rules like allowed domains
Signing keys and access tokens serve different purposes:
* **Access tokens** authenticate your server-to-Mux API requests
* **Signing keys** create tokens that authenticate viewer playback requests
You can create and manage signing keys in the [Mux Dashboard](https://dashboard.mux.com/settings/signing-keys).
**Learn more:** [Secure video playback](/docs/guides/secure-video-playback) | Signing Keys API
# Webhooks
**Webhooks** are HTTP callbacks that Mux sends to your application when events occur. Instead of repeatedly polling the API to check if an asset is ready, you configure a webhook URL and Mux notifies you automatically.
Common webhook events:
| Event | Description |
| :---- | :---------- |
| `video.asset.ready` | An asset has finished processing and is ready for playback |
| `video.asset.errored` | An asset failed to process |
| `video.live_stream.active` | A live stream has started broadcasting |
| `video.live_stream.idle` | A live stream has stopped broadcasting |
| `video.upload.asset_created` | A direct upload has completed and created an asset |
Webhooks are configured per environment. Make sure your webhook is set up in the same environment where your resources are created.
**Learn more:** [Listen for webhooks](/docs/core/listen-for-webhooks) | [Verify webhook signatures](/docs/core/verify-webhook-signatures)
# IDs at a glance
Mux uses several different types of identifiers. Here's a quick reference:
| ID Type | Format Example | Purpose |
| :------ | :------------- | :------ |
| **Organization ID** | `abc123` | Identify your organization |
| **Environment ID** | `j0863n` | Identify specific environments within an organization |
| **Asset ID** | `01itgOBvgj...` | Identify and manage assets via the API |
| **Playback ID** | `TXjw00EgPB...` | Stream content to viewers |
| **Live Stream ID** | `aA02skpHX...` | Identify and manage live streams via the API |
| **Upload ID** | `OA02dANZ...` | Track direct upload status |
| **Token ID** | `44c819de-4add-...` | Identify access tokens (part of API auth) |
| **Signing Key ID** | `JjPXgkqO...` | Identify signing keys for JWT creation |
# SDKs
Mux provides official SDKs for several languages that handle authentication and make it easier to work with the API:
* [Node.js](/docs/integrations/mux-node-sdk)
* [Python](/docs/integrations/mux-python-sdk)
* [Ruby](/docs/integrations/mux-ruby-sdk)
* [PHP](/docs/integrations/mux-php-sdk)
* [Java](/docs/integrations/mux-java-sdk)
* [C# / .NET](/docs/integrations/mux-csharp-sdk)
* [Elixir](/docs/integrations/mux-elixir-sdk)
For client-side playback, see [Mux Player](/docs/guides/mux-player-web) and the various player SDK guides.
**Learn more:** [Use an SDK](/docs/core/sdks)
# API and webhook specifications
Mux publishes machine-readable specifications for both the API and webhook events:
| Specification | URL | Description |
| :------------ | :-- | :---------- |
| **Combined spec** | [`mux.com/full-combined-spec.json`](https://www.mux.com/full-combined-spec.json) | All API endpoints and webhook events in one spec |
| **API spec** | [`mux.com/api-spec.json`](https://www.mux.com/api-spec.json) | Core API endpoints only |
| **Webhook spec** | [`mux.com/webhook-spec.json`](https://www.mux.com/webhook-spec.json) | Webhook event schemas only |
| **Image API spec** | [`mux.com/image-spec.json`](https://www.mux.com/image-spec.json) | Thumbnail, animated GIF, and storyboard endpoints |
| **Streaming API spec** | [`mux.com/stream-spec.json`](https://www.mux.com/stream-spec.json) | HLS and MP4 streaming playback endpoints |
| **Engagement Counts spec** | [`mux.com/stats-spec.json`](https://www.mux.com/stats-spec.json) | Real-time view and viewer count endpoints |
These are useful for generating API clients, importing into tools like [Postman](/docs/core/postman), validating webhook payloads, or integrating with any tooling that supports OpenAPI. Use the combined spec if you want everything in one file.
# What's next?
Now that you understand the fundamentals, here are some recommended next steps:
# Getting started for AI agents
A reference for LLMs and AI agents writing code against the Mux API.
# Getting started for AI agents
This guide is written for LLMs and AI coding agents. It contains everything you need to write working code against the Mux API on the first try.
## CLI
The [Mux CLI](/docs/integrations/mux-cli) (`@mux/cli`) lets you manage Mux resources directly from the terminal. It is useful for quick operations, scripting, automation, and CI/CD pipelines.
Install:
```bash
npm install -g @mux/cli # global install
# or run directly without installing:
npx @mux/cli
# or install via Homebrew:
brew install muxinc/tap/mux
```
After installing, authenticate with `mux login` or set `MUX_TOKEN_ID` and `MUX_TOKEN_SECRET` environment variables. Always pass `--agent` to optimize output for AI agents (includes JSON output).
Common commands:
| Command | What it does |
| :--- | :--- |
| `mux assets create --input-url URL` | Create an asset from a URL |
| `mux assets create --file video.mp4` | Upload a local file |
| `mux assets list` | List assets |
| `mux assets get ${ASSET_ID}` | Get asset details |
| `mux assets delete ${ASSET_ID}` | Delete an asset |
| `mux live-streams create` | Create a live stream |
| `mux uploads create` | Create a direct upload URL |
| `mux sign ${PLAYBACK_ID}` | Generate a signed playback URL |
Use `--wait` to block until an asset is ready:
```bash
mux assets create --input-url "https://example.com/video.mp4" --wait --agent
```
For the full list of commands, see the [CLI documentation](/docs/integrations/mux-cli).
## Common resources
* [Authentication and making API requests](/docs/core/make-api-requests) — how to authenticate with the Mux API
* [Rate limits](/docs/core/make-api-requests#api-rate-limits) — API rate limit details
* [Full API reference](/docs/api-reference/video) — complete endpoint documentation
* [Webhooks guide](/docs/core/listen-for-webhooks) — listen for events like `video.asset.ready`
* [Mux Player guide](/docs/guides/play-your-videos) — the easiest way to play Mux videos
* [Direct uploads guide](/docs/guides/upload-files-directly) — let users upload video files from the browser
* [Stream video files guide](/docs/core/stream-video-files) — ingest a video, wait for it to be ready, get a playback URL
* [Live streaming guide](/docs/guides/start-live-streaming) — set up live streams
* [Secure video playback](/docs/guides/secure-video-playback) — signed playback for private content
* [Static MP4 renditions guide](/docs/guides/enable-static-mp4-renditions) — downloadable MP4/M4A files
* [MCP Server](/docs/integrations/mcp-server) — use Mux from AI tools that support MCP
* [Docs for LLMs](/docs/core/llms-txt) — machine-readable documentation bundles
* [OpenAPI spec](https://www.mux.com/api-spec.json) — full API specification
## Instructions for your human
Before you can make API calls, your user needs to set up a Mux account and provide you with API credentials.
1. **Sign up for Mux** at the [Mux dashboard](https://dashboard.mux.com/signup). No credit card is required. The free tier includes enough usage to develop and test.
2. **Go to the [Mux dashboard](https://dashboard.mux.com)**, then navigate to **Settings → Access Tokens**.
3. **Create an API access token** with all permissions — **Mux Video**, **Mux Data**, and **System** — with read and write access.
4. **Save the Access Token ID and Access Token Secret.** The secret is only shown once.
Store the credentials as environment variables:
```bash
MUX_TOKEN_ID=your-token-id
MUX_TOKEN_SECRET=your-token-secret
```
For details on how authentication works, see the [make API requests guide](/docs/core/make-api-requests).
Never expose API credentials in client-side code. All Mux API calls must be made from a server.
## Two main ways to use Mux
### Website embed
This is for when you have a small, constrained number of videos — a hero video or background video on your homepage, a demo reel, or a few dozen videos across your site. The key characteristic is that the set of videos doesn't change often and is manageable enough to hardcode.
In this case, you can hardcode playback IDs directly in your code or extract them into a JSON config file with metadata:
```json
{
"videos": [
{ "title": "Hero Video", "playbackId": "TXjw00EgPBPS6acv7gBUEJ14PEr5XNWOe" },
{ "title": "Product Demo", "playbackId": "a4nOgR00sKz6cMWLeM5skT8ePBn7U6gC5" }
]
}
```
Then use [Mux Player](/docs/guides/play-your-videos) to embed each video:
```jsx
import MuxPlayer from '@mux/mux-player-react';
```
To create your assets and get playback IDs, use the CLI (`mux assets create --input-url URL --wait --json`) or the [stream video files guide](/docs/core/stream-video-files).
### User uploaded
This is for when videos are uploaded dynamically as part of your application. Common scenarios include:
* **Admin-managed content** — an admin area where authorized users upload and manage videos (e.g., a course platform, media library, or CMS)
* **User-generated content (UGC)** — end users upload their own videos (e.g., a social platform, portfolio site, or community forum)
* **Programmatic ingestion** — videos are created automatically from external sources or pipelines
For these use cases, you will need to:
1. **Accept uploads** — use [direct uploads](/docs/guides/upload-files-directly) to let users upload video files from the browser, or create assets server-side from URLs using the [stream video files guide](/docs/core/stream-video-files)
2. **Listen for events** — use [webhooks](/docs/core/listen-for-webhooks) to know when a video is ready for playback (`video.asset.ready`), when it errors, or when it's deleted
3. **Persist video data** — store asset IDs, playback IDs, status, and metadata in your database (see [Persisting Mux data](#persisting-mux-data) below)
4. **Play videos** — use [Mux Player](/docs/guides/play-your-videos) with the stored playback ID
## SDKs
Official server-side SDKs:
| Language | Package | Docs |
| :--- | :--- | :--- |
| Node.js | `@mux/mux-node` | [Guide](/docs/integrations/mux-node-sdk) |
| Python | `mux_python` | [Guide](/docs/integrations/mux-python-sdk) |
| Ruby | `mux_ruby` | [Guide](/docs/integrations/mux-ruby-sdk) |
| PHP | `mux-php` | [Guide](/docs/integrations/mux-php-sdk) |
| Go | `mux-go` | [GitHub](https://github.com/muxinc/mux-go) |
| Java | `com.mux:mux-sdk-java` | [Guide](/docs/integrations/mux-java-sdk) |
| C# | `Mux.Csharp.Sdk` | [Guide](/docs/integrations/mux-csharp-sdk) |
| Elixir | `mux` | [Guide](/docs/integrations/mux-elixir-sdk) |
## Sensible defaults
Unless the user specifies otherwise, use these values:
| Parameter | Default to use | Notes |
| :--- | :--- | :--- |
| `playback_policy` | `["public"]` | Use `"signed"` only if the user needs secure/private playback |
| `video_quality` | `"basic"` | No encoding costs and great for most use cases. Use `"plus"` if the user needs higher quality encoding |
| `static_renditions` | Do not set | Only set if the user explicitly needs downloadable MP4/M4A files. See the [static renditions guide](/docs/guides/enable-static-mp4-renditions) |
| `max_resolution_tier` | Do not set | Defaults to `1080p`. Set to `"2160p"` only if the user requests 4K |
### Cross-references for defaults
* `playback_policy`: `"public"` allows open access. Use `"signed"` for [secure video playback](/docs/guides/secure-video-playback) with [signed JWTs](/docs/guides/signing-jwts).
* `video_quality`: See [pricing](/docs/pricing/video) for the difference between `"basic"` and `"plus"`.
* `static_renditions`: Replaces the deprecated `mp4_support` parameter. Use `[{ "resolution": "highest" }]` for an MP4 download or `[{ "resolution": "audio-only" }]` for an M4A file. See the [static renditions guide](/docs/guides/enable-static-mp4-renditions) for all options.
## Persisting Mux data
After creating an asset, save the relevant data into your database or persistence layer. At minimum, store the **asset ID** and **playback ID**. You will also want to save metadata as it becomes available: `status`, `duration`, `aspect_ratio`, `resolution_tier`, and any `static_renditions` information.
For **simple integrations** with a fixed set of videos — hero videos, background videos, demo reels on a marketing site — you can hardcode playback IDs in a JSON file or config object. These rarely change and don't need a database.
For **production applications** where users upload videos, videos are created programmatically, or the video catalog changes over time, always persist asset data in a database. Use [webhooks](/docs/core/listen-for-webhooks) to keep your database in sync — listen for `video.asset.ready` to update status, and `video.asset.deleted` to clean up records.
## IDs reference
| ID type | What it's for |
| :--- | :--- |
| Asset ID | Managing the asset (get, update, delete) via `api.mux.com` |
| Playback ID | Streaming the video via `stream.mux.com` |
| Upload ID | Tracking direct upload status |
| Stream Key | Broadcasting to a live stream (keep secret) |
| Live Stream ID | Managing the live stream via `api.mux.com` |
## Common mistakes
**Do NOT confuse Asset IDs with Playback IDs.** Asset IDs are for API operations (`api.mux.com`). Playback IDs are for streaming (`stream.mux.com`). They are different strings.
**Do NOT use the playback URL before the asset is ready.** Always check `status === "ready"` first. A playback URL for a `preparing` asset will not work.
**Do NOT construct playback URLs with the Asset ID.** The correct URL is `https://stream.mux.com/{PLAYBACK_ID}.m3u8`, not `https://stream.mux.com/{ASSET_ID}.m3u8`.
**Do NOT expose API keys in client-side code.** API credentials (Token ID and Token Secret) must never be included in frontend JavaScript, mobile apps, or any code that runs on the user's device. All Mux API requests must be made from a trusted server.
**Do NOT expose stream keys in client-side code.** Stream keys allow anyone to broadcast to your live stream. Keep them server-side only.
**Do NOT hardcode playback URLs.** Always construct them from the playback ID returned by the API.
**Do NOT poll more than once per second.** The API has rate limits. Poll every 2 seconds for asset status.
**Do NOT use `POST` endpoints at high volume without backoff.** POST requests are rate limited to ~1 request per second sustained. GET requests allow ~5 per second.
# Make API requests
Learn how to work with Mux's API through HTTP requests.
## HTTP basic auth
| Term | Description |
| :----------- | :----------------------------------------------------- |
| Token ID | access token ID, the "username" in HTTP basic auth |
| Token secret | access token secret, the "password" in HTTP basic auth |
Every request to the API is authenticated via an [Access Token](https://dashboard.mux.com/settings/access-tokens), which includes the ID and the secret key. You can think of the Access Token’s ID as its username and secret as the password. Mux only stores a hash of the secret, not the secret itself. If you lose the secret key for your access token, Mux cannot recover it; you will have to create a new Access Token. If the secret key for an Access Token is leaked you should revoke that Access Token on the settings page: https://dashboard.mux.com/settings/access-tokens.
Note that in order to access the settings page for access tokens you must be an admin on the Mux organization.
API requests are authenticated via HTTP Basic Auth, where the username is the Access Token ID, and the password is the Access Token secret key. Due to the use of Basic Authentication and because doing so is just a Really Good Idea™, all API requests must made via HTTPS (to `https://api.mux.com`).
Access tokens are scoped to an environment, for example: a development token cannot be used in requests to production. Verify the intended environment when creating an access token.
This is an example of authenticating a request with cURL, which automatically handles HTTP Basic Auth. If you run this request yourself it will not work, you should replace the Access Token ID (`44c819de-4add-4c9f-b2e9-384a0a71bede`) and secret (`INKxCoZ+cX6l1yrR6vqzYHVaeFEcqvZShznWM1U/No8KsV7h6Jxu1XXuTUQ91sdiGONK3H7NE7H`) in this example with your own credentials.
```shell
curl https://api.mux.com/video/v1/assets \
-H "Content-Type: application/json" \
-X POST \
-d '{ "inputs": [{ "url": "https://muxed.s3.amazonaws.com/leds.mp4" }], "playback_policies": ["public"], "video_quality": "basic" }' \
-u 44c819de-4add-4c9f-b2e9-384a0a71bede:INKxCoZ+cX6l1yrR6vqzYHVaeFEcqvZShznWM1U/No8KsV7h6Jxu1XXuTUQ91sdiGONK3H7NE7H
```
HTTP basic auth works by base64 encoding the username and password in an `Authorization` header on the request.
Specifically, the header looks something like this:
```bash
'Authorization': 'Basic base64(MUX_TOKEN_ID:MUX_TOKEN_SECRET)'
```
1. The access token ID and secret are concatenated with a `:` and the string is base64 encoded.
2. The value for the `Authorization` header is the string `Basic` plus a space ` ` followed by the base64 encoded result from Step 1.
In the cURL example above, the cURL library is taking care of the base64 encoding and setting the header value internally. The HTTP library you use in your server-side language will probably have something similar for handling basic auth. You should be able to pass in the `username` (Access Token ID) and `password` (Access Token secret) and the library will handle the details of formatting the header.
## Access token permissions
If you're just getting started with Mux Video, use Read and Write.
If you are creating or modifying resources with Mux Video then you need **Read** and **Write** permissions. This includes things like:
* Creating new assets
* Creating direct uploads
* Creating new live streams
If you need to create signed tokens for secure video playback, your access token needs **System** write permissions. Learn more about [secure video playback](/docs/guides/secure-video-playback) and signing keys.
Mux Data only requires **Write** permissions if you need to create Annotations via API. Annotations created in the Dashboard do not require **Write** permissions.
If your code is not creating anything and only doing `GET` requests then you can restrict the access token to **Read** only.
## CORS and client side API requests
Mux API endpoints do not have CORS headers, which means if you try to call the Mux API from the browser you will get an error:
request has been blocked by CORS policy: Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource.
This is expected. Although making API requests directly from the browser or your mobile app would be convenient, it leaves a massive security hole in your application by the fact that your client side code would contain your API keys. Anyone who accesses your application would have the ability to steal your API credentials and make requests to Mux on your behalf. An attacker would be able to gain full control of your Mux account.
Mux API Credentials should never be stored in a client application. All Mux API calls should be made from a trusted server.
Instead of trying to make API requests from the client, the flow that your application should follow is:
1. Client makes a request to your server
2. Your server makes an authenticated API request to Mux
3. Your server saves whatever it needs in your database
4. Your server responds to the client with only the information that the client needs. For example, with live streaming that's the stream key for a specific stream, for uploads that's just the direct upload URL
## Using Mux with serverless functions
Serverless functions are a great way to add pieces of secure server-side code to your client heavy application. Examples of services that help you run serverless functions are:
* [AWS Lambda](https://aws.amazon.com/lambda/)
* [Firebase Cloud Functions](https://firebase.google.com/docs/functions)
* [Cloudflare Workers](https://workers.cloudflare.com/)
* [Vercel Functions](https://vercel.com/docs/functions)
* [Netlify Functions](https://docs.netlify.com/functions/overview/)
The basic idea behind serverless functions is that you can write a bit of server code and deploy it to run on these platforms. Your client application can make requests to these endpoints to perform specific actions. Below is an example from [with-mux-video](https://github.com/vercel/next.js/blob/canary/examples/with-mux-video/pages/api/upload.js) of a serverless function endpoint that makes an API call to create a Mux Direct Upload.
```js
// pages/api/upload.js
// see: https://github.com/vercel/next.js/tree/canary/examples/with-mux-video
import Mux from '@mux/mux-node';
const mux = new Mux();
export default async function uploadHandler(req, res) {
const { method } = req;
switch (method) {
case 'POST':
try {
const upload = await mux.video.uploads.create({
new_asset_settings: { playback_policy: ['public'], video_quality: 'basic' },
cors_origin: '*',
});
res.json({
id: upload.id,
url: upload.url,
});
} catch (e) {
console.error('Request error', e);
res.status(500).json({ error: 'Error creating upload' });
}
break;
default:
res.setHeader('Allow', ['POST']);
res.status(405).end(`Method ${method} Not Allowed`);
}
}
```
## API pagination
Our list endpoints (such as List Assets) do not return every single relevant record.
To offer everyone the best performance we limit the amount of records you can receive and offer pagination parameters to help you navigate through your list.
### Page/limit pagination
Our most common pagination controls are `page` and `limit`.
| Parameter | Default | Maximum | Description |
| :-------- | :------ | :---- | :--------------------------------------------------|
| `page` | `1` | None | The page number to return. The first page is `1`. |
| `limit` | `10` | `100` | The number of records to return per page. |
If you have 100 assets and you want to get the first 10, you would make a request like this:
```http
GET /video/v1/assets?page=1&limit=10
```
And if you want to get the next 10, you would increment the page parameter from `1` to `2` and make a request like this:
```http
GET /video/v1/assets?page=2&limit=10
```
### Cursor pagination
In addition to `page`/`limit`, the List Assets endpoint also supports cursor pagination.
Cursor pagination is a more efficient and reliable way of paginating through very large collections.
Cursor pagination is only available on the List Assets endpoint, but we plan to add it to more endpoints in the future. If you want it added to any specific endpoints please [let us know!](/support)
When you make a request to the list assets endpoint we return a `next_cursor` value.
```json
// GET /video/v1/assets
{
"data": [
{
"id": "asset_id",
"status": "ready",
...
}
],
"next_cursor": "eyJwYWdlX2xpbWl0IjoxMDAwLCJwYWdlX2NvdW50IjoxfQ"
}
```
Take that `next_cursor` value and make a new request to the list assets endpoint with the `cursor` parameter.
```json
// GET /video/v1/assets?cursor=eyJwYWdlX2xpbWl0IjoxMDAwLCJwYWdlX2NvdW50IjoxfQ
{
"data": [
{
"id": "asset_id",
"status": "ready",
...
}
],
"next_cursor": null
}
```
If `next_cursor` is `null`, you've reached the end of your list. If `next_cursor` is not `null` you can use that value to get the next page, repeating this pattern until `next_cursor` is `null`.
## API rate limits
Mux Video implements a simple set of rate limits. Rate limits are set per account (not per environment). These rate limits exist for two reasons:
1. First, to protect you, or customers from runaway scripts or batch process - we don't want you to accidentally delete all your content, or run up a large bill if you're not expecting it.
2. Second, to ensure that there's always Mux infrastructure available when our customers need it, for example to start that critical live stream, or ingest that urgent video.
When the rate limit threshold is exceeded, the API will return a HTTP status code `429`.
### Video API
1. All Video API activities that include a `POST` request to `https://api.mux.com/video/` are rate limited to a sustained 1 request per second (RPS) with the ability to burst above this for short periods of time. This includes creating new Assets, Live Streams, and Uploads.
2. All other request methods are limited to 5 sustained requests per second (RPS) with the ability to burst above this for short periods of time. This includes `GET`, `PUT`, `PATCH`, & `DELETE` verbs. Examples include (but not limited to) requests for retrieving an asset, updating mp4 support, & listing delivery usage.
### Playback
There are no limits as to the number of viewers that your streams can have, all we ask is that you let us know if you're planning an event expected to receive more than 100,000 concurrent live viewers.
### Monitoring Data API
Requests against the Monitoring Data APIs are rate limited to a sustained 1 request per second (RPS) with the ability to burst above this for short periods of time.
### General Data API
Requests against the all other General Data APIs are rate limited to a sustained 5 request per second (RPS) with the ability to burst above this for short periods of time.
# OpenAPI specification
The complete Mux API is described by an OpenAPI specification, available at [`https://www.mux.com/api-spec.json`](https://www.mux.com/api-spec.json). You can use this spec to generate API clients, import endpoints into tools like [Postman](/docs/core/postman), or integrate with any tooling that supports OpenAPI.
# Use a Mux SDK
Mux SDKs are available for a variety of languages and platforms.
Mux has API SDKs for several major languages. You are not required to use them, but these SDKs handle the details of authentication for you and make it a little nicer to send API requests to Mux; in languages with static typing or type hints, they also will help you form correct requests and reduce development time.
* [Node](/docs/integrations/mux-node-sdk)
* [Python](/docs/integrations/mux-python-sdk)
* [PHP](/docs/integrations/mux-php-sdk)
* [Ruby](/docs/integrations/mux-ruby-sdk)
* [Elixir](/docs/integrations/mux-elixir-sdk)
* [Java](/docs/integrations/mux-java-sdk)
* [C# and other .NET languages](/docs/integrations/mux-csharp-sdk)
# Make API requests with Postman
In this guide you will learn how to fork, set up, and work with Mux's API collection using Postman's API interface.
## Fork the collection
We recommend [Postman](https://postman.com) as a way to easily explore and interact with our API.
Similar to forking a repository on GitHub, forking a collection on Postman allows you to create a new instance of the collection.
Here, you can send requests, collaborate, and submit changes to the original collection.
Without forking the collection, the collection will be **read-only** and you will not be able to make requests unless you're a member of the workspace — even if the collection is public.
If you're already a Postman user, you can fork our [officially supported Postman collection](https://www.postman.com/muxinc/workspace/mux-apis/overview?utm_campaign=postman-collab\&utm_medium=guide\&utm_source=mux) and add it to your workspace by clicking the button below.
You can then stay up to date with future changes to our API specification by pulling changes. More on that in the sections below.
[](https://god.gw.postman.com/run-collection/18282356-97f1767e-f35a-4fca-b1c5-bf612e6f8e76?action=collection%2Ffork\&collection-url=entityId%3D18282356-97f1767e-f35a-4fca-b1c5-bf612e6f8e76%26entityType%3Dcollection%26workspaceId%3D2bcc854d-f831-4c9f-ac0a-3b4382f3a5cd)
## Basic authentication
| Term | Description |
| :----------- | :--------------------------------------------------------- |
| Token ID | access token ID, the "username" in basic auth |
| Token secret | access token secret key, the "password" in basic auth |
## Set up credentials
Once you've created your access tokens via your [Mux account](https://dashboard.mux.com/signup?type=video?utm_campaign=postman-collab\&utm_medium=guide\&utm_source=mux), you can input them into their respective fields under authorization.
## Environment variables
You can use [environment variables](https://learning.postman.com/docs/sending-requests/variables/?utm_campaign=mux-collab\&utm_medium=site\&utm_source=mux) to store and reuse values — like your credentials —
across requests and collections. Variables can either be scoped to the environment or globally, available to all collections within a workspace.
To create environment variables, click the eye icon on the right-hand side of the collection and choose the scope you want your credentials to apply to.
Next, add your credentials and set the type to **secret**. This will hide values on-screen. Once you've finished setting up your environment variables,
you can go back to basic authentication and use the variables instead of the values directly. To do this, use `{{variable_name}}` in the form field.
## Sample request body and responses
Even with extensive documentation, it can be hard to navigate an API for the first time. To help you make requests and understand their responses, we use Postman's
[examples feature](https://learning.postman.com/docs/sending-requests/examples/?utm_campaign=mux-collab\&utm_medium=site\&utm_source=mux) for all Mux Video and Mux Data endpoints.
You can view an endpoint's sample request body by clicking the endpoint on the left-hand API menu and then clicking **body** in the main section of the interface.
You can view an endpoint's sample request response by clicking the right-facing carat on the endpoint. A new item will appear in the collection with the icon **e.g.**.
## Stay up to date with the main collection
Similar to a forked repository on GitHub, your Postman fork will only stay up to date with the origin collection if you periodically [pull changes](https://learning.postman.com/docs/collaborating-in-postman/version-control/#pulling-updates)
to keep your fork in sync.
You can pull changes by clicking the three dots next to the name of your fork. This will open a sub-menu. Click on **merge changes** near the bottom of the menu.
If your fork is not in sync with the origin collection, there will be a yellow banner that states, "The destination has been modified since you last updated the fork. We’d recommend pulling changes." Click **pull changes** on the right.
You will then see a diff where source is the origin and destination is your fork.
Sometimes there will be merge conflicts. If you encounter them, you can choose whether you keep the source or destination version of a change.
Once everything looks good, click the orange button labeled **pull changes**.
# Listen for webhooks
Learn how to listen for webhooks from Mux.
Mux uses [webhooks](https://webhooks.fyi) to let your application know when things happen asynchronously, outside of an API request cycle. For example, you may want to update something on your end when an asset transitions its status from `processing` to `ready`, or when a live stream starts or ends. When these asynchronous events happen, we'll make a POST request to the address you give us and you can do whatever you need with it on your end.
After a webhook is configured for an environment, notifications will be sent for all events for that environment.
Note that webhooks are scoped per *environment*. If you have configured webhooks and you are not seeing them show up, double check that the webhook is correctly configured for the environment you are working in.
If Mux doesn't receive a `2xx` response from your system, we will continue to try the message for the next 24 hours (with an increasing delay between attempts).
Mux makes an effort to deliver each message successfully once, but in certain
situations duplicate webhook messages may be sent even if your service
responds with a 2xx response code. Please ensure that your webhook handling
mechanism treats duplicated event delivery appropriately.
# Webhooks vs. polling
Please use webhooks to track asset status rather than polling the Asset API. Webhooks are much more efficient for both you and Mux, and we rate limit GET requests to the `/assets` endpoint, which means polling the `/assets` API doesn't scale.
# Handling webhooks locally
A common gotcha for anyone new to working with webhooks is figuring out how to receive them when working in a local environment. Since your application runs on a local URL like `http://localhost:3000`, Mux can't reach it directly to deliver webhook events.
The recommended approach is to use the [Mux CLI](/docs/integrations/mux-cli) to listen for events and forward them to your local server.
## Using the Mux CLI
The Mux CLI can connect to Mux's event stream and forward webhook events to your local development server in real-time.
CLI webhook forwarding is for **local development only** and provides **no delivery guarantees**. In production, you must configure a webhook endpoint in the [Mux Dashboard](https://dashboard.mux.com) that points to your server's webhook URL.
### Listen and forward events
```bash
mux webhooks listen --forward-to http://localhost:3000/api/webhooks/mux
```
When using `--forward-to`, the CLI displays a webhook signing secret and signs each forwarded request with a `mux-signature` header. Set `MUX_WEBHOOK_SECRET` in your app's environment to [verify these signatures](/docs/core/verify-webhook-signatures):
```typescript
const event = mux.webhooks.unwrap(body, headers, process.env.MUX_WEBHOOK_SECRET);
```
The signing secret is unique per environment and persisted between sessions, so you only need to configure it once.
### Replay past events
The CLI stores the last 100 events received during `listen` sessions. You can replay them to re-test your webhook handler without creating new resources:
```bash
# List stored events
mux webhooks events list
# Replay a specific event
mux webhooks events replay --forward-to http://localhost:3000/api/webhooks/mux
# Replay all stored events
mux webhooks events replay --all --forward-to http://localhost:3000/api/webhooks/mux
```
### Trigger synthetic events
You can also send synthetic webhook events to your local server for testing, without making any API calls or creating real resources:
```bash
mux webhooks trigger video.asset.ready --forward-to http://localhost:3000/api/webhooks/mux
```
Run `mux webhooks trigger ` to see all supported event types.
For the full list of webhook CLI commands, see the [Mux CLI docs](/docs/integrations/mux-cli#webhook-forwarding).
## Alternative: using ngrok
If you prefer, you can also use a tunneling tool like [ngrok](https://ngrok.com/docs/integrations/webhooks/mux-webhooks) to expose your local server to the internet and receive webhooks directly from Mux.
```bash
ngrok http 3000
```
This gives you a public URL (e.g. `https://abc123.ngrok.io`) that you can configure as a webhook endpoint in the [Mux Dashboard](https://dashboard.mux.com). Your full webhook URL would be something like `https://abc123.ngrok.io/api/webhooks/mux`.
You'll need to create an ngrok account (a free account works for most testing purposes). See [ngrok's Mux integration docs](https://ngrok.com/docs/integrations/webhooks/mux-webhooks) for more details.
# Configuring endpoints
Webhook endpoints are configured in the Mux dashboard under "Settings."
Enter a URL from your application that Mux will call for event notifications.
# Receiving events
Mux will submit a POST request to the configured URL, which your application can treat the same as any other route. Your event handler can do things like update the state of the specified asset in your database, or trigger other work.
Note that a single request attempt will timeout after 5 seconds, after which the attempt is considered failed and will be reattempted. If you expect this will be a problem in your workflow, consider doing the work in an asynchronous task so you can respond to the event immediately.
For more details on the Webhook event object definition, see [the example response](#example-response).
# Example response
```json
{
"type": "video.asset.ready",
"object": {
"type": "asset",
"id": "0201p02fGKPE7MrbC269XRD7LpcHhrmbu0002"
},
"id": "3a56ac3d-33da-4366-855b-f592d898409d",
"environment": {
"name": "Demo pages",
"id": "j0863n"
},
"data": {
"tracks": [
{
"type": "video",
"max_width": 1280,
"max_height": 544,
"max_frame_rate": 23.976,
"id": "0201p02fGKPE7MrbC269XRD7LpcHhrmbu0002",
"duration": 153.361542
},
{
"type": "audio",
"max_channels": 2,
"max_channel_layout": "stereo",
"id": "FzB95vBizv02bYNqO5QVzNWRrVo5SnQju",
"duration": 153.361497
}
],
"status": "ready",
"max_stored_resolution": "SD",
"max_stored_frame_rate": 23.976,
"id": "0201p02fGKPE7MrbC269XRD7LpcHhrmbu0002",
"duration": 153.361542,
"created_at": "2018-02-15T01:04:45.000Z",
"aspect_ratio": "40:17"
},
"created_at": "2018-02-15T01:04:45.000Z",
"accessor_source": null,
"accessor": null,
"request_id": null
}
```
# Types of Events
## Asset Events
| Event | Description |
|-------|-------------|
| `video.asset.created` | Asset has been created |
| `video.asset.ready` | Asset is ready for playback. You can now use the asset's `playback_id` to successfully start streaming this asset. |
| `video.asset.errored` | Asset has encountered an error. Use this to notify your server about assets with errors. Asset errors can happen for a number of reasons, most commonly an input URL that Mux is unable to download or a file that is not a valid video file. |
| `video.asset.updated` | Asset has been updated. Use this to make sure your server is notified about changes to assets. |
| `video.asset.deleted` | Asset has been deleted. Use this so that your server knows when an asset has been deleted, at which point it will no longer be playable. |
| `video.asset.live_stream_completed` | The live stream for this asset has completed. Every time a live stream starts and ends a new asset gets created and this event fires. |
| `video.asset.static_rendition.created` | A new static rendition for this asset has been created. Static renditions are streamable mp4 files that are most commonly used for allowing users to download files for offline viewing. |
| `video.asset.static_rendition.ready` | A static rendition for this asset is ready. Static renditions are streamable mp4 files that are most commonly used for allowing users to download files for offline viewing. |
| `video.asset.static_rendition.skipped` | A static rendition for this asset was skipped, due to the source not being suitable for the requested static rendition. Static renditions are streamable mp4 files that are most commonly used for allowing users to download files for offline viewing. |
| `video.asset.static_rendition.deleted` | A static rendition for this asset was deleted. The static renditions (mp4 files) for this asset will no longer be available. |
| `video.asset.static_rendition.errored` | A static rendition for this asset errored. This indicates that there was some error when creating a static rendition (mp4s) of your asset. This should be rare and if you see it unexpectedly please open a support ticket. |
| `video.asset.master.ready` | Master access for this asset is ready. Master access is used when downloading an asset for purposes of editing or post-production work. The master access file is not intended to be streamed or downloaded by end-users. |
| `video.asset.master.preparing` | Master access for this asset is being prepared. After requesting master access you will get this webhook while it is being prepared. |
| `video.asset.master.deleted` | Master access for this asset has been deleted. Master access for this asset has been removed. You will no longer be able to download the master file. If you want it again you should re-request it. |
| `video.asset.master.errored` | Master access for this asset has encountered an error. This indicates that there was some error when creating master access for this asset. This should be rare and if you see it unexpectedly please open a support ticket. |
| `video.asset.track.created` | A new track for this asset has been created, for example a subtitle text track. |
| `video.asset.track.ready` | A track for this asset is ready. In the example of a subtitle text track the text track will now be delivered with your HLS stream. |
| `video.asset.track.errored` | A track for this asset has encountered an error. There was some error preparing this track. Most commonly this could be a text track file that Mux was unable to download for processing. |
| `video.asset.track.deleted` | A track for this asset has been deleted. |
| `video.asset.warning` | This event fires when Mux has encountered a non-fatal issue with the recorded asset of the live stream. At this time, the event is only fired when Mux is unable to download a slate image from the URL set as `reconnect_slate_url` parameter value. More details on this event is available [here](/docs/guides/handle-live-stream-disconnects#reconnect-window-and-slates). |
## Upload Events
| Event | Description |
|-------|-------------|
| `video.upload.asset_created` | An asset has been created from this upload. This is useful to know what a user of your application has finished uploading a file using the URL created by a [Direct Upload](/docs/guides/upload-files-directly). |
| `video.upload.cancelled` | Upload has been canceled. This event fires after hitting the cancel direct upload API. |
| `video.upload.created` | Upload has been created. This event fires after creating a direct upload. |
| `video.upload.errored` | Upload has encountered an error. This event fires when the asset created by the direct upload fails. Most commonly this happens when an end-user uploads a non-video file. |
## Live Stream Events
| Event | Description |
|-------|-------------|
| `video.live_stream.created` | A new live stream has been created. Broadcasters with a `stream_key` can start sending encoder feed to this live stream. |
| `video.live_stream.connected` | An encoder has successfully connected to this live stream. |
| `video.live_stream.recording` | Recording on this live stream has started. Mux has successfully processed the first frames from the encoder. If you show a *red dot* icon in your UI, this would be a good time to show it. |
| `video.live_stream.active` | This live stream is now "active". The live streams `playback_id` OR the `playback_id` associated with this live stream's asset can be used right now to created HLS URLs (`https://stream.mux.com/{PLAYBACK_ID}.m3u8` and start streaming in your player. Note that before the live stream is `"active"`, trying to stream the HLS URL will result in HTTP `412` errors. |
| `video.live_stream.disconnected` | An encoder has disconnected from this live stream. Note that while disconnected the live stream is still `status: "active"`. |
| `video.live_stream.idle` | The `reconnect_window` for this live stream has elapsed. The live stream `status` will now transition to `"idle"`. |
| `video.live_stream.updated` | This live stream has been updated. For example, after resetting the live stream's stream key. |
| `video.live_stream.enabled` | This live stream has been enabled. This event fires after enable live stream API. |
| `video.live_stream.disabled` | This live stream has been disabled. This event fires after disable live stream API. Disabled live streams will no longer accept new RTMP connections. |
| `video.live_stream.deleted` | This live stream has been deleted. This event fires after delete live stream API API. |
| `video.live_stream.warning` | This live stream event fires when Mux has encountered a non-fatal issue. There is no disruption to the live stream ingest and playback. At this time, the event is only fired when Mux is unable to download an image from the URL set as `reconnect_slate_url` parameter value. More details on this event is available [here](/docs/guides/handle-live-stream-disconnects#reconnect-window-and-slates). |
## Simulcast Target Events
These simulcast target events are useful when creating a UI that shows your users the status of their configured 3rd party endpoints. These events are handy when you want to build a UI that shows the state of each simulcast target and keep track of the state changes as they happen.
| Event | Description |
|-------|-------------|
| `video.live_stream.simulcast_target.created` | A new simulcast target has been created for this live stream. |
| `video.live_stream.simulcast_target.idle` | When the parent live stream is `"disconnected"`, all simulcast targets will have be `"idle"`. |
| `video.live_stream.simulcast_target.starting` | When the parent live stream fires `"connected"` then the simulcast targets transition to `"starting"`. |
| `video.live_stream.simulcast_target.broadcasting` | This fires when Mux has successfully connected to the simulcast target and has begun pushing content to that third party. |
| `video.live_stream.simulcast_target.errored` | This fires when Mux has encountered an error either while attempting to connect to the third party streaming service or while broadcasting. Mux will try to re-establish the connection and if it does successfully the simulcast target will transition back to `"broadcasting"`. |
| `video.live_stream.simulcast_target.updated` | This simulcast target has been updated. |
| `video.live_stream.simulcast_target.deleted` | This simulcast target has been deleted. |
# Webhook specification
A machine-readable specification of all Mux webhook events is available at [`https://www.mux.com/webhook-spec.json`](https://www.mux.com/webhook-spec.json). You can use this to generate types, validate payloads, or integrate with any tooling that supports OpenAPI-style schemas.
# Verify webhook signatures
You have the option to verify webhook requests that Mux sends to your endpoints. Mux will include a signature in the request's header. You can use this signature in your code to make sure the request was sent by Mux and not a third party.
## Obtain your signing secret
Before you get started, you will need your signing secret for your webhook. You can find that where you configure webhooks on the [webhooks settings page](https://dashboard.mux.com/settings/webhooks). Please note that the signing secret is different for each webhook endpoint that we notify.
Webhooks contain a header called `mux-signature` with the timestamp and a signature. The timestamp is prefixed by `t=` and the signature is prefixed by a scheme. Schemes start with `v`, followed by an integer. Currently, the only valid signature scheme is `v1`. Mux generates signatures using [HMAC](https://en.wikipedia.org/wiki/HMAC) with [SHA-256](https://en.wikipedia.org/wiki/SHA-2).
```text
Mux-Signature: t=1565220904,v1=20c75c1180c701ee8a796e81507cfd5c932fc17cf63a4a55566fd38da3a2d3d2`
```
## How to verify webhook signatures
### Step 1: Extract the timestamp and signature
Split the header at the `,` character and get the values for `t` (timestamp) and `v1` (the signature)
### Step 2: Prepare the `signed_payload` string
You will need:
* the timestamp from Step 1 as a string (for example: "1565220904")
* the dot character `.`
* the raw request body (this will be JSON in a string format)
### Step 3: Determine the expected signature
Use the 3 components from Step 2 to compute an HMAC with the SHA256 hash function. Depending on the language that you are using this will look something like the following:
```js
secret = 'my secret' // your signing secret
payload = timestamp + "." + request_body
expected_signature = createHmacSha256(payload, secret)
```
### Step 4: Compare signature
Compare the signature in the header to the expected signature. If the signature matches, compute the difference between the current timestamp and the received timestamp, then check to make sure that the timestamp is within our tolerance. By default, our SDKs allow a tolerance of 5 minutes.
## Examples
Our official SDKs for [Node](https://github.com/muxinc/mux-node-sdk) and [Elixir](https://github.com/muxinc/mux-elixir) contain helper methods for verifying Mux webhooks. If you're using one of these languages it's best to use our available helper methods. Note that the helper methods use the raw request body instead of a payload including the timestamp.
```elixir
# check the mux-elixr docs for details and a full example using Phoenix
# https://github.com/muxinc/mux-elixir#verifying-webhook-signatures-in-phoenix
Mux.Webhooks.verify_header(raw_body, signature_header, secret)
```
```go
func generateHmacSignature(webhookSecret, payload string) string {
h := hmac.New(sha256.New, []byte(webhookSecret))
h.Write([]byte(payload))
return hex.EncodeToString(h.Sum(nil))
}
func IsValidMuxSignature(req *http.Request, body []byte) error {
muxSignature := req.Header.Get("Mux-Signature")
if muxSignature == "" {
return errors.New("no Mux-Signature in request header")
}
muxSignatureArr := strings.Split(muxSignature, ",")
if len(muxSignatureArr) != 2 {
return errors.New(fmt.Sprintf("Mux-Signature in request header should be 2 values long: %s", muxSignatureArr))
}
timestampArr := strings.Split(muxSignatureArr[0], "=")
v1SignatureArr := strings.Split(muxSignatureArr[1], "=")
if len(timestampArr) != 2 || len(v1SignatureArr) != 2 {
return errors.New(fmt.Sprintf("missing timestamp: %s or missing v1Signature: %s", timestampArr, v1SignatureArr))
}
timestamp := timestampArr[1]
v1Signature := v1SignatureArr[1]
webhookSecret := "" //insert secret here or load from config file.
payload := fmt.Sprintf("%s.%s", timestamp, string(body))
sha := generateHmacSignature(webhookSecret, payload)
if sha != v1Signature {
return errors.New("not a valid mux webhook signature")
}
fmt.Println("timestamp sha:", sha)
fmt.Println("v1Signature:", v1Signature)
return nil
}
```
```laravel
/**
* Verify the signature (laravel)
*
* @param Request $request
* @return boolean
*/
protected function verifySignature(Request $request)
{
// Get the signature from the request header
$muxSig = $request->header('Mux-Signature');
if(empty($muxSig)) {
return false;
}
// Split the signature based on ','.
// Format is 't=[timestamp],v1=[hash]'
$muxSigArray = explode(',', $muxSig);
if(empty($muxSigArray) || empty($muxSigArray[0]) || empty($muxSigArray[1])) {
return false;
}
// Strip the first occurence of 't=' and 'v1=' from both strings
$muxTimestamp = Str::replaceFirst('t=', '', $muxSigArray[0]);
$muxHash = Str::replaceFirst('v1=', '', $muxSigArray[1]);
// Create a payload of the timestamp from the Mux signature and the request body with a '.' in-between
$payload = $muxTimestamp . "." . $request->getContent();
// Build a HMAC hash using SHA256 algo, using our webhook secret
$ourSignature = hash_hmac('sha256', $payload, config('mux.webhook_secret'));
// `hash_equals` performs a timing-safe crypto comparison
return hash_equals($ourSignature, $muxHash);
}
```
```node
import Mux from '@mux/mux-node';
// check the mux-node-sdk docs for details
// https://github.com/muxinc/mux-node-sdk/blob/master/api.md#webhooks
const mux = new Mux();
mux.webhooks.verifySignature(body, headers, secret);
```
# Content Security Policy for Mux
Learn how to configure Content Security Policy (CSP) to work with Mux Video and Data services.
## Understanding CSP with Mux
Content Security Policy (CSP) is a security feature that helps protect your web application from cross-site scripting (XSS) attacks and other code injection attacks. CSP works by restricting the resources (such as scripts, stylesheets, images, and network connections) that a web page can load.
When integrating Mux Video and Mux Data into your application, you'll need to configure your CSP to allow connections to Mux services. This guide will help you set up the appropriate CSP directives to ensure your Mux integration works securely.
If you're new to Content Security Policy, we recommend reading [Google's CSP guide](https://developers.google.com/web/fundamentals/security/csp) for a comprehensive introduction to CSP concepts and implementation.
## Basic CSP configuration
For most applications, the simplest approach is to use a basic CSP that allows all Mux services. This configuration ensures compatibility with all current and future Mux features:
```
Content-Security-Policy: default-src 'self' *.mux.com *.litix.io storage.googleapis.com
```
This CSP directive allows your application to:
* Load resources from your own domain (`'self'`)
* Connect to all Mux Video services (`*.mux.com`)
* Connect to all Mux Data services (`*.litix.io`)
* Connect to Google Cloud Storage (`storage.googleapis.com`) -- this is needed for [Direct Uploads](/docs/guides/upload-files-directly)
The wildcard approach for `mux.com` and `litix.io` is recommended because Mux utilizes multiple CDNs and subdomains to provide optimal performance globally. These hostnames may change without notice as we optimize our infrastructure.
## Granular CSP configuration
If your security requirements call for a more restrictive CSP, you can use specific directives instead of the broad `default-src` approach. Here's a granular configuration that covers all Mux functionality:
```
Content-Security-Policy:
connect-src 'self' https://*.mux.com https://*.litix.io https://storage.googleapis.com;
media-src 'self' blob: https://*.mux.com;
img-src 'self' https://image.mux.com https://*.litix.io;
script-src 'self' https://src.litix.io;
worker-src 'self' blob:
```
The above configuration must be merged with your existing CSP directives. Each directive should combine values from both your current policy and the Mux requirements.
## Upload and media handling
If your application uploads media files to Mux via [Direct Uploads](/docs/guides/upload-files-directly), you'll need additional CSP directives to handle binary data and file uploads:
```
Content-Security-Policy:
connect-src 'self' https://*.mux.com https://*.litix.io https://storage.googleapis.com;
media-src 'self' blob: https://*.mux.com;
img-src 'self' https://image.mux.com https://*.litix.io;
script-src 'self' https://src.litix.io;
worker-src 'self' blob:;
form-action 'self' https://*.mux.com https://storage.googleapis.com
```
The key additions for upload functionality are:
| Directive | Purpose |
| :-------- | :------ |
| `https://storage.googleapis.com` in `connect-src` | Allows uploads to Google Cloud Storage endpoints used by Mux |
| `form-action` directive | Permits form submissions and PUT/POST requests to upload endpoints |
| `blob:` in `media-src` and `worker-src` | Enables handling of binary file data during upload processing |
## Product-specific requirements
Different Mux features have specific CSP requirements. Here's what you need for each:
### Mux Video Playback
For video playback functionality, you **must** include:
```
connect-src https://*.mux.com;
media-src blob: https://*.mux.com;
worker-src blob:
```
This is required because:
* HLS manifests and video segments are delivered via `https://stream.mux.com` and other `*.mux.com` subdomains
* Video players use web workers and blob URLs for optimal performance
* Mux uses multiple CDNs with different hostnames for global performance
### Video Thumbnails and Storyboards
If you're displaying video thumbnails or timeline hover previews, include:
```
img-src https://image.mux.com;
connect-src https://image.mux.com
```
The `connect-src` directive is needed for dynamic thumbnail loading in timeline hover previews, while `img-src` covers standard image embedding.
### Mux Data Integration
For Mux Data analytics, you **must** allow:
```
connect-src https://*.litix.io;
img-src https://*.litix.io
```
This covers:
* Data collection endpoints across multiple subdomains
* Fallback beacon loading through image tags
* Various monitoring and analytics endpoints
For tighter security, you can replace `https://*.litix.io` with `https://img.litix.io` and `https://.litix.io` where `` is your Mux environment key. However, the wildcard approach is recommended for maximum compatibility.
### Hosted Mux Data Integrations
If you're loading pre-built Mux Data integrations from our hosted domain (rather than installing via NPM), add:
```
script-src https://src.litix.io
```
This is not required if you bundle the Mux Data SDK directly into your application code.
### Complete Example
Here's a complete CSP that supports all Mux features including uploads:
```
Content-Security-Policy:
default-src 'self';
connect-src 'self' https://*.mux.com https://*.litix.io https://storage.googleapis.com;
media-src 'self' blob: https://*.mux.com;
img-src 'self' https://image.mux.com https://*.litix.io;
script-src 'self' https://src.litix.io;
worker-src 'self' blob:;
form-action 'self' https://*.mux.com https://storage.googleapis.com
```
After implementing your CSP, test all Mux functionality in your application including video playback, uploads, thumbnails, and analytics to ensure everything works as expected.
# Mux Uploader for web
Mux Uploader is a drop in component for uploading videos to Mux from your web application
**Mux Uploader** is a drop-in web component that makes it easy to upload video files to Mux.
This component allows you to build a fully-functional, customizable video upload UI in your application using a single line of code. Mux Uploader supports:
* Manual file selection
* Drag and drop for files
* Optional pausing and resuming of uploads
* Automatic offline/online detection with upload resumes
* And more!
Mux Uploader can be used as either a web component (`` from `@mux/mux-uploader`), or a React component (`` from `@mux/mux-uploader-react`).
## Quick start
Here are some examples of Mux Uploader in action.
### Mux Uploader HTML element
Install with either npm, yarn or load Mux Uploader from the hosted script.
#### NPM
```shell
npm install @mux/mux-uploader@latest
```
#### Yarn
```shell
yarn add @mux/mux-uploader@latest
```
#### Hosted
```html
```
#### Example HTML element implementation
```html
```
### Mux Uploader React component
You will need to select one of the package options below. Both examples will automatically update the uploader. You can always anchor the package to a specific version if needed.
#### NPM
```shell
npm install @mux/mux-uploader-react@latest
```
#### Yarn
```shell
yarn add @mux/mux-uploader-react@latest
```
#### Example React Usage
```jsx
import MuxUploader from "@mux/mux-uploader-react";
export default function App() {
return (
);
}
```
## Upload a video
Mux Uploader allows you to use upload URLs provided by Mux's Direct Uploads in your web application.
It takes care of rendering a file selector, uploading your video file, displaying progress updates to the user, handling retries, and more.
This does mean that you'll need to provide a new upload URL whenever a user will be uploading a new video file in your application. You provide that URL value via the `endpoint` attribute or property. It looks like this:
### HTML example
Sandpack interactive code example configuration JSON.stringified:
```json
{
"customSetup": {
"dependencies": {
"@mux/mux-uploader": "latest"
}
},
"files": {
"/index.html": {
"code": "\n",
"active": true
},
"/index.js": {
"code": "import '@mux/mux-uploader/dist/mux-uploader.js'",
"hidden": true
}
}
}
```
The `endpoint` indicates the direct upload URL that will receive the video file you're uploading.
You can generate a signed direct upload URL by making a server-side API call to Mux's Create Direct Upload endpoint,
or you can use `curl` based on the example from the link if you just want to test it out.
In a successful API response, you will receive a unique signed upload URL that can then be passed along to your client application and set as the `endpoint` property on a `mux-uploader` element. The URL for a Direct Upload looks like `"https://storage.googleapis.com/video..."`.
In the following examples, you will replace the value of the `endpoint` property with your unique direct upload URL.
### React example
Sandpack interactive code example configuration JSON.stringified:
```json
{
"customSetup": {
"dependencies": {
"@mux/mux-uploader-react": "latest"
}
},
"files": {
"/App.js": {
"code": "import MuxUploader from \"@mux/mux-uploader-react\";\n\nexport default function App() {\n return (\n \n );\n}\n",
"active": true
},
"/src/index.js": {
"code": "",
"hidden": true
}
},
"template": "react"
}
```
## Overview of the upload process
Video uploads and processing take time. Processing time can vary depending on the file size and type of video that you upload.
Mux uses [webhooks ](/docs/core/listen-for-webhooks)to keep your application informed about what's happening with your uploaded video — from when the upload completes to when the video is ready to be played.
To minimize processing time, consider following [Mux's guide for handling standard video input](/docs/guides/minimize-processing-time).
The overall flow generally looks like this:
### 1. Set up webhooks
* Set up a public webhook endpoint in your application to receive events from Mux
* Configure the webhook in your Mux dashboard to send events to this endpoint
### 2. Upload the video
* Create a direct upload URL using the Mux API
* Save the upload ID to your database
* Pass the URL to the `endpoint` property on the Mux Uploader component
### 3. Wait for video to be ready
* When the upload completes, show a "processing" indicator to the user.
* Poll your database to check if the video is ready for playback.
### 4. Handle webhook events
Listen for specific webhook events, particularly:
* `video.upload.asset_created` which indicates that the upload has completed and an asset has been created
* `video.asset.ready` which indicates that the video has been processed and is ready for playback
The `video.upload.asset_created` event contains the `asset_id` in the event payload.
The `video.asset.ready` event contains the `playback_id` in the event payload.
### 5. Store the information in your database
Save the `asset_id` and `playback_id` to your database, associating them with the user or relevant entity in your application.
Here's an example of how you might structure your database table schema:
| videos | | |
|--------------------------|------------------------|------------|
| id | uuid (primary key) | |
| user\_id | uuid (foreign key) | References users.id |
| upload\_id | string | From initial upload |
| asset\_id | string | From Mux webhook |
| playback\_id | string | From Mux webhook |
| title | string | Optional metadata |
| status | enum | e.g. `preparing`, `ready` |
| created\_at | timestamp | |
| updated\_at | timestamp | |
### 6. Use the IDs
While Mux generates several IDs during the upload and processing flow, there are two key IDs you'll primarily work with:
1. The `asset_id`: This is used when you need to manage your video through the Mux API (like deleting the video or checking its status)
2. The `playback_id`: This is what you'll use to actually play your video, either by:
* Adding it to Mux Player
* Creating a URL where your video can be played
Note that this process happens asynchronously, so your application should be designed to handle the delay between the initial upload and when the video becomes available for playback.
For more detailed implementations, you can refer to the examples provided in the Mux documentation for various frameworks:
* [Next.js](/docs/frameworks/next-js)
* [SvelteKit](/docs/frameworks/sveltekit)
* [Astro](/docs/frameworks/astro)
* [Remix](/docs/frameworks/remix-js)
## Fetching the upload URL async
At the time you render the ``, you may not have the direct upload URL yet. Instead, you might want to retrieve it async from your server after a user selects a file. You can do that by setting the `endpoint` property value to a custom function instead of a URL.
```html
```
This is even easier using React props:
```jsx
import MuxUploader from "@mux/mux-uploader-react";
export default function App() {
return (
{
return fetch("/your-server/api/create-upload")
.then(res => res.text());
}}
/>
);
}
```
## Customizing the UI
As you can see in the examples above, Mux Uploader provides a fairly feature rich and reasonably styled (albeit basic) UI by default.
It will automatically update based on different stages or states of uploading, like showing a UI for file selection before a video has been picked,
showing progress as the file is uploaded, showing when the file upload has completed, and showing error state with the option to retry if something
goes wrong with the upload.
In addition, Mux Uploader provides many ways to customize this look and feel, including:
* attributes / properties like `no-drop` or `pausable` to enable/disable UI components
* intuitive styling with CSS, just like any other HTML element.
* state transition attributes like `upload-in-progress` or `upload-error` for responsive styling
* attribute / property based data customization for things like `dynamic-chunk-size` or `max-file-size`
* overridable and composable components like `` or `` for full flexibility of UI
# Core functionality of Mux Uploader
In this guide, see the features and functionality that Mux Uploader gives you out of the box.
## Mux Video integration
Mux Uploader is built for working with Mux's [Direct Uploads](/docs/guides/upload-files-directly) API and workflow. Add your upload
URL as Mux Uploader's [`endpoint`](/docs/guides/mux-uploader#upload-a-video) to use it.
Mux Uploader uses [UpChunk](https://github.com/muxinc/upchunk) under the hood to handle large files by splitting them into small chunks before uploading them.
## Controls and UI
Mux Uploader provides a feature-rich, dynamic UI that changes based on the current state of your media upload.
These can be broken down into:
| State | Attribute | Description |
| ----- | --------- | ----------- |
| Initial | (none) | State before a media file has been selected for upload |
| In Progress | `upload-in-progress` | State while media chunks are being uploaded |
| Completed | `upload-complete` | State after the media has successfully finished uploading all chunks |
| Error | `upload-error` | State whenever an error occurs that results in a failure to fully upload the media |
## Initial State
The initial state by default will show both a drag and drop region and a file select button to select your file for upload.
By default, it looks like this:
## In Progress State
Under normal conditions, the in progress state will indicate the ongoing uploading progress as both a numeric percentage and
a progress bar. It will look something like this:
### Pausing
In addition, you can [opt into pausing](/docs/guides/uploader-web-customize-look-and-feel#enable-pausing), in which case the UI
will look like one of these, depending on if you are unpaused, pausing (after the current chunk finishes uploading), or paused.
### Offline
Finally, if you unfortunately end up loosing internet connection while uploading is in progress, you'll see this:
## Completed State
Once uploading has completed, Mux Uploader will present the following status:
## Error State
And in the unfortunate case where you encounter an error, by default you'll see the error message and a retry button:
If you want to explore different ways to customize the UI for these different states,
check out our documentation on [customizing Mux Uploader's look and feel](/docs/guides/uploader-web-customize-look-and-feel).
## Error handling
Mux Uploader will monitor for unrecoverable errors and surface them via the UI, giving the
user the opportunity to retry the upload. Mux Uploader monitors both HTTP-status based errors
(e.g. 4xx, 5xx statuses) and file processing errors like exceeding maximum file size limits. See our [optional configuration options](#configure-upload-details) below for more ways to work around some of these errors.
In addition, before surfacing an HTTP-based error, Mux Uploader will automatically retry the request 5 times.
You may also listen for these errors via the `uploaderror` event, discussed in the section below.
## Using events
All of Mux Uploader's core UI behaviors and functionality are driven by specific events. These fall into two
categories:
1. user-driven update events (e.g. notifying Mux Uploader which file to upload or to retry uploading after an error)
2. state-driven informational events (e.g. notifying subcomponents or anyone else listening about the upload progress or that an error occurred)
For example, you can listen for the `progress` event to receive details on how far along your file upload is.
```js
const muxUploader = document.querySelector('mux-uploader');
muxUploader.addEventListener('progress', function (e) {
console.log(`My upload is ${e.detail}% complete!`)
});
```
When the upload is complete, you'll see 100% on the progress bar and the `success` event will fire.
If an error occurs during the upload, an `uploaderror` event will fire.
### Example HTML Usage
```html
```
### Example React Usage
```jsx
import MuxUploader from "@mux/mux-uploader-react";
export default function App() {
return (
{
// Handle upload success
}}
onUploadError={() => {
// Handle upload error
}}
/>
);
}
```
## Configure Upload Details
In addition to various UI customization and behaviors, Mux Uploader exposes the following attributes / properties for configuring details
about the file upload itself:
| Attribute / Property | Description |
| --- | --- |
| `max-file-size` / `maxFileSize` | The largest size, in kB, allowed for upload |
| `chunk-size` / `chunkSize` | The size of each upload chunk, in kB. Useful for advanced optimization based on known network conditions or file details. |
| `dynamic-chunk-size` / `dynamicChunkSize` | A boolean that tells Mux Uploader to automatically adapt its chunk size larger or smaller based on network conditions. |
| `use-large-file-workaround` / `useLargeFileWorkaround` | A boolean that enables a less memory efficient way of loading and chunking files for environments that don't reliably handle [`ReadableStream` for large files](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API/Using_readable_streams). This can occur on e.g. Safari browsers with files >= 4GB. **NOTE:** This fallback will only be used if and when attempts to use `ReadableStream` fails. |
## Full API reference
Any features or settings not mentioned above can be found in our [full API reference](https://github.com/muxinc/elements/blob/main/packages/mux-uploader/REFERENCE.md)
covering all of the available events, attributes, properties, slots, CSS parts, and CSS variables available on Mux Uploader and all of its subcomponents.
# Integrate Mux Uploader into your web application
In this guide, you will learn about Mux Uploader and how to use it in your web application.
## Install Mux Uploader
Mux Uploader has 2 packages:
* `@mux/mux-uploader`: the web component, compatible with all frontend frameworks
* `@mux/mux-uploader-react`: the React component, for usage in React
Both are built with TypeScript and can be installed either via `npm`, `yarn` or the hosted option on `jsdelivr`.
### NPM
```shell
npm install @mux/mux-uploader@latest #or @mux/mux-uploader-react@latest
```
### Yarn
```shell
yarn add @mux/mux-uploader@latest #or @mux/mux-uploader-react@latest
```
### Hosted
```html
```
## Providing attributes
The only required value to use Mux uploader is [`endpoint`](/docs/guides/mux-uploader#upload-a-video).
## Examples
### HTML element
Sandpack interactive code example configuration JSON.stringified:
```json
{
"customSetup": {
"dependencies": {
"@mux/mux-uploader": "latest"
}
},
"files": {
"/index.html": {
"code": "\n",
"active": true
},
"/index.js": {
"code": "import '@mux/mux-uploader/dist/mux-uploader.js'",
"hidden": true
}
}
}
```
Using in HTML just requires adding the hosted `
```
### Vue
Because Vue supports web components, it doesn't need a separate wrapper component like React. View the Vue example in the [Mux Elements repo](https://github.com/muxinc/elements/tree/main/examples/vue-with-typescript) for a fully functioning example.
```html
```
{/* */}
# Customize the look and feel of Mux Uploader
Learn how to customize the look and feel of Mux Uploader to fit your brand and use case.
## Configure UI features
The basic use case of Mux Uploader includes many UI features which may be enabled or disabled by default.
You can toggle many of these via attributes/properties.
### Enable pausing
For larger video files, you may want to allow your users to pause and resume an upload. You can enable this in the UI using
the `pausable` attribute, property, or React prop.
Because Mux Uploader uploads the file in chunks, it will wait to complete uploading the current chunk before pausing. To indicate this,
the pause button will actually have 3 states:
1. Pause - indicates the upload is not currently paused, but can be by pressing the button.
2. Pausing - indicates that the upload will pause once the current chunk upload finishes. The button will be disabled in this case.
3. Resume - indicates the upload is currently paused, but can be resumed by pressing the button.
Below are examples of what this looks like in the UI.
### Disable Retrying
If for some reason your video upload fails, Mux Uploader will allow a user to retry via the UI. You can disable this using the
`no-retry` attribute or `noRetry` property in the web component, or just `noRetry` prop in React.
Below are examples of what this looks like in the UI.
### Disable Drag & Drop
Mux Uploader makes drag and drop available for your video files by default. You can disable this using the
`no-drop` attribute or `noDrop` property in the web component, or just `noDrop` prop in React.
Below are examples of what this looks like in the UI.
**Note:** There are two likely cases where you may want to disable drag and drop on Mux Uploader:
1. You still want to support drag and drop, but your page or application design needs the drop zone component somewhere different.
Mux Uploader supports this by allowing you to [use its subcomponents directly](/docs/guides/uploader-web-use-subcomponents-directly).
2. You want to use Mux Uploader with all of its features baked in but drag and drop doesn't make sense for your designs. Because
things like the upload progress UI requires more space for its display, you'll probably also want to
[use CSS to customize Mux Uploader](#style-with-css).
### Disable other UI subcomponents or features
Mux Uploader also provides attributes and properties to disable:
* The upload progress UI (`no-progress` / `noProgress` for the web component attribute / property, `noProgress` for the React prop)
* The upload status UI (e.g. when the upload is complete or when an error occurs) (`no-status` / `noStatus` for the web component attribute / property, `noStatus` for the React prop)
Since removing these UI elements might result in a poor user experience, you may want to [use Mux Uploader's subcomponents directly](/docs/guides/uploader-web-use-subcomponents-directly) for a more bespoke design when doing so.
## Override the file selector with slots
Because Mux Uploader is a [web component](https://developer.mozilla.org/en-US/docs/Web/API/Web_components), it lets you provide your
own file select element simply by adding it as a child and using the [named slot](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_templates_and_slots#using_the_element-details_custom_element_with_named_slots)
`slot="file-select"` attribute or property.
This is really handy if, for example, you already have a `.btn` class or similar that styles buttons in your application. For example:
Sandpack interactive code example configuration JSON.stringified:
```json
{
"customSetup": {
"dependencies": {
"@mux/mux-uploader": "latest"
}
},
"files": {
"/index.html": {
"code": "\n\n\n\n \n",
"active": true
},
"/index.js": {
"code": "import '@mux/mux-uploader/dist/mux-uploader.js'",
"hidden": true
}
}
}
```
The same applies to the React version of the component, ``, as it's just a wrapper around the web component:
Sandpack interactive code example configuration JSON.stringified:
```json
{
"customSetup": {
"dependencies": {
"@mux/mux-uploader-react": "latest"
}
},
"files": {
"/App.js": {
"code": "import MuxUploader from \"@mux/mux-uploader-react\";\n\nexport default function App() {\n return (\n \n Pick a file\n \n );\n}\n",
"active": true
},
"/src/index.js": {
"code": "",
"hidden": true
}
},
"template": "react"
}
```
## Style with CSS
The Mux Uploader element, ``, can be styled and positioned with CSS just like you would any other HTML element. For example:
Sandpack interactive code example configuration JSON.stringified:
```json
{
"customSetup": {
"dependencies": {
"@mux/mux-uploader": "latest"
}
},
"files": {
"/index.html": {
"code": "\n\n\n",
"active": true
},
"/index.js": {
"code": "import '@mux/mux-uploader/dist/mux-uploader.js'",
"hidden": true
}
}
}
```
Because Mux Uploader React is a wrapper around the HTML element, the same applies to it as well:
Sandpack interactive code example configuration JSON.stringified:
```json
{
"customSetup": {
"dependencies": {
"@mux/mux-uploader-react": "latest"
}
},
"files": {
"/App.js": {
"code": "import MuxUploader from \"@mux/mux-uploader-react\";\n\nexport default function App() {\n return (\n \n );\n}\n",
"active": true
},
"/src/index.js": {
"code": "",
"hidden": true
}
},
"template": "react"
}
```
* Mux Uploader relies on certain styles for its layout, so take care when overriding them. For example: flexbox is used by default to layout
its subcomponents so it might be best to prefer `display: inline-flex` instead of potentially changing it to `inline` or `inline-block`.
* Because Mux Uploader is a complex component made up of various sub-components, your mileage may vary on simply relying
on CSS to style the component. In these more advanced cases of styling, you may want to explore [using CSS variables](#use-css-variables-for-additional-styling) or
[using the Mux Uploader subcomponents directly](/docs/guides/uploader-web-use-subcomponents-directly).
### Use CSS variables for additional styling
In addition to styling with standard CSS, Mux Uploader exposes some additional styles via [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties).
This allows you to tweak some of the "under the hood" subcomponents' styles simply. These include:
| Name | CSS Property | Default Value | Description |
| ------------------------------- | ------------------ | --------------------------- | ----------------------------------------------- |
| `--overlay-background-color` | `background-color` | `rgba(226, 253, 255, 0.95)` | background color of the drop overlay |
| `--progress-bar-fill-color` | `background` | `#000000` | color for progress bar |
| `--progress-percentage-display` | `display` | `block` | display value for text percentage progress UI |
| `--progress-radial-fill-color` | `stroke` | `black` | stroke color for radial progress (experimental) |
Building off of the prior examples, you can use these just like you would other CSS variables:
Sandpack interactive code example configuration JSON.stringified:
```json
{
"customSetup": {
"dependencies": {
"@mux/mux-uploader": "latest"
}
},
"files": {
"/index.html": {
"code": "\n\n\n",
"active": true
},
"/index.js": {
"code": "import '@mux/mux-uploader/dist/mux-uploader.js'",
"hidden": true
}
}
}
```
And for React:
Sandpack interactive code example configuration JSON.stringified:
```json
{
"customSetup": {
"dependencies": {
"@mux/mux-uploader-react": "latest"
}
},
"files": {
"/App.js": {
"code": "import MuxUploader from \"@mux/mux-uploader-react\";\n\nexport default function App() {\n return (\n \n );\n}\n",
"active": true
},
"/src/index.js": {
"code": "",
"hidden": true
}
},
"template": "react"
}
```
### Use uploader attributes for state-driven styling
Mux Uploader uses read-only properties and attributes to manage and advertise different state changes during the upload process.
These are:
| State | Description |
| --- | --- |
| (none) | Upload has not yet begun |
| `upload-in-progress` | Upload is currently in progress. **NOTE:** This includes while the upload is paused. |
| `upload-complete` | Upload has completed. |
| `upload-error` | An error occurred while attempting to upload. |
These allow you to use [attribute selectors](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors/Attribute_selectors)
if you want state-driven, dynamic styling via CSS.
Here's a basic example of these in action that builds off of the prior examples:
Sandpack interactive code example configuration JSON.stringified:
```json
{
"customSetup": {
"dependencies": {
"@mux/mux-uploader": "latest"
}
},
"files": {
"/index.html": {
"code": "\n\n\n",
"active": true
},
"/index.js": {
"code": "import '@mux/mux-uploader/dist/mux-uploader.js'",
"hidden": true
}
}
}
```
**NOTE:** Because Mux Uploader React is a thin wrapper around the Mux Uploader web component, you can use these exact same CSS selectors
in your React application. Alternatively, some frameworks, like [Tailwind CSS](https://tailwindcss.com/), have built-in support for arbitrary
attribute selectors. For an example of this in use, see the [section below](#using-tailwind-css).
### Styling in React
If you're using React to build your application, there are some common patterns used in React that are less likely to be relevant for
the web component version. Below are a couple of these.
### Using CSS modules
One common pattern for styling in React is to use CSS-in-JS, for example, using CSS modules:
Sandpack interactive code example configuration JSON.stringified:
```json
{
"customSetup": {
"dependencies": {
"@mux/mux-uploader-react": "latest"
}
},
"files": {
"/App.js": {
"code": "import styles from \"./Styles.module.css\";\nimport MuxUploader from \"@mux/mux-uploader-react\";\n\nexport default function App() {\n return (\n \n );\n}\n",
"active": true
},
"/src/index.js": {
"code": "",
"hidden": true
},
"/Styles.module.css": {
"code": ".uploader {\n --overlay-background-color: purple;\n --progress-bar-fill-color: purple;\n --progress-percentage-display: none;\n display: inline-flex;\n width: 350px;\n height: 275px;\n color: white;\n background: hotpink;\n font-family: \"Gill Sans\", sans-serif;\n}\n"
}
},
"template": "react"
}
```
### Using Tailwind CSS
Another common approach to styling React applications is using [Tailwind CSS](https://tailwindcss.com). Here's an example for Mux Uploader
approximating the previous examples, including CSS variables via
[arbitrary properties](https://tailwindcss.com/docs/adding-custom-styles#arbitrary-properties) and attribute selectors via
[arbitrary variants](https://tailwindcss.com/docs/hover-focus-and-other-states#using-arbitrary-variants):
Sandpack interactive code example configuration JSON.stringified:
```json
{
"customSetup": {
"dependencies": {
"@mux/mux-uploader-react": "latest"
}
},
"files": {
"/App.js": {
"code": "import MuxUploader from \"@mux/mux-uploader-react\";\n\n// Declaring the tailwind classes as an array for legibility\nconst stylesList = [\n 'inline-flex',\n 'w-4/5',\n 'h-4/5',\n 'font-sans',\n 'text-white',\n 'bg-pink-400',\n '[--progress-percentage-display:none]',\n '[--overlay-background-color:purple]',\n '[--progress-bar-fill-color:purple]',\n '[&[upload-in-progress]]:bg-orange-500',\n '[&[upload-complete]]:bg-green-500',\n];\n\nconst stylesStr = stylesList.join(' ');\n\nexport default function App() {\n return (\n \n );\n}\n",
"active": true
},
"/src/index.js": {
"code": "",
"hidden": true
}
},
"options": {
"externalResources": [
"https://cdn.tailwindcss.com"
]
},
"template": "react"
}
```
# Compose custom UIs with subcomponents
Learn how to use Mux Uploader's various subcomponents to compose even more bespoke user experiences and designs.
Although Mux Uploader is a single component that's easy to drop into your web application, it's actually built using several subcomponents
"under the hood." If your application design or desired user experience requires more customization, you can use the individual web components that come packaged with Mux Uploader to build out a custom upload UI that meets your needs.
To use this approach, add an `id` attribute to your `` element with a unique value.
You can then associate the `` element with any of the packaged components by adding a `mux-uploader=""` attribute to each component and setting it to the `id` that you gave to the `` element.
Here's a simple example for the web component:
```html
```
Here's one for React:
```jsx
import MuxUploader, { MuxUploaderFileSelect } from "@mux/mux-uploader-react";
export default function App() {
return (
{/* ...then, somewhere else in your app, add a reference back to it */}
);
}
```
Because all of these are web components, you can use CSS to style them or
any of their slotted children (discussed below).
# Subcomponents
## File Select
The file select subcomponent is what tells Mux Uploader to open the file selection browser. The web component is
``, and the React component is ``.
You can further customize it by slotting in your own `\n\n \n",
"active": true
},
"/index.js": {
"code": "import '@mux/mux-uploader/dist/mux-uploader.js';",
"hidden": true
}
}
}
```
## Drop
The drop subcomponent is what implements the [drag and drop API](https://developer.mozilla.org/en-US/docs/Web/API/HTML_Drag_and_Drop_API)
and tells Mux Uploader the relevant details about the file.
The web component is ``, and the React component is ``.
Mux Uploader Drop provides a few slots for customization.
* `heading` - By default this is a `` with the text "Drop a video file here to upload".
* `separator` - By default this is a `` containing the text "or" placed between the heading and any additional children.
* (default) - Any additional children that don't have a specified slot will show up below the two previous slots.
Here's an example that puts all of these together, including CSS:
Sandpack interactive code example configuration JSON.stringified:
```json
{
"customSetup": {
"dependencies": {
"@mux/mux-uploader": "latest"
}
},
"files": {
"/index.html": {
"code": "\n\n\n \n
Drop videoz here plz
\n \n \n
You can also add arbitrary children for designs like the drop zone being the full screen
\n\n\n",
"active": true
},
"/index.js": {
"code": "import '@mux/mux-uploader/dist/mux-uploader.js';",
"hidden": true
}
}
}
```
In addition, Mux Uploader Drop has attributes/properties for optionally showing an overlay whenever a file is
dragged over it. These are on by default in Mux Uploader, and are:
* `overlay` - A boolean attribute / property / React prop for enabling the overlay UI.
* `overlay-text` (`overlayText` property and React prop) - Allows you to provide custom text to show on the overlay.
If you'd like to further customize the overlay with a different background color, you can use the
`--overlay-background-color` CSS variable (which is also available when [using Mux Uploader directly](/docs/guides/uploader-web-customize-look-and-feel#use-css-variables-for-additional-styling))
Here's an example of these in action:
Sandpack interactive code example configuration JSON.stringified:
```json
{
"customSetup": {
"dependencies": {
"@mux/mux-uploader": "latest"
}
},
"files": {
"/index.html": {
"code": "\n\n\n\n \n
Drop videoz here plz
\n \n \n
You can also add arbitrary children for designs like the drop zone being the full screen
\n\n\n",
"active": true
},
"/index.js": {
"code": "import '@mux/mux-uploader/dist/mux-uploader.js';",
"hidden": true
}
}
}
```
### Custom Drop
You can even implement your own drag and drop completely separate from `` and as long as you dispatch a custom `file-ready` with the file in the `detail` property then `` will handle the upload upon receiving the event.
```html
```
## Progress
The progress subcomponent is what visualizes progress of your upload. In fact, it is used twice "under the hood" by the default ``:
once for showing the %, and once for showing the progress bar.
The web component is ``, and the React component is ``.
In addition, Mux Uploader Progress exposes the `type` attribute / property / React prop for choosing the particular kind of visualization you'd prefer. The
available type values are:
* `percentage` (default) - Show as a numeric % in text
* `bar` - Show as a progress bar
* `radial` (***Experimental***) - Show as a radial/circular progress indicator
Each of these types also has CSS variables available for further customization:
`percentage`:
* `--progress-percentage-display` - Applies to the `display` of the underlying percentage element (default: `block`).
`bar`:
* `--progress-bar-height` - Applies to the `height` of the progress bar (default: `4px`).
* `--progress-bar-fill-color` - Applies to the color of the progress bar's progress indication (default: `black`).
`radial`:
* `--progress-radial-fill-color` - Applies to the color of the radial progress indication (default: `black`).
Here's an example of these in action:
Sandpack interactive code example configuration JSON.stringified:
```json
{
"customSetup": {
"dependencies": {
"@mux/mux-uploader": "latest"
}
},
"files": {
"/index.html": {
"code": "\n\n\n \n\n",
"active": true
},
"/index.js": {
"code": "import '@mux/mux-uploader/dist/mux-uploader.js';",
"hidden": true
}
}
}
```
## Status
The status subcomponent is what indicates when the upload is completed, or an error has occurred, or when you're offline.
The web component is ``, and the React component is ``.
Here's an example with a bit of CSS customization, using Mux Uploader's [state attributes](/docs/guides/uploader-web-customize-look-and-feel#use-uploader-attributes-for-state-driven-styling)
on the status component for additional state-driven styling:
Sandpack interactive code example configuration JSON.stringified:
```json
{
"customSetup": {
"dependencies": {
"@mux/mux-uploader": "latest"
}
},
"files": {
"/index.html": {
"code": "\n\n\n",
"active": true
},
"/index.js": {
"code": "import '@mux/mux-uploader/dist/mux-uploader.js';",
"hidden": true
}
}
}
```
## Retry
The retry subcomponent that is displayed when an error has occurred to retry uploading and will notify Mux Uploader to retry when clicked.
The web component is ``, and the React component is ``.
Here's a simple example:
Sandpack interactive code example configuration JSON.stringified:
```json
{
"customSetup": {
"dependencies": {
"@mux/mux-uploader": "latest"
}
},
"files": {
"/index.html": {
"code": "\n\n",
"active": true
},
"/index.js": {
"code": "import '@mux/mux-uploader/dist/mux-uploader.js';",
"hidden": true
}
}
}
```
## Pause
The pause subcomponent that is displayed while an upload is in progress and will notify Mux Uploader to either pause or resume uploading
when clicked, depending on the current uploading state.
The web component is ``, and the React component is ``.
Here's a simple example:
Sandpack interactive code example configuration JSON.stringified:
```json
{
"customSetup": {
"dependencies": {
"@mux/mux-uploader": "latest"
}
},
"files": {
"/index.html": {
"code": "\n\n",
"active": true
},
"/index.js": {
"code": "import '@mux/mux-uploader/dist/mux-uploader.js';",
"hidden": true
}
}
}
```
# Advanced use cases
Here are some more examples of working with the subcomponents directly, using multiple subcomponents together to demonstrate the versatility
and composability of using the various subcomponents together in either React or vanilla HTML.
## React CSS modules
Just like you can do with the "batteries" usage of Mux Uploader, you can use [CSS-in-JS](/docs/guides/uploader-web-customize-look-and-feel#using-css-modules)
to handle styling of your subcomponents in React. Here's an example of how you can style Mux Uploader using CSS modules:
Sandpack interactive code example configuration JSON.stringified:
```json
{
"customSetup": {
"dependencies": {
"@mux/mux-uploader-react": "latest"
}
},
"files": {
"/App.js": {
"code": "import styles from \"./Styles.module.css\";\nimport MuxUploader, { MuxUploaderFileSelect, MuxUploaderProgress } from \"@mux/mux-uploader-react\"; \n\nexport default function App() {\n return (\n
\n
Mux Uploader with CSS Modules
\n \n \n \n \n \n
\n );\n}\n",
"active": true
},
"/src/index.js": {
"code": "",
"hidden": true
},
"/Styles.module.css": {
"code": ".heading {color: #333;}\n.uploader { display: none; }\n.progress { color: orange; }\n.button {\n background: #3a3a9d;\n padding: 1em;\n color: white;\n border-radius: .35em;\n border: 0;\n cursor: pointer;\n}\n "
}
},
"template": "react"
}
```
## React Tailwind CSS
Also like Mux Uploader, you can use [Tailwind CSS](/docs/guides/uploader-web-customize-look-and-feel#using-tailwind-css) for your subcomponent styling. Here's an example in React:
Sandpack interactive code example configuration JSON.stringified:
```json
{
"customSetup": {
"dependencies": {
"@mux/mux-uploader-react": "latest"
}
},
"files": {
"/App.js": {
"code": "import MuxUploader, { MuxUploaderFileSelect, MuxUploaderProgress, MuxUploaderDrop } from \"@mux/mux-uploader-react\"; \n\nexport default function App() {\n return (\n
\n
Mux Uploader with Tailwind example
\n \n\n \n Drop your favorite video\n — or —\n\n \n \n Select from a folder\n \n \n \n\n \n
\n );\n}\n",
"active": true
},
"/src/index.js": {
"code": "",
"hidden": true
}
},
"options": {
"externalResources": [
"https://cdn.tailwindcss.com"
]
},
"template": "react"
}
```
## Uploader Page
In this example, we use the Mux Uploader Drop component as the parent for a full page upload experience, with the various subcomponents as descendants
with their own customization for a more bespoke look and feel:
Sandpack interactive code example configuration JSON.stringified:
```json
{
"customSetup": {
"dependencies": {
"@mux/mux-uploader": "latest"
}
},
"files": {
"/index.html": {
"code": "\n\n\n\n \n \n
Drop your video file anywhere on the page
\n
\n \n \n \n
\n \n \n \n",
"active": true
},
"/index.js": {
"code": "import '@mux/mux-uploader/dist/mux-uploader.js';",
"hidden": true
}
}
}
```
# Use different video quality levels
Learn how to pick an appropriate video quality and control the video quality of assets.
[We recently renamed encoding tiers to video quality levels. Read the blog for more details.](https://www.mux.com/blog/no-one-said-naming-was-easy-encoding-tiers-are-now-video-quality-levels)
## Introducing video quality levels
Mux Video supports encoding content with three different video quality levels. The video quality level informs the quality, cost, and available platform features for the asset.
### Basic
The *basic* video quality level uses a reduced encoding ladder, with a lower target video quality, suitable for simpler video use cases.
There is no charge for video encoding when using basic quality.
### Plus
The *plus* video quality level encodes your video at a consistent high-quality level. Assets encoded with the plus quality use an AI-powered per-title encoding technology that boosts bitrates for high-complexity content, ensuring high-quality video, while reducing bitrates for lower-complexity content to save bandwidth without sacrificing on quality.
The plus quality level incurs a [cost per video minute of encoding](https://mux.com/pricing).
### Premium
The *premium* video quality level uses the same AI-powered per-title encoding technology as plus, but is tuned to optimize for the presentation of premium media content, where the highest video quality is required, including use cases like live sports, or studio movies.
The premium quality level incurs a higher [cost per video minute of encoding, storage, and delivery](https://mux.com/pricing).
## Set a video quality level when creating an asset
The video quality of an asset is controlled by setting the `video_quality` attribute on your create-asset API call, so to create an asset with the `basic` quality level, you should set `"video_quality": "basic"` as shown below.
```json
// POST /video/v1/assets
{
"inputs": [
{
"url": "https://storage.googleapis.com/muxdemofiles/mux.mp4"
}
],
"playback_policies": [
"public"
],
"video_quality": "basic"
}
```
And of course you can also select the `video_quality` within Direct Uploads, too; you just need to set the same `"video_quality": "basic"` field in the `new_asset_settings` of your create-direct-upload API call.
```json
// POST /video/v1/uploads
{
"new_asset_settings": {
"playback_policies": [
"public"
],
"video_quality": "basic"
},
"cors_origin": "*"
}
```
## Set the video quality when creating a live stream
To set the `video_quality` for a live stream, you just need to set the `"video_quality"` field within the `new_asset_settings` configuration of your create-live-stream API call to `"plus"` or `"premium"`, as shown below.
```json
// POST /video/v1/live-streams
{
"playback_policies": [
"public"
],
"new_asset_settings": {
"playback_policies": [
"public"
],
"video_quality": "plus"
}
}
```
All on-demand assets created from the live stream will also inherit the given quality level. Live streams can currently only use the `plus` or `premium` video quality levels.
## Supported features
Assets using different video quality levels have different features or limits available to them. Refer to the below table for more details:
| Feature | Basic | Plus | Premium |
| :-- | :-- | :-- | :-- |
| [JIT encoding](https://www.mux.com/features#just-in-time-encoding) | ✅ | ✅ | ✅ |
| [Multi CDN delivery](https://www.mux.com/blog/multi-cdn-support-in-mux-video-for-improved-performance-and-reliability) | ✅ | ✅ | ✅ |
| [Mux Data included](https://mux.com/data) | ✅ | ✅ | ✅ |
| [Mux Player included](https://mux.com/player) | ✅ | ✅ | ✅ |
| [Thumbnails, Gifs,](/docs/guides/get-images-from-a-video) [Storyboards](/docs/guides/create-timeline-hover-previews) | ✅ | ✅ | ✅ |
| [Watermarking](/docs/guides/add-watermarks-to-your-videos) | ✅ | ✅ | ✅ |
| [Signed playback IDs and playback restrictions](/docs/guides/secure-video-playback) | ✅ | ✅ | ✅ |
| [On-Demand](/docs/core/stream-video-files) | ✅ | ✅ | ✅ |
| [Master Access](/docs/guides/download-for-offline-editing) | ✅ | ✅ | ✅ |
| [Audio-only Assets](https://www.mux.com/blog/have-you-heard-we-support-audio-only-files-too) | ✅ | ✅ | ✅ |
| [Auto-generated captions](/docs/guides/add-autogenerated-captions-and-use-transcripts) | ✅ | ✅ | ✅ |
| [Clipping to a new asset](/docs/guides/create-clips-from-your-videos)| ✅ | ✅ | ✅ |
| [Multi-track audio](/docs/guides/add-alternate-audio-tracks-to-your-videos) | ✅ | ✅ | ✅ |
| [Live Streaming](/docs/guides/start-live-streaming) | ❌ | ✅ | ✅ |
| [Adaptive bitrate ladder](https://www.mux.com/video-glossary/abr-adaptive-bitrate) | Reduced | Standard | Extended |
| [Maximum streaming resolution](/docs/guides/stream-videos-in-4k) | 2160p (4K) | 2160p (4K) | 2160p (4K) |
| [MP4 support](/docs/guides/enable-static-mp4-renditions) \* | ✅ | ✅ | ✅ |
| [DRM](/docs/guides/protect-videos-with-drm) | ❌ | ✅ | ✅ |
## Examples for comparison
| Encoding tier | Content complexity | Playback page |
| :-- | :-- | :-- |
| basic | Simple | [moodeng - basic](https://player.mux.com/elUDQkfDSv43pR8ejgrURIGcNDzx00Jgq) |
| basic | Complex | [waterfall - basic](https://player.mux.com/z00qLVB3NsE1FOE7mCKboHGXQDQIun4sp) |
| plus | Simple | [moodeng - plus](https://player.mux.com/Vl7wZGmm3ztT01VL8UzTv9QEfPleP4kMR) |
| plus | Complex | [waterfall - plus](https://player.mux.com/aTFGdFMLBgdvegF29Orvoj026mpkb8v6Q) |
| premium | Simple | [moodeng - premium](https://player.mux.com/JQ1P00AC3EjGfL7BjI951M006dvL4asVce) |
| premium | Complex | [waterfall - premium](https://player.mux.com/Q8Vk00DqGWTGS40201TtXROm67LNCMlfxed) |
\* MP4 pricing depends on the video quality level of your asset. [Learn more.](/docs/pricing/video#do-you-charge-for-mp4-downloads)
# Stream videos in 4K
Learn how to ingest, store, and deliver your videos in 4K resolutions
## Introduction to 4K
Mux Video supports ingesting, storing, and delivering on-demand video assets in high resolutions up to and including 4K (2160p). At this time, 2K and 4K output is not supported for Mux [Live Streaming](https://www.mux.com/docs/guides/start-live-streaming). Live Streams will accept 2K and 4K input, but the output will be capped to 1080p (and will be billed as 1080p).
Much premium video content is created in 4K, but more recently user-generated content is often in 4K as well, as mobile devices are increasingly capable of producing 4K video.
Mux Video also supports [2K and 2.5K video on-demand video assets](/docs/guides/stream-videos-in-4k#stream-2k-and-25k-content).
## Create a 4K asset
To ingest, store, and deliver an asset in 4K, you'll need to set the new `max_resolution_tier` attribute on your create-asset API call.
```json
// POST /video/v1/assets
{
"inputs": [
{
"url": "https://storage.googleapis.com/muxdemofiles/mux-4k.mp4"
}
],
"playback_policies": [
"public"
],
"video_quality": "basic",
"max_resolution_tier": "2160p"
}
```
This field controls the maximum resolution that we'll encode, store, and deliver your media in. We do not to automatically ingest content at 4K so that you can avoid unexpectedly high ingest bills. If you send us 4K content today and don't set `max_resolution_tier`, nothing changes in your bill.
This also allows you to build applications where some of your content creators are able to upload 4K content while others remain capped at 1080p.
And of course you can use 4K with Direct Uploads, too; you just need to set the same `"max_resolution_tier": "2160p"` field in the `new_asset_settings` of your create-direct-upload API call.
```json
// POST /video/v1/uploads
{
"new_asset_settings": {
"playback_policies": [
"public"
],
"video_quality": "basic",
"max_resolution_tier": "2160p"
},
"cors_origin": "*"
}
```
## Play your assets in 4K
For assets with 4K enabled at ingest, we'll automatically add 2K and 4K renditions to your HLS Playback URLs. Mux uses high-bitrate H.264 for delivering 4K content, which is supported on a wide range of devices, like Mux Player shown below.
While we've tested playback and built device detection rules that should protect you against unexpected playback failures, you should always test playback on your own device footprint before enabling 4K widely on your platform.
## Limiting playback resolution below 4K
Of course, you might not want all of your viewers to be able to view your content in 4K. Lots of streaming platforms choose to only offer 4K playback to their high subscription tiers. You can implement this by controlling playback resolution with the max\_resolution query parameter on your playback URLs, as shown below.
```
https://stream.mux.com/${PLAYBACK_ID}.m3u8?max_resolution=1080p
```
## Preparing 4K inputs
Mux uses just-in-time (JIT) encoding to make sure your assets are available as soon as possible after you create them, and this includes 4K assets.
Most of the usual restrictions for standard inputs still apply when you're using 4K, but there are a few different restrictions you should be aware of:
* The input must have a maximum dimension of 4096 pixels
* The input must have a maximum keyframe interval of 10 seconds
* The input must be 20 Mbps or less
* The input must have a frame rate between 5 fps and 60 fps
[You can find full details of the standard input specification for 1080p and 4K content in our documentation.](/docs/guides/minimize-processing-time#standard-input-specs)
## Stream 2K and 2.5K content
Mux Video also supports 2K and 2.5K (1440p) content. If you want your asset processed as 2/2.5K, you just need to set `"max_resolution_tier": "1440p"` in your create asset (or create direct upload) calls instead.
# Upload files directly
Allow your users to upload content directly to Mux.
## Overview
Direct Uploads allow you to provide an authenticated upload URL to your client applications so content can be uploaded directly to Mux without needing any intermediary steps. You still get to control who gets an authenticated URL, how long it's viable, and, of course, the Asset settings used when the upload is complete.
The most common use-case for Direct Uploads is in client applications, such as native mobile apps and the browser, but you could also use them to upload directly from your server or in a command line tool. Any time you don't feel the need to store the original on your own, just generate a signed URL and push the content directly.
Let's start by walking through the simplest use case of getting a file directly into Mux.
## Upload a file directly into Mux
### 1. Create an authenticated URL
The first step is creating a new Direct Upload with the Mux Asset settings you want. The Mux API will return an authenticated URL that you can use directly in your client apps, as well as an ID specific to that Direct Upload so you can check the status later via the API.
```curl
curl https://api.mux.com/video/v1/uploads \
-X POST \
-H "Content-Type: application/json" \
-u MUX_TOKEN_ID:MUX_TOKEN_SECRET \
-d '{ "new_asset_settings": { "playback_policies": ["public"], "video_quality": "basic" }, "cors_origin": "*" }'
```
```elixir
# config/dev.exs
config :mux,
access_token_id: "MUX_TOKEN_ID",
access_token_secret: "MUX_TOKEN_SECRET"
client = Mux.client()
params = %{"new_asset_settings" => %{"playback_policies" => ["public"], "video_quality" => "basic"}, "cors_origin" => "https://your-browser-app.com"}
Mux.Video.Uploads.create(client, params)
```
```go
import (
muxgo "github.com/muxinc/mux-go"
)
client := muxgo.NewAPIClient(
muxgo.NewConfiguration(
muxgo.WithBasicAuth(os.Getenv("MUX_TOKEN_ID"), os.Getenv("MUX_TOKEN_SECRET")),
))
car := muxgo.CreateAssetRequest{PlaybackPolicy: []muxgo.PlaybackPolicy{muxgo.PUBLIC}, VideoQuality: "basic"}
cur := muxgo.CreateUploadRequest{NewAssetSettings: car, Timeout: 3600, CorsOrigin: "*"}
u, err := client.DirectUploadsApi.CreateDirectUpload(cur)
```
```node
import Mux from '@mux/mux-node';
const mux = new Mux({
tokenId: process.env.MUX_TOKEN_ID,
tokenSecret: process.env.MUX_TOKEN_SECRET
});
mux.video.uploads.create({
cors_origin: 'https://your-browser-app.com',
new_asset_settings: {
playback_policy: ['public'],
video_quality: 'basic'
}
}).then(upload => {
// upload.url is what you'll want to return to your client.
});
```
```php
$config = MuxPhp\Configuration::getDefaultConfiguration()
->setUsername(getenv('MUX_TOKEN_ID'))
->setPassword(getenv('MUX_TOKEN_SECRET'));
$uploadsApi = new MuxPhp\Api\DirectUploadsApi(
new GuzzleHttp\Client(),
$config
);
$createAssetRequest = new MuxPhp\Models\CreateAssetRequest(["playback_policy" => [MuxPhp\Models\PlaybackPolicy::_PUBLIC], "video_quality" => "basic"]);
$createUploadRequest = new MuxPhp\Models\CreateUploadRequest(["timeout" => 3600, "new_asset_settings" => $createAssetRequest, "cors_origin" => "https://your-browser-app.com"]);
$upload = $uploadsApi->createDirectUpload($createUploadRequest);
```
```python
import mux_python
configuration = mux_python.Configuration()
configuration.username = os.environ['MUX_TOKEN_ID']
configuration.password = os.environ['MUX_TOKEN_SECRET']
uploads_api = mux_python.DirectUploadsApi(mux_python.ApiClient(configuration))
create_asset_request = mux_python.CreateAssetRequest(playback_policy=[mux_python.PlaybackPolicy.PUBLIC], video_quality="basic")
create_upload_request = mux_python.CreateUploadRequest(timeout=3600, new_asset_settings=create_asset_request, cors_origin="*")
create_upload_response = uploads_api.create_direct_upload(create_upload_request)
```
```ruby
MuxRuby.configure do |config|
config.username = ENV['MUX_TOKEN_ID']
config.password = ENV['MUX_TOKEN_SECRET']
end
uploads_api = MuxRuby::DirectUploadsApi.new
create_asset_request = MuxRuby::CreateAssetRequest.new
create_asset_request.playback_policy = [MuxRuby::PlaybackPolicy::PUBLIC]
create_asset_request.video_quality = "basic"
create_upload_request = MuxRuby::CreateUploadRequest.new
create_upload_request.new_asset_settings = create_asset_request
create_upload_request.timeout = 3600
create_upload_request.cors_origin = "https://your-browser-app.com"
upload = uploads_api.create_direct_upload(create_upload_request)
```
### 2. Use the URL to upload in your client
Once you've got an upload object, you'll use the authenticated URL it includes to make a `PUT` request that includes the file in the body. The URL is resumable, which means if it's a *really* large file you can send your file in pieces and pause/resume at will.
```ReactNative
async function uploadVideo () {
// videoUri here is the local URI to the video file on the device
// this can be obtained with an ImagePicker library like expo-image-picker
const imageResponse = await fetch(videoUri)
const blob = await imageResponse.blob()
// Create an authenticated Mux URL
// this request should hit your backend and return a "url" in the
// response body
const uploadResponse = await fetch('/backend-api')
const uploadUrl = (await uploadResponse.json()).url
try {
let res = await fetch(uploadUrl, {
method: 'PUT',
body: blob,
headers: { "content-type": blob.type}
});
console.log("Upload is complete");
} catch(error) {
console.error(error);
}
};
```
```curl
curl -v -X PUT -T myawesomevideo.mp4 "$URL_FROM_STEP_ONE"
```
```js
import * as UpChunk from '@mux/upchunk';
const upload = UpChunk.createUpload({
// getUploadUrl is a function that resolves with the upload URL generated
// on the server-side
endpoint: getUploadUrl,
// picker here is a file picker HTML element
file: picker.files[0],
chunkSize: 5120, // Uploads the file in ~5mb chunks
});
// subscribe to events
upload.on('error', err => {
console.error('💥 🙀', err.detail);
});
upload.on('progress', progress => {
console.log('Uploaded', progress.detail, 'percent of this file.');
});
// subscribe to events
upload.on('success', err => {
console.log("Wrap it up, we're done here. 👋");
});
```
```node
// assuming you're using ESM
import fs from "fs";
import got from "got";
const uploadUrl = /* Authenticated URL from step 1 */
got.put(uploadUrl, {
body: fs.createReadStream('/path/to/your/file'),
});
```
If you were following along with these examples, you should find new Assets in the Mux Dashboard with the settings you specified in the original upload create request, but the video you uploaded in the second step!
If the upload doesn't work via cURL, be sure that you've put quotes around the upload URL.
## Using Direct Uploads in your application
The examples above are a great way to upload a one-off file into Mux, but let's talk about how this workflow looks in your actual application. Typically you're going to want to do a few things:
* Authenticate the request that gives the user a signed URL so random people don't start ingesting Assets into your Mux account.
* Save information in your application about the file when the user creates the upload, such as who uploaded it and when, details about the video like title, tags, etc.
* Make sure the Asset that's ultimately created from that upload is associated with that information.
Just like Assets, Direct Uploads have their own events, and then the Asset created off the upload has the usual events as well. When you receive the `video.upload.asset_created` event you'll find an `asset_id` key that you could use in your application to tie the Asset back to the upload, but that gets tricky if your application misses events or they come out of order. To keep things simple, we like to use the `passthrough` key when creating an Asset. Let's look at how the passthrough workflow would work in a real application.
We provide SDKs for Android, iOS, iPadOS, and web frontend that handle difficult parts of the upload process, such has handling large files and preprocessing video for size and cost. Once your backend has created an authenticated URL for the upload, you you can give it to one of our Upload SDKs to reliably process and upload the the video.
For more information, check out our upload SDK guides:
* [Upload directly from an Android app](/docs/guides/upload-video-directly-from-android)
* [Upload directly from iOS or iPadOS](/docs/guides/upload-video-directly-from-ios-or-ipados)
* [Upload directly from your Web App](/docs/guides/mux-uploader)
[with-mux-video](https://github.com/vercel/next.js/tree/canary/examples/with-mux-video) is a full open-source example application that uses direct uploads
`npx create-next-app --example with-mux-video with-mux-video-app`
Another open-source example application is [stream.new](https://stream.new). GitHub repo link: [muxinc/stream.new](https://github.com/muxinc/stream.new)
`git clone git@github.com:muxinc/stream.new.git`
Both of these example applications use [Next.js](https://nextjs.org/), UpChunk, Mux Direct Uploads and Mux playback.
### Creating an `/upload` route in the application
In the route we build to create and return a new Direct Upload, we'll first create a new object in our application that includes a generated ID and all the additional information we want about that Asset. *Then* we'll create the Direct Upload and include that generated ID in the `passthrough` field.
```node
const { json, send } = require('micro');
const uuid = require('uuid/v1');
// This assumes you have MUX_TOKEN_ID and MUX_TOKEN_SECRET
// environment variables.
const mux = new Mux();
// All the 'db' references here are going to be total pseudocode.
const db = yourDatabase();
module.exports = async (req, res) => {
const id = uuid();
// Go ahead and grab any info you want from the request body.
const assetInfo = await json(req);
// Create a new upload using the Mux SDK.
const upload = await mux.video.uploads.create({
// Set the CORS origin to your application.
cors_origin: 'https://your-app.com',
// Specify the settings used to create the new Asset after
// the upload is complete
new_asset_settings: {
passthrough: id,
playback_policy: ['public'],
video_quality: 'basic'
}
});
db.put(id, {
// save the upload ID in case we need to update this based on
// 'video.upload' webhook events.
uploadId: upload.id,
metadata: assetInfo,
status: 'waiting_for_upload',
});
// Now send back that ID and the upload URL so the client can use it!
send(res, 201, { id, url: upload.url });
}
```
Excellent! Now we've got a working endpoint to create new Mux uploads that we can use in our Node app or deploy as a serverless function. Next we need to make sure we have an endpoint that handles the Mux webhooks when they come back.
```node
const { json, send } = require('micro');
// More db pseudocode.
const db = yourDatabase();
module.exports = async (req, res) => {
// We'll grab the request body again, this time grabbing the event
// type and event data so we can easily use it.
const { type: eventType, data: eventData } = await json(req);
switch (eventType) {
case 'video.asset.created': {
// This means an Asset was successfully created! We'll get
// the existing item from the DB first, then update it with the
// new Asset details
const item = await db.get(eventData.passthrough);
// Just in case the events got here out of order, make sure the
// asset isn't already set to ready before blindly updating it!
if (item.asset.status !== 'ready') {
await db.put(item.id, {
...item,
asset: eventData,
});
}
break;
};
case 'video.asset.ready': {
// This means an Asset was successfully created! This is the final
// state of an Asset in this stage of its lifecycle, so we don't need
// to check anything first.
const item = await db.get(eventData.passthrough);
await db.put(item.id, {
...item,
asset: eventData,
});
break;
};
case 'video.upload.cancelled': {
// This fires when you decide you want to cancel an upload, so you
// may want to update your internal state to reflect that it's no longer
// active.
const item = await db.findByUploadId(eventData.passthrough);
await db.put(item.id, { ...item, status: 'cancelled_upload' });
}
default:
// Mux sends webhooks for *lots* of things, but we'll ignore those for now
console.log('some other event!', eventType, eventData);
}
}
```
Great! Now we've got our application listening for events from Mux, then updating our DB to reflect the relevant changes. You could also do cool things in the webhook handler like send your customers events via [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) or [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API).
## Handle large files with UpChunk
In general, just making a `PUT` request with the file in the body is going to work fine for most client applications and content. When the files start getting a little bigger, you can stretch that by making sure to stream the file from the disk into the request. With a reliable connection, that can take you to gigabytes worth of video, but if that request fails, you or your customer are going to have to start the whole thing over again.
In those scenarios where you have really big files and potentially need to pause/restart a transfer, you can chunk up the file and use the resumable features of the upload endpoint! If you're doing it in a browser we wrote [UpChunk](https://github.com/muxinc/upchunk) to help, but the process isn't nearly as scary as it sounds.
### Installing UpChunk
**With NPM**
```shell
npm install --save @mux/upchunk
```
**With yarn**
```shell
yarn add @mux/upchunk
```
**With CDN**
```html
```
### Using UpChunk
```js
import * as UpChunk from '@mux/upchunk';
// Pretend you have an HTML page with an input like:
const picker = document.getElementById('picker');
picker.onchange = () => {
const getUploadUrl = () =>
fetch('/the-backend-endpoint').then(res => {
res.ok ? res.text() : throw new Error('Error getting an upload URL :(')
});
const upload = UpChunk.createUpload({
endpoint: getUploadUrl,
file: picker.files[0],
chunkSize: 5120, // Uploads the file in ~5mb chunks
});
// subscribe to events
upload.on('error', err => {
console.error('💥 🙀', err.detail);
});
}
```
```react
import React, { useState } from 'react';
import * as UpChunk from '@mux/upchunk';
function Page() {
const [progress, setProgress] = useState(0);
const [statusMessage, setStatusMessage] = useState(null);
const handleUpload = (inputRef) => {
try {
const response = await fetch('/your-server-endpoint', { method: 'POST' });
const url = await response.text();
const upload = UpChunk.createUpload({
endpoint: url, // Authenticated url
file: inputRef.files[0], // File object with your video file’s properties
chunkSize: 5120, // Uploads the file in ~5mb chunks
});
// Subscribe to events
upload.on('error', error => {
setStatusMessage(error.detail);
});
upload.on('progress', progress => {
setProgress(progress.detail);
});
upload.on('success', () => {
setStatusMessage("Wrap it up, we're done here. 👋");
});
} catch (error) {
setErrorMessage(error);
}
}
return (
);
}
export default Page;
```
### Alternatives to UpChunk
* Split the file into chunks that are a multiple of 256KB (`256 * 1024` bytes). For example, if you wanted to have 20MB chunks, you'd want each one to be 20,971,520 bytes (`20 * 1024 * 1024`). The exception is the final chunk, which can just be the remainder of the file. Bigger chunks will be a faster upload, but think about each one as its own upload in the sense of needing to restart that one if it fails, but needing to upload fewer chunks can be faster.
* Set a couple of headers:
* `Content-Length`: the size of the current chunk you're uploading.
* `Content-Range`: what bytes you're currently uploading. For example, if you've got a 10,000,000 byte file and you're uploading in ~1MB chunks, this header would look like `Content-Range: bytes 0-1048575/10000000` for the first chunk.
* Now use a `PUT` request like we were for "normal" uploads, just with those additional headers and each individual chunk as the body.
* If the server responds with a `308`, you're good to continue uploading! It will respond with as `200 OK` or `201 Created` when the upload is completed.
## Upload streamed data as it becomes available
When dealing with streaming data where the total file size is unknown until the end—such as live recordings or streaming AI generated data—you can upload the data to Mux in chunks as it becomes available.
This approach has several benefits:
* No need to know the total file size upfront
* Reduced memory usage on the client, because you're uploading chunks and releasing them instead of buffering the entire file in memory
* Faster uploads, because you're uploading chunks in parallel with the client instead of waiting for the entire file to be recorded
### Example: MediaRecorder
When recording media directly from a user's device using the [MediaRecorder API](https://developer.mozilla.org/en-US/docs/Web/API/MediaRecorder), the total file size is unknown until the recording is complete. To handle this, you can upload the media data to Mux in chunks as it becomes available, without needing to know the total size up front.
Let's look at an example of how to do this with a web app. First, we'll set up the MediaRecorder to capture media data in chunks. Each chunk will be passed to the `uploadChunk` function, which will upload it to Mux.
You can find a complete example repository demonstrating this approach in our [examples repo](https://github.com/muxinc/examples/tree/main/mediarecorder-streaming-uploads).
Start by declaring some global variables to track recording state and upload progress.
```javascript
// Global variables to track recording state and upload progress
let mediaRecorder;
let mediaStream;
let nextByteStart = 0;
const CHUNK_SIZE = 8 * 1024 * 1024; // 8MB chunks - must be multiple of 256KB
const maxRetries = 3; // Number of upload retry attempts
const lockName = 'uploadLock'; // Used by Web Locks API for sequential uploads
let activeUploads = 0; // Track number of chunks currently uploading
let isFinalizing = false; // Flag to prevent new uploads during finalization
```
Next, configure the MediaRecorder to capture media data in chunks.
```javascript
async function startRecording() {
// Request access to user's media devices
mediaStream = await navigator.mediaDevices.getUserMedia({ audio: true, video: true });
// Use a widely supported MIME type for maximum compatibility
const mimeType = 'video/webm';
// Initialize MediaRecorder with optimal settings
mediaRecorder = new MediaRecorder(mediaStream, {
mimeType,
videoBitsPerSecond: 5000000, // 5 Mbps video bitrate
audioBitsPerSecond: 128000 // 128 kbps audio bitrate
});
// Buffer to accumulate media data until we have enough for a chunk
let buffer = new Blob([], { type: mimeType });
let bufferSize = 0;
// Handle incoming media data
mediaRecorder.ondataavailable = async (event) => {
// Only process if we have data and aren't in the finalization phase
if (event.data.size > 0 && !isFinalizing) {
// Combine the new data with our existing buffer
// We use a Blob to efficiently handle large binary data
// The type must match what we specified when creating the MediaRecorder
buffer = new Blob([buffer, event.data], { type: mimeType });
bufferSize += event.data.size;
// Keep processing chunks as long as we have enough data
// This ensures we maintain a consistent chunk size of 8MB (CHUNK_SIZE)
// which is required by Mux's direct upload API
while (bufferSize >= CHUNK_SIZE) {
// Extract exactly CHUNK_SIZE bytes from the start of our buffer
const chunk = buffer.slice(0, CHUNK_SIZE);
// Keep the remainder in the buffer for the next chunk
buffer = buffer.slice(CHUNK_SIZE);
bufferSize -= CHUNK_SIZE;
// Upload this chunk, passing false for isFinalChunk since we're still recording
// nextByteStart tracks where in the overall file this chunk belongs
await uploadChunk(chunk, nextByteStart, false);
// Increment our position tracker by the size of the chunk we just uploaded
nextByteStart += chunk.size;
}
// Any remaining data stays in the buffer until we get more from ondataavailable
}
};
// Start recording, getting data every 500ms
mediaRecorder.start(500);
}
```
Uploaded chunks need to be delivered in multiples of 256KB (`256 * 1024` bytes). Since the chunks provided by the `MediaRecorder` API can be smaller than that, you'll need to collect them in a buffer until you have an aggregate chunk that is at least 256KB in size. 8MB is a good size for a chunk, so we'll use that as our chunk size in this example.
When the recording is complete, call the `stopRecording` function to upload the final chunk and clean up the MediaRecorder.
```javascript
async function stopRecording() {
// Only proceed if we have an active mediaRecorder
if (mediaRecorder && mediaRecorder.state !== 'inactive') {
// Stop recording new data
mediaRecorder.stop();
// Set flag to prevent new uploads from starting during finalization
isFinalizing = true;
// Wait for any in-progress chunk uploads to complete
// Check every 100ms until all uploads are done
while (activeUploads > 0) {
await new Promise(resolve => setTimeout(resolve, 100));
}
// If there's any remaining data in the buffer that hasn't been uploaded yet
// Upload it as the final chunk (isFinalChunk = true)
if (buffer.size > 0) {
await uploadChunk(buffer, nextByteStart, true);
nextByteStart += buffer.size;
}
// Clean up by stopping all media tracks (camera, mic etc)
if (mediaStream) {
mediaStream.getTracks().forEach(track => track.stop());
}
// Reset finalization flag now that we're done
isFinalizing = false;
}
}
```
Within the `uploadChunk` function, perform a `PUT` request to the authenticated Mux upload URL. Use the `Content-Range` header to indicate the byte range of the chunk being uploaded. Since the total file size is unknown, use `*` as the total size until the final chunk is uploaded.
```javascript
async function uploadChunk(chunk, byteStart, isFinalChunk) {
// Calculate the end byte position for this chunk by adding chunk size to start position
// Subtract 1 since byte ranges are inclusive (e.g. bytes 0-499 is 500 bytes)
const byteEnd = byteStart + chunk.size - 1;
// For the total size in the Content-Range header:
// - If this is the final chunk, use the actual total size (byteEnd + 1)
// - Otherwise use '*' since we don't know the final size yet
const totalSize = isFinalChunk ? byteEnd + 1 : '*';
// Set required headers for resumable upload:
// - Content-Length: Size of this chunk in bytes
// - Content-Range: Byte range being uploaded in format "bytes START-END/TOTAL"
const headers = {
'Content-Length': chunk.size.toString(),
'Content-Range': `bytes ${byteStart}-${byteEnd}/${totalSize}`,
};
let attempt = 0;
let success = false;
// Use Web Locks API to enforce sequential uploads
await navigator.locks.request(lockName, async () => {
activeUploads++;
while (attempt < maxRetries && !success) {
try {
const response = await fetch('MUX_DIRECT_UPLOAD_URL_HERE', {
method: 'PUT',
headers,
body: chunk
});
if (response.ok || response.status === 308) {
success = true;
} else {
throw new Error(`Upload failed with status: ${response.status}`);
}
} catch (error) {
attempt++;
if (attempt < maxRetries) {
await new Promise(resolve => setTimeout(resolve, attempt * 1000)); // Exponential backoff
} else {
throw error;
}
}
}
activeUploads--;
});
return success;
}
```
In the provided example, the [`navigator.locks.request`](https://developer.mozilla.org/en-US/docs/Web/API/Web_Locks_API) method is used to enforce sequential chunk uploads. This is necessary because if the `MediaRecorder` is stopped, the `ondataavailable` event can trigger multiple times simultaneously, which would cause multiple concurrent uploads if not properly synchronized. If you attempt to upload the final chunk before the previous uploads have completed, the upload will fail.
The final chunk is indicated by the `isFinalChunk` parameter, which is passed to the `uploadChunk` function. When `isFinalChunk` is `true`, the function will upload the remaining data in the buffer as the final chunk and modify the `totalSize` to reflect the total amount of data that was uploaded.
# Upload video directly from an Android app
Allow your users to upload content directly to Mux from a native Android app.
Direct Uploads allow you to provide an authenticated upload URL to your client applications so content can be uploaded directly to Mux without needing any intermediate steps. You still get to control who gets an authenticated URL, how long it's viable, and, of course, the Asset settings used when the upload is complete.
The Android Upload SDK allows a client application to upload video files from an Android device to Mux Video. The upload can be paused before completion and resume where it left off, even after process death.
Let's start by uploading a video directly into Mux from an Android application. The code from these examples can be found in our [upload example app](https://github.com/muxinc/android-upload-sdk/tree/main/app)
## Gradle setup
To integrate the Mux Upload SDK into your Android app, you first have to add it to your project, then create a `MuxUpload` object using an upload URL your app can fetch from a trusted server. Once you create the `MuxUpload`, you can start it with `start()`.
A working example can be found alongside our source code [here](https://github.com/muxinc/android-upload-sdk/tree/main/app).
## Add Mux's maven repository to your project
Add our maven repository to your project's `repositories` block. Depending on your setup, you may need to do this either the `settings.gradle` under `dependencyResolutionManagement` or your project's `build.gradle`.
```gradle\_kts
// In your repositories block
maven {
url = uri("https://muxinc.jfrog.io/artifactory/default-maven-release-local")
}
```
```gradle\_groovy
// In your repositories block
maven {
url "https://muxinc.jfrog.io/artifactory/default-maven-release-local"
}
```
## Add the Upload SDK to your app's dependencies
Add the upload SDK to your app's `dependencies` block in its `build.gradle` file.
```gradle\_kts
// in your app's dependencies
implementation("com.mux.video:upload:0.4.1")
```
```gradle\_groovy
// in your app's dependencies
implementation "com.mux.video:upload:0.4.1"
```
## Upload a video
In order to securely upload a video, you will need to create a PUT URL for your video. Once you have created the upload URL, return it to the Android client then use the `MuxUpload` class to upload the file to Mux.
## Getting an Upload URL to Mux Video
In order to upload a new video to Mux, you must first create a new Direct Upload to receive the file. The Direct Upload will contain a resumable PUT url for your Android client to use while uploading the video file.
You should not create your Direct Uploads directly from your app. Instead, refer to the [Direct Upload Guide](/docs/guides/upload-files-directly) to create them securely on your server backend.
## Creating and starting your `MuxUpload`
To perform the upload from your Android app, you can use the `MuxUpload` class. At the simplest, you need to build your `MuxUpload` via its `Builder`, then add your listeners and `start()` the upload.
```kotlin
/**
* @param myUploadUri PUT URL fetched from a trusted environment
* @param myVideoFile File where the local video is stored. The app must have permission to read this file
*/
fun beginUpload(myUploadUrl: Uri, myVideoFile: File) {
val upl = MuxUpload.Builder(myUploadUrl, myVideoFile).build()
upl.addProgressListener { innerUploads.postValue(uploadList) }
upl.addResultListener {
if (it.isSuccess) {
notifyUploadSuccess()
} else {
notifyUploadFail()
}
}
upl.start()
}
```
```java
/**
* @param myUploadUri PUT URL fetched from a trusted environment
* @param myVideoFile File where the local video is stored. The app must have permission to read this file
*/
public void beginUpload(Uri uploadUrl, File videoFile) {
MuxUpload upload = new MuxUpload.Builder(uploadUri, videoFile).build();
upload.setProgressListener(progress -> {
handleProgress(progress);
});
upload.setResultListener(result -> {
if (UploadResult.isSuccessful(progressResult)) {
handleSuccess(UploadResult.getFinalProgress(progressResult));
} else {
handleFailure(UploadResult.getError(progressResult));
}
});
upload.start();
}
```
### Resume uploads after network loss or process death
The upload SDK will keep track of uploads that are in progress. When your app starts, you can restart them using `MuxUploadManager`. For more information on managing, pausing, and resuming uploads, see the next section of this guide.
```kotlin
// You can do this anywhere, but it's really effective to do early in app startup
MuxUploadManager.resumeAllCachedJobs()
```
```java
// You can do this anywhere, but it's really effective to do early in app startup
MuxUploadManager.INSTANCE.resumeAllCachedJobs()
```
### Upload from a coroutine
If you're using Kotlin coroutines, you don't have to rely on the listener API to receive notifications when an upload succeeds or fails. If you prefer, you can use `awaitSuccess` in your coroutine.
```kotlin
suspend fun uploadFromCoroutine(videoFile: File): Result {
val uploadUrl = withContext(Dispatchers.IO) {
getUploadUrl() // via call to your backend server, see the guide above
}
val upload = MuxUpload.Builder(uploadUrl, videoFile).build()
// Set up your listener here too
return upload.awaitSuccess()
}
```
## Resuming and managing Uploads
`MuxUpload`s are managed globally while they are in-progress. Your upload can safely continue while your user does other things in your app. Optionally, you can listen for progress updates for these uploads in, eg, a foreground `Service` with a system notification, or a progress view in another `Fragment`.
### Find Uploads already in progress
`MuxUpload`s are managed internally by the SDK, and you don't have to hold onto a reference to your `MuxUpload` in order for the upload to complete. You can get a `MuxUpload` object for any file currently uploading using `MuxUploadManager`
This example listens for progress updates. You can also `pause()` or `cancel()` your uploads this way if desired.
```kotlin
fun listenToUploadInProgress(videoFile: File) {
val upload = MuxUploadManager.findUploadByFile(videoFile)
upload?.setProgressListener { handleProgress(it) }
}
```
```java
public void listenToUploadInProgress(File videoFile) {
MuxUpload uploadInProgress = MuxUploadManager.INSTANCE.findUploadByFile(videoFile);
if (uploadInProgress != null) {
uploadInProgress.setProgressListener(progress -> handleProgress(progress));
}
}
```
## Advanced
### Setting a Maximum resolution
If desired, you may choose a maximum resolution for the content being uploaded. You may wish to scale down the video files that are too large for your asset tier, for instance. This can save data costs for your users and it ensures that your assets are available to play as soon as possible.
The Mux Upload SDK scales down any input video larger than 4k (3840x2160 or 2160x3840) by default. You can choose to scale them down further to save on user data, or if you're targeting a basic video quality asset.
### Disable Input Standardization
The setting described here will only affect *local* changes to your input. Mux Video will still convert any non-standard inputs to a standard format during ingestion.
The Upload SDK is capable of processing input videos in order to optimize them for use with Mux Video. This behavior can be disabled if it isn't desired, although this may result in extra processing on Mux's servers. We don't recommend disabling standardization unless you are experiencing issues.
```kotlin
fun beginUpload(myUploadUrl: Uri, myVideoFile: File) {
val upl = MuxUpload.Builder(myUploadUrl, myVideoFile)
.standarizationRequested(false) // disable input processing
.build()
// add listeners etc
upl.start()
}
```
```java
public void beginUpload(Uri uploadUrl, File videoFile) {
MuxUpload upload = new MuxUpload.Builder(uploadUri, videoFile)
.standarizationRequested(false) // disable input processing
.build();
// add listeners etc
upload.start();
}
```
## Release notes
### Current release
### 1.0.0
New:
* 4k and 720p input standardization
* Background-Uploading example in sample app
Fixes:
* fix: currentStatus always reports READY
* fix: upload success reported as failure in some cases
### Previous releases
### 0.5.0
New:
* Audio transcoding
Improvements:
* Improved performance reporting
### 0.4.2
New
* feat: Add `UploadResult` class for java users to interpret Result
Fixes
* Fix: Some methods on MuxUpload.Builder don't return Builder
* Fix: the application context shouldn't be visible
* Fix: Transcoding errors handled incorrectly
### 0.4.1
New
* feat: Add API for listening to and retrieving the status of an upload
* feat: Add Input Standardization, to process videos device-side
Fixes
* fix: Metrics events not properly redirected
Known Issues
* There's no notification/callback for the result of input standardization
### 0.4.0
Improvements
* doc: Finish out the public KDoc
* doc: Improve KDocs and add logo
* nfc: Hide some internal classes from java. This should not affect anyone using the SDK
Fixes
* fix: pausing uploads shouldn't create errors
### 0.3.1
Improvements
* fix: Restarts broken due to invalid progress data
### 0.3.0
Breaking
* breaking: Remove extraneous MIME type and Retry Time Builder fields. Configuring these did nothing
Updates
* update: Add the ability to resume all failed or paused uploads
Improvements
* Greatly improved the example app
### 0.2.0
Improvements
* fix: Hide some constructors to prevent unintended use by java callers
* feat: Add Performance Metrics Tracking
### 0.1.0
🥳 First beta release of the Mux Android SDK
Features
* Upload multiple files at once
* Pause and resume uploads, even after process death
* Observe upload progress from anywhere in your app without extra code
# Upload video directly from iOS or iPadOS
Allow your users to upload video to Mux from an iOS or iPadOS application with Direct Uploads and the Upload SDK.
[Direct Uploads](/docs/guides/upload-files-directly) allow you to upload content from your client applications directly to Mux without needing any intermediary steps using an authenticated URL.
This guide will help you install the Upload SDK from Mux. The Upload SDK is designed to handle common tasks required to upload large video files, like file chunking and networking. By using the Upload SDK, your application will also become able to pause and resume uploads across restarts, report upload progress, and make adjustments that minimize processing time when your upload is ingested by Mux.
The Upload SDK is supported on iOS 14 and iPadOS 14, or higher. macOS is not supported at this time.
Your application can also handle uploads [on its own](/docs/guides/upload-files-directly#if-you-dont-want-to-use-upchunk) using built-in [`URLSession`](https://developer.apple.com/documentation/foundation/urlsession) and [file system](https://developer.apple.com/documentation/foundation/file_system) APIs. We encourage you to check out the Upload SDK [implementation](https://github.com/muxinc/swift-upload-sdk) as an example to follow along.
## Install the SDK
Let's start by installing the SDK. We'll use the Swift Package Manager. [Step-by-step guide on using Swift Package Manager in Xcode](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app).
Open your applications project in Xcode. In the Xcode menu bar select File > Add Packages. In the top-right corner of the modal window that opens enter the SDK repository URL which is `https://github.com/muxinc/swift-upload-sdk`.
By default Xcode will fetch the latest version of the SDK available on the `main` branch. If you need a specific package version or to restrict the range of package versions used in your application, select a different Dependency Rule. [Here's an overview of the different SPM Dependency Rules and their semantics](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app#Decide-on-package-requirements).
Click on Add Package to begin resolving and downloading the SDK package. When completed, select your application target as the destination for the `MuxUploadSDK` package product. To use the SDK in your application, import it's module: `import MuxUploadSDK`.
## Upload content from your application
## Getting an authenticated URL from Mux Video
You must create a new [Direct Upload](/docs/guides/upload-files-directly#1-create-an-authenticated-mux-url) to upload a new video to Mux.
The Direct Upload will contain an authenticated `PUT` url that's unique to your upload. Your application will upload video to this url.
Direct Uploads are resumable and if your application application started an upload and needed to pause it, use the same url to resume the upload.
We recommend that you avoid creating Direct Uploads outside of a trusted environment such as a backend server. Your application can request a new authenticated URL from your server when it needs one. You can also hardcode a pre-made URL in an internal build of your application for a one-time test.
## Create and start your direct upload
Once your application has an authenticated direct upload URL, you're ready to start uploading!
Your application will use the authenticated url to construct a `PUT` request. The body of the request will contain your video data. The `DirectUpload` API in the Upload SDK handles these operations for you.
Initialize a `DirectUpload` with your authenticated URL and a local video file URL. We'll also set the progress handler callback to log the upload progress to the console. In a later example you'll learn how to customize how an upload behaves.
```swift
import MuxUploadSDK
// The url found in the response after creating a direct upload
let authenticatedURL: URL = /* fetch from trusted environment */
// In this example we're uploading a video input file saved locally inside the application sandbox
let videoInputURL: URL = /* URL to a video available locally */
let directUpload = DirectUpload(
uploadURL: authenticatedURL,
inputFileURL: videoInputURL
)
// Let's log the progress to the console
directUpload.progressHandler = { state in
print("Uploaded (state.progress.completedUnitCount) / (state.progress.totalUnitCount)")
}
// Then start the direct upload
directUpload.start()
```
## Tactics for handling large files
### Chunking uploads
Smaller videos can be uploaded with a single request. We recommend breaking up larger videos into chunks and treating them as separate uploads.
The Upload SDK handles the required networking and file chunking operations for you regardless of file size. By default the SDK splits your video into *8MB* chunks when necessary. To change the chunk size your application will initialize its own `DirectUploadOptions` and pass the custom size as `chunkSizeInBytes`. Be sure to convert any quantities expressed in kilobytes or megabytes to bytes first.
Initialize a `DirectUpload` and pass the custom options you've created as the `options` parameter. A default set of options will be used if `options` isn't set when initializing a `DirectUpload`.
```swift
import MuxUploadSDK
let authenticatedURL: URL = /* fetch from trusted environment */
let videoInputURL: URL = /* URL to a video available locally */
// Construct custom upload options to upload a file in 6MB chunks
let chunkSizeInBytes = 6 * 1024 * 1024
let options = DirectUploadOptions(
chunkSizeInBytes: chunkSizeInBytes
)
// Initialize a DirectUpload with custom options
let directUpload = DirectUpload(
uploadURL: authenticatedURL,
inputFileURL: videoInputURL,
options: options
)
// Let's log the upload progress to the console
directUpload.progressHandler = { state in
print("Uploaded (state.progress.completedUnitCount) / (state.progress.totalUnitCount)")
}
// Then start the direct upload
directUpload.start()
```
Smaller chunk sizes result in more requests while larger chunk sizes lead to fewer requests that take longer to complete. We recommend using a smaller chunk size on unstable or lossy networks.
### What happens if an upload request fails?
When the SDK becomes aware of a failed upload `PUT` request, it will automatically retry it. By default the SDK will retry uploading each chunk up to 3 times before the upload is deemed to have failed. This limit can be altered by your application by initializing its own `DirectUploadOptions` with a custom value for `retryLimitPerChunk`. Then initialize a `DirectUpload` with the custom options as the `option` argument.
```swift
import MuxUploadSDK
let authenticatedURL: URL = /* fetch from trusted environment */
let videoInputURL: URL = /* URL to a video available locally */
// Construct custom upload options with a higher per-chunk retry limit
let options = DirectUploadOptions(
retryLimitPerChunk: 5
)
// Initialize a DirectUpload that will retry each chunk
// request up to 5 times
let directUpload = DirectUpload(
uploadURL: authenticatedURL,
inputFileURL: videoInputURL,
options: options
)
// Then start the direct upload
directUpload.start()
```
### Pause and resume uploads
Your application might become suspended or terminated in the middle of a long-running upload. You can avoid losing the progress completed so far by pausing the upload and resuming it when the app becomes active again.
```swift
import MuxUploadSDK
class UploadCoordinator {
func handleApplicationWillTerminate() {
UploadManager.shared.allManagedUploads().forEach { upload in
upload.pause()
}
}
func handleApplicationDidBecomeActive() {
UploadManager.shared.resumeAllUploads()
}
}
```
A direct upload can be resumed as long as it remains in a `waiting` status and hasn't yet transitioned to a `timed_out` status. You can customize this length of time by setting the `timeout` value in the create direct upload request to a value between 1 minute and 7 days. If no value is set the upload times out 1 hour after being *created*.
## Need a playable asset as fast as possible?
The APIs around this feature are not final.
After your direct upload is completed, Mux Video will convert the uploaded input into a playable asset.
Some types of inputs require additional processing time during ingestion before becoming ready for playback. By default the Upload SDK reduces the processing time by adjusting upload inputs locally to a faster-to-process format when needed. More details on how audio and video input formats relate to new asset processing time [available here](/docs/guides/minimize-processing-time).
### Setting a maximum resolution
The SDK can adjust the resolution of your video input locally before it is uploaded to Mux. By default the SDK will adjust the input resolution to 1920 x 1080 for any inputs that are larger.
You can also reduce the maximum resolution further to 1280 x 720. Initialize a new `DirectUploadOptions` and set `.preset1280x720` as `InputStandardization.maximumResolution`.
```swift
import MuxUploadSDK
let authenticatedURL: URL = /* fetch from trusted environment */
let videoInputURL: URL = /* URL to a video available locally */
// Reduce the maximum resolution to 1280 x 720
let options = DirectUploadOptions(
inputStandardization: .init(maximumResolution: .preset1280x720)
)
// Initialize a DirectUpload with custom options
let directUpload = DirectUpload(
uploadURL: authenticatedURL,
inputFileURL: videoInputURL,
options: options
)
// Then start the direct upload
directUpload.start()
```
### Skipping input adjustments
The setting described here will only affect *local* changes to your input. Mux Video will still convert any non-standard inputs to a standard format during ingestion.
In most cases your application won't need to bypass these adjustments. When necessary they can be skipped by initializing `DirectUploadOptions` and passing `.skipped` for `inputStandardization`, then passing those to the `options` argument when initializing a new `DirectUpload` like you've customized other options before.
```swift
import MuxUploadSDK
let authenticatedURL: URL = /* fetch from trusted environment */
let videoInputURL: URL = /* URL to a video available locally */
// Skip adjustments to your input locally
let options = DirectUploadOptions(
inputStandardization: .skipped
)
// Initialize a DirectUpload with that skips input standardization
// and uploads your video as-is
let directUpload = DirectUpload(
uploadURL: authenticatedURL,
inputFileURL: videoInputURL,
options: options
)
// Then start the direct upload
directUpload.start()
```
## Release notes
### Current release
### 1.0.0
Improvements
* Direct uploads are cancelable while inputs are standardized on the client
* Video inputs can be standardized to 2160p (4K) resolution
* Upload source `AVAsset` has the correct URL
Known Issues
* When checking if a video input file is standard or not, the SDK compares an averaged bitrate to a resolution-dependent limit. If different parts of the video input have varying input, the video may require further processing by Mux upon ingestion.
### 0.7.0
New
* Add macOS deployment target
Improvements
* Fix memory leak occurring when uploading large files
### 0.6.0
New
* Add Foundation Measurement API for chunk size
Breaking
* Rename Version to SemanticVersion for explicitness in API
Improvements
* Remove UIKit dependency from SDK
* Backfill missing inline API docs
### 0.5.0
New
* Add an overload initializer for `DirectUploadOptions`
Breaking
* Remove prefix use in public APIs and respell Upload as DirectUpload
### Previous releases
### 0.4.0
API Changes
* Deprecation: `MuxUpload.init(uploadURL:videoFileURL:chunkSize:retriesPerChunk:)` has been deprecated and will be removed in a future SDK version. Use `init(uploadURL:inputFileURL:options:)` instead
* Breaking Change: `MuxUpload.startTime` now returns an optional value
* Breaking Change: `MuxUpload.Status` has been renamed to `MuxUpload.TransportStatus`
* Add: `UploadOptions` struct to contain all available `MuxUpload` options
* Add: Options to request or to skip input standardization
* Add: `MuxUpload` initializer APIs that accept `AVAsset` or `PHAsset`
* Add: `MuxUpload.InputStatus` enum to represent the current state of the upload and change handler
New
* Support for on-device input standardization, create a playable asset from your direct upload faster. When input standardization is requested from the SDK, input video is converted to a standard range of values on a best-effort basis
Fixes
* Prevent integer overflow when calculating chunk request content ranges
* Prevent crash from chunk worker force unwrap
* Remove public methods from internal SDK classes
* Prevent removal of result handler properties when passing MuxUpload via UploadManager
### 0.3.0
API Changes
* `MuxUpload`'s initializer no longer requires a MIME type or Retry Time. These are calculated internally
* Added methods for querying the `UploadManager` for the list of currenty-active uploads, and listening for changes to the list
* Add opt-out for upload statistics
Improvements
* Add a much-improved example app
### 0.2.1
Improvements
* Track upload statistics
Fixes
* Resumed Uploads start at the beginning of the file
### 0.2.0
Improvements
* Remove Alamofire Dependency
### 0.1.0
Our first release of Mux's Swift Upload SDK!! 🎉 💯
This public beta release includes chunked, pause-able, resume-able video uploads for Mux Video. You can upload from anywhere in your app as well as query the upload state from anywhere in your app regardless of your app architecture. Uploads can be resumed even after your app restarted after a shutdown.
# Minimize processing time
Learn how to optimize your video files for the fastest processing time.
Mux Video accepts most modern video formats and codecs. However, certain types of inputs need to be *standardized* in order for Mux to do further operations on them, and this can add time before the video is ready to be streamed. If you want to standardize your content before sending it to Mux, and potentially improve performance, this guide will show what you need to do.
## Standard input specs
To be considered standard input, the input video file must meet the following requirements:
* **H.264 or HEVC video codecs**. H.264 is the dominant video codec in use today and almost every device supports H.264. HEVC is a more modern codec that's increasingly popular, though not as universally supported. While Mux accepts other codecs as input, other codecs are considered non-standard and will be standardized automatically to H.264.
* **Closed GOP** (group-of-pictures). (Warning: video jargon ahead. You can likely ignore this) In video files encoded with a closed-GOP, all B frames reference other frames in the same GOP. Closed GOPs always begins with an IDR (Instantaneous Decoder Refresh) frame. This means that every GOP can be played independently, without reference to another GOP. Standard inputs must be encoded with a closed-GOP.
* **8-bit 4:2:0, or 10-bit 4:2:0 if HEVC**. This refers to the color depth and chroma subsampling. If you don't know what this is, you can probably ignore this, since most streaming video is 8-bit 4:2:0. HDR usually uses 10-bit 4:2:0, which is only supported as standard when using the HEVC video codec. However, SDR is preferred as Mux does not provide full HDR support.
* **Simple Edit Decision Lists**. Edit Decision Lists (EDLs) are typically added during post-production and define how certain segments are used to build a track timeline for playback. A good example of a Simple Edit Decision List is to fix out of order frames in the video. Input files with more complex uses of EDLs are considered non-standard.
* **AAC audio codec**. AAC is the dominant audio codec in use today and almost every device supports this audio codec. While Mux accepts files that use other audio codecs, Mux only delivers AAC audio and non-AAC audio inputs are considered non-standard.
### Additional requirements for assets with a `max_resolution_tier` of 1080p
Assets ingested up to 1080p are subject to the following standard input requirements.
* **1080p/2K or smaller**. Files with a resolution of up to 2048x2048 are considered standard. Files with a larger than this are considered non-standard, unless ingested with a higher `max_resolution_tier`.
* **Max 20-second keyframe interval (10 seconds for HEVC)**. To stream well using HTTP-based streaming methods like HLS, Mux requires all keyframes intervals to be less than 20 seconds, or less than 10 seconds if encoded with HEVC.
* **8Mbps or below**. While Mux accepts higher bitrate inputs, average bitrates higher than 8Mbps are generally challenging for most viewers' connections and are considered non-standard. The bitrate should not exceed 16Mbps for any single GOP.
* **Frame rate between 5 and 120**. Inputs with average frames per second (fps) less than 5 or greater than 120 is considered non-standard. Frame rates within this range will be preserved (e.g. 60 fps will remain 60 fps). Inputs with less than 5 fps or greater than 120 fps will be automatically standardized to 30 fps.
### Additional requirements for assets with a `max_resolution_tier` of 2160p (4K)
[Assets ingested at 2K and 4K resolutions](/docs/guides/stream-videos-in-4k) are subject to the following standard input requirements.
* **2160p or smaller**. The input file must not have any dimension (width, height, or both) that exceeds 4096 pixels.
* **Max 10-second keyframe interval (6 seconds for HEVC)**. To stream 4k video well, a 10 second keyframe interval is required. If using the HEVC video CODEC, this is further limited to 6 seconds.
* **20Mbps or below**. While Mux accepts higher bitrate inputs, bitrates higher than 20Mbps are generally challenging for most viewers' connections.
* **Frame rate between 5 and 60**. For 4k videos, a frame rate above 60fps is considered non-standard.
## How to create standard input (ffmpeg)
As a starting point, here is a sample ffmpeg command for creating video that complies with Mux standard input. Feel free to modify this by using things like 2-pass encoding, different presets, or different bitrates (as long as the total bitrate ends up below than 8Mbps).
```shell
ffmpeg -i input.mp4 -c:a copy -vf "scale=w=min(iw\,1920):h=-2" -c:v libx264 \
-profile high -b:v 7000k -g 239 -pix_fmt yuv420p -maxrate 16000k -bufsize 24000k out.mp4
```
### Standard input for 4K
If you are creating a 4K video, the resolution and bitrate limits are higher. Here is a sample ffmpeg command for creating video that complies with Mux standard input for 4K.
```shell
ffmpeg -i input.mp4 -c:a copy -vf "scale=w=min(iw\,4096):h=-2" -c:v libx264 \
-profile high -b:v 18000k -g 239 -pix_fmt yuv420p -maxrate 36000k -bufsize 54000k out.mp4
```
## How to create standard input on mobile devices
Mux's [iOS](https://www.mux.com/docs/guides/upload-video-directly-from-ios-or-ipados) and [Android](https://www.mux.com/docs/guides/upload-video-directly-from-android) upload SDKs are optimised to pre-process video files created on mobile devices to create standard input video files before uploading to Mux.
Many mobile devices capture H.264 8-bit 4:2:0 video by default. More recent mobile devices increasing use HEVC 4:2:0 by default (either 8-bit with HDR disabled, or 10-bit with HDR enabled). Here are the main things to watch out for:
* Ensure that the total file bitrate is below 8 mbps.
* Prefer recording video in SDR (standard dynamic range). Some newer devices capture video in HDR (High Dynamic Range), which requires 10-bit 4:2:0 color. This is also acceptable, but may be more likely to exceed the limited bitrate to be considered standard input. If you have the choice, you should record SDR.
* Ensure the output file is smaller than 1080p (1920x1080) or 2K (2048x1152). Some cameras shoot 4K video, which by default is converted down to 1080p when using Mux Video. If you want to use 4K video, ensure you're enabling that in your API calls to Mux.
* If possible, choose a keyframe interval of 5s or so, but certainly between 1 and 10 seconds, and enable closed-GOP encoding. (If you don't see these options in your app or camera, it's probably the default already.)
## Non-standard input
Mux Video works fine with video outside of the standard input specs. But because other videos cannot be easily streamed to many modern devices, Mux Video must perform an initial encoding operation on non-standard input to create a mezzanine file. This means that non-standard input will be slower to ingest.
As soon as Mux Video detects that the input file is non-standard, it emits the `video.asset.non_standard_input_detected`. This lets you know right away that your video will need additional processing time, along with the specific reasons why it's considered non-standard.
```json
{
"type": "video.asset.non_standard_input_detected",
"data": {
"id": "{ASSET_ID}",
"status": "preparing",
"non_standard_input_reasons": {
"video_gop_size": "high"
}
// ... other asset fields
}
}
```
*Note that `non_standard_input_reasons` may not be finalized as additional reasons maybe found later and will be included on the asset after ingest completion.*
Mux Video also exposes this information in all subsequent asset webhooks, including the `video.asset.ready` event. This information is also returned in the asset object when retrieved using the Get Asset API.
### Understanding the transcoding progress of a non-standard input
When an asset needs additional processing, you can use the `progress` field from the Get Asset API response, which returns the current `state` of and, the completion percentage of a transcode.
```json
// GET /video/v1/assets/{ASSET_ID}
{
"id": "{ASSET_ID}",
"status": "preparing",
"non_standard_input_reasons": {
"video_gop_size": "high"
},
"progress": {
"state": "transcoding",
"progress": 23.02
}
// ... other asset fields
}
```
This field tells you both the current processing state and an estimated completion percentage from `0` to `100`, allowing you to keep your users informed with accurate progress indicators.
The progress field can have the following `state`s:
* `transcoding`: Asset is undergoing non-standard transcoding. `progress` will be between `0` and `100`.
* `ingesting`: Asset is being ingested (initial processing before or after transcoding). Progress will be `0`.
* `errored`: Asset has encountered an error (`status` is `errored`). Progress will be `-1`.
* `completed`: Asset processing is complete (`status` is `ready`). Progress will be `100`.
* `live`: Asset is a live stream currently in progress. Progress will be `-1`.
## General limits
The max duration for any single asset is 12 hours.
# Control recording resolution
If the video being captured in your app doesn't need to be played back in full resolution, specify a lower resolution when recording to take advantage of Mux's resolution dependent pricing.
## Android
The way you control the resolution of a recorded video depends on the API used to record or encode it. All of Google's major camera and recording APIs have a method for setting either the exact or maximum resolution of the videos they create.
### CameraX
With the CameraX library provide a `QualitySelector` that doesn't allow for resolutions beyond 720p (1280x720).
```kotlin
// Selects only Standard HD (720p) and Standard Definition (480p)
val selector = QualitySelector.fromOrderedList(
listOf(Quality.HD, Quality.SD),
FallbackStrategy.lowerQualityOrHigherThan(Quality.SD)
)
val recorder = Recorder.Builder()
.setQualitySelector(selector)
...
.build()
```
### MediaCodec
If you are encoding video yourself via the `MediaCodec` API, you can set the encoder's output resolution by setting it in the input `MediaFormat`. For more information on how to configure and use `MediaCodec`, [try the docs](https://developer.android.com/reference/android/media/MediaCodec)
```kotlin
val mediaCodec = MediaCodec.createByCodecName(codecName)
val encodeFormat = MediaFormat().apply {
setInteger(MediaFormat.KEY_FRAME_RATE, myExampleFrameRate)
//... Other required params
// Output 720p
setInteger(MediaFormat.KEY_HEIGHT, 720)
setInteger(MediaFormat.KEY_WIDTH, 1280)
}
mediaCodec.configure(
encodeFormat,
myInputSurface,
null,
MediaCodec.CONFIGURE_FLAG_ENCODE
)
```
### Camera2
Camera2 doesn't have an API to set the video resolution directly, but it infers it from the input surface. You have to call `SurfaceHolder.setFixedSize()` on your capture requests' targets. This can only be done on Lollipop/API 21 or higher. Please refer to [the camera2 docs](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#createCaptureSession\(android.hardware.camera2.params.SessionConfiguration\)) for more information
```kotlin
val supportedCameraResolutions = streamConfigMap.getOutputSizes(ImageFormat.NV21)
val size =
supportedCameraResolutions.toList().sortedBy { it.height }.findLast { it.height <= 720 && it.width <= 1280 }
size?.let { cameraSurfaceHolder.setFixedSize(it.width, it.height) }
cameraDevice.createCaptureRequest(CameraDevice.TEMPLATE_RECORD)
.apply { addTarget(cameraSurfaceHolder.surface) }
// ...
.build()
cameraDevice.createCaptureSession(...)
```
### MediaRecord
MediaRecord's output size can be configured by calling `MediaRecord.setVideoSize()` before calling `prepare()`.
```kotlin
mediaRecord.setVideoSize(1280, 720)
mediaRecord.prepare()
```
## iOS and iPadOS
This guide covers setting maximum video resolution when recording video on iOS and iPadOS. The directions and code examples on this page assume you are using AVFoundation to setup and configure your camera. If you’ve never used AVFoundation before we recommend you brush up on the basics before proceeding further, see the official Apple [documentation](https://developer.apple.com/documentation/avfoundation) for a quick introduction and sample code.
Video recording on iOS is managed using [AVCaptureSession](https://developer.apple.com/documentation/avfoundation/avcapturesession). The resolution for video output from AVCaptureSession can be configured using a settings preset and this example shows how to configure VCaptureSession to output video at a resolution of 720p (1280 x 720 pixels).
```swift
let session = fetchYourCaptureSession()
session.beginConfiguration()
let updatedSessionPreset = AVCaptureSession.hd1280x720
if session.canSetSessionPreset(updatedSessionPreset) {
session.sessionPreset = updatedSessionPreset
}
session.commitConfiguration()
```
Don’t forget to call `beginConfiguration()` before applying any configuration changes. When all the configuration changes have been applied, make sure your implementation calls `commitConfiguration()`.
It is best for any work that is done in-between calls to `beginConfiguration()` and `commitConfiguration()` to be synchronous. If you need to perform any asynchronous tasks, such as fetching the preferred resolution from your backend, make sure those are complete before you begin to configure `AVCaptureSession`.
## OBS
Streams initiated via [OBS](https://obsproject.com/) can be configured in Settings > Video > Output (Scaled) Resolution.
# Play your videos
In this guide you will learn how to play Mux videos in your application.
## 1. Get your playback ID
Each `asset` and each `live_stream` in Mux can have one or more **Playback IDs**.
This is an example of the `"playback_ids"` from the body of your `asset` or `live_stream` in Mux. In this example, the `PLAYBACK_ID` is `"uNbxnGLKJ00yfbijDO8COxTOyVKT01xpxW"` and the `policy` is `"public"`.
**Playback IDs** can have a policy of `"public"` or `"signed"`. For the purposes of this guide we will be working with `"public"` playback IDs.
If this is your first time using Mux, start out with `"public"` playback IDs and then read more about [securing video playback with signed URLs](/docs/guides/secure-video-playback) later.
```json
"playback_ids": [
{
"policy": "public",
"id": "uNbxnGLKJ00yfbijDO8COxTOyVKT01xpxW"
}
],
```
## 2. Create an HLS URL
HLS is a standard protocol for streaming video over the internet. Most of the videos you watch on the internet, both live video and on-demand video is delivered over HLS. Mux delivers your videos in this standard format.
Because HLS is an industry standard, you are free to use any HLS player of your choice when working with Mux Video.
HLS URLs end with the extension `.m3u8`. Use your `PLAYBACK_ID` to create an HLS URL like this:
```
https://stream.mux.com/{PLAYBACK_ID}.m3u8
```
If you're curious to learn more about how HLS works you might find this informational site [howvideo.works](https://howvideo.works) makes for some good bedtime reading.
## Other formats
HLS (`.m3u8`) is used for streaming assets (video on demand) and live streams. For offline viewing and post-production editing take a look at the guide for [download your videos](/docs/guides/download-your-videos) which covers `mp4` formats and master access.
## 3. Use the HLS URL in a player
Most browsers do not support HLS natively in the `video` element (Safari and IE edge are exceptions). Some JavaScript will be needed in order to support HLS playback in your web application.
The default player in iOS and TVOS (AVPlayer) supports HLS natively, so no extra effort is needed. In the Swift example below we're using the [VideoPlayer](https://developer.apple.com/documentation/avkit/videoplayer) struct that comes with SwiftUI and AVKit.
Similarly, the default player ExoPlayer on Android also supports HLS natively.
If you're using [Next.js](https://nextjs.org/) or React for your application, the [with-mux-video example](https://github.com/vercel/next.js/tree/canary/examples/with-mux-video) is a good place to start.
`npx create-next-app --example with-mux-video with-mux-video-app`
```android
implementation 'com.google.android.exoplayer:exoplayer-hls:2.X.X'
// Create a player instance.
SimpleExoPlayer player = new SimpleExoPlayer.Builder(context).build();
// Set the media item to be played.
player.setMediaItem(MediaItem.fromUri("https://stream.mux.com/{PLAYBACK_ID}.m3u8"));
// Prepare the player.
player.prepare();
```
```embed
```
```html
```
```react
import MuxPlayer from '@mux/mux-player-react';
export default function VideoPlayer() {
return (
);
}
```
```swift
import SwiftUI
import AVKit
let playbackID = "qxb01i6T202018GFS02vp9RIe01icTcDCjVzQpmaB00CUisJ4"
struct ContentView: View {
private let player = AVPlayer(
url: URL.makePlaybackURL(
playbackID: playbackID
)
)
var body: some View {
// VideoPlayer comes from SwiftUI
// Alternatively, you can use AVPlayerLayer or AVPlayerViewController
VideoPlayer(player: player)
.onAppear() {
player.play()
}
}
}
struct ContentView_Previews: PreviewProvider {
static var previews: some View {
ContentView()
}
}
extension URL {
static func makePlaybackURL(
playbackID: String
) -> URL {
guard let baseURL = URL(
string: "https://stream.mux.com"
) else {
preconditionFailure("Invalid base URL string")
}
guard let playbackURL = URL(
string: "\(playbackID).m3u8",
relativeTo: baseURL
) else {
preconditionFailure("Invalid playback URL component")
}
return playbackURL
}
}
```
## 4. Find a player
The examples below are meant to be a starting point. You are free to use **any player that supports HLS** with Mux videos. Here's some popular players that we have seen:
### Mux Player
```embed
```
```html
```
```react
import MuxPlayer from '@mux/mux-player-react';
export default function VideoPlayer() {
return (
);
}
```
See [the Mux Player guide](/docs/guides/mux-player-web) for more details and configuration options.
### Mux Video Element
If Mux Player does more than you're looking for, and you're interested in using something more like the native HTML5 `