Mux Video Input Sanity Plugin

> For the v2 version, please refer to the v2-branch.

This plugin lets you use Mux video assets in your Sanity studio.

The Mux plugin for Sanity allows you to easily upload and preview videos.

Read our blog post about this plugin.

Not familiar with Sanity? Visit www.sanity.io

Installation

``
npm install sanity-plugin-mux-input
`

or

`
yarn add sanity-plugin-mux-input
`

Quick start

- While in your project folder, run npm i sanity-plugin-mux-input.
Read more about using plugins in Sanity here.

* Make a schema type that uses the plugin's type mux.video, for example:

`js
export default {
title: 'Video blog post',
name: 'videoBlogPost',
type: 'document',
fields: [
{title: 'Title', name: 'title', type: 'string'},
{
title: 'Video file',
name: 'video',
type: 'mux.video',
},
],
}
`

- Add the muxInput import to your plugins:

`js
import {defineConfig} from 'sanity'
import {muxInput} from 'sanity-plugin-mux-input'

export default defineConfig({
plugins: [muxInput()],
})
`

Read more about schemas in Sanity here.

- Get an API Access Token and enter it into the setup screen
First time you use the plugin you will be asked to enter your Mux credentials.

The Mux Video API uses an Access Token and Secret Key for authentication.

If you haven't already, generate a new Access Token in the Access Token settings of your Mux account dashboard, and make sure it got permission to both read and write _video_ and read _data_.

The token is stored in the dataset as a document of the type mux.apiKey with the id secrets.mux.
Having the ID be non-root ensures that only editors are able to see it.

The Mux plugin will find its access tokens by fetching this document.

Fetching playback IDs and understanding the data structure

When a Mux video is uploaded/chosen in a document via this plugin, it gets stored as a reference to the video document:

`json5
// example document
{
_type: 'exampleSchemaWithVideo',
// Example video field
myVideoField: {
_type: 'mux.video',
asset: {
_type: 'reference',
_weak: true,
_ref: '4e37284e-cec2-406d-973c-fdf9ab1e5598', // 👈 ID of the document holding the video's Mux data
},
},
}
`

Before you can display videos in your frontend, you need to follow these references to fetch the asset's playback ID, which will be used to create a player. Here's an example GROQ query to expand the video reference in the example data above:

`groq
// Example for fetching data above
*[ _type == "exampleSchemaWithVideo" ] {
myVideoField {
asset-> {
playbackId,
assetId,
filename,
}
}
}
`

💡 For more information on querying references, refer to the documentation on Writing GROQ queries for references or on Sanity's GraphQL API.

For reference, here's an example mux.videoAsset document:

`json5
{
_id: '4e37284e-cec2-406d-973c-fdf9ab1e5598',
_type: 'mux.videoAsset',
assetId: '7ovyI76F92n02H00mWP7lOCZMIU00N4iysDiQDNppX026HY',
filename: 'mux-example-video.mp4',
status: 'ready',
playbackId: 'YA02HBpY02fKWHDRMNilo301pdH02LY3k9HTcK43ItGJLWA',
thumbTime: 65.82,
// Full Mux asset data:
data: {
video_quality: 'plus',
max_resolution_tier: '1080p',
aspect_ratio: '16:9',
created_at: '1706645034',
duration: 25.492133,
status: 'ready',
master_access: 'none',
max_stored_frame_rate: 29.97,
playback_ids: [
{
id: 'YA02HBpY02fKWHDRMNilo301pdH02LY3k9HTcK43ItGJLWA',
policy: 'signed',
},
],
resolution_tier: '1080p',
ingest_type: 'on_demand_url',
max_stored_resolution: 'HD',
tracks: [
{
max_channel_layout: 'stereo',
max_channels: 2,
id: '00MKMC73SYimw1YTh0102lPJJp9w2R5rHddpNX1N9opAMk',
type: 'audio',
primary: true,
duration: 25.45,
},
{
max_frame_rate: 29.97,
max_height: 1080,
id: 'g1wEph3CVvbJL01YNKzAWMyH8N1SxW00WeECGjqwEHW9g',
type: 'video',
duration: 25.4254,
max_width: 1920,
},
],
id: '7ovyI76F92n02H00mWP7lOCZMIU00N4iysDiQDNppX026HY',
mp4_support: 'none',
},
}
`

Playing videos in the frontend

We recommend using Mux Player to properly display your videos, through packages like @mux/mux-player and @mux/mux-player-react. Here's an example of how you can use the Mux Player to display a video in a React component:

`tsx
'use client'

import MuxPlayer from '@mux/mux-player-react'

export default function MuxVideo({playbackId, title}: {playbackId?: string; title?: string}) {
if (!playbackId) return null

return
}
`

💡 You can try these recommendations through the Codesandbox example.

Configuring Mux Video uploads

$3

To enable signed URLs with content uploaded to Mux, you will need to check the "Enable Signed Urls" option in the Mux Plugin configuration. This feature requires you to set the API Access Token and Secret Key (as per the Quick start section).

⚠️ Important: To use Signed URLs, the API Access Token must have System permissions. Without these permissions, the signing key cannot be created, and authentication will fail.

📌 Note: When the signed URL option is triggered, the plugin will cache a signingKeyPrivate in a private document in the dataset. This key is used by Mux to sign the uploads, and if it's incorrect your uploads will fail. If that's the case, you can delete the secrets document and try again:

`bash


Using the Sanity CLI, delete the secrets, then re-open the plugin and configure it again


sanity documents delete secrets.mux
`

More information on signed URLs is available on Mux's docs

$3

To enable static MP4 renditions, add static_renditions to your plugin configuration. This allows users to download videos for offline viewing.

#### Standard Mode (Recommended)

`js
import {muxInput} from 'sanity-plugin-mux-input'

export default defineConfig({
plugins: [
muxInput({
static_renditions: ['highest'], // Enables MP4 downloads at the highest quality (up to 4K)
// or
static_renditions: ['highest', 'audio-only'], // Also includes audio-only (M4A) downloads
}),
],
})
`

Standard mode options:

- 'highest': Produces an MP4 file with video resolution up to 4K (2160p)
- 'audio-only': Produces an M4A (audio-only MP4) file

#### Advanced Mode (Specific Resolutions)

For more control, you can specify exact resolutions:

`js
import {muxInput} from 'sanity-plugin-mux-input'

export default defineConfig({
plugins: [
muxInput({
static_renditions: ['1080p', '720p', 'audio-only'],
}),
],
})
`

Advanced mode options:

- Specific resolutions: '270p', '360p', '480p', '540p', '720p', '1080p', '1440p', '2160p'
- 'audio-only': M4A file

Important notes:

- You cannot mix 'highest' with specific resolutions (e.g., ['highest', '1080p'] is invalid)
- Mux will not upscale videos - renditions requiring upscaling are automatically skipped
- When uploading new assets, editors can choose different rendition settings on a per-video basis

#### Backward Compatibility

The deprecated mp4_support field is still supported for backward compatibility:

`js
// ⚠️ Deprecated - use static_renditions instead
muxInput({mp4_support: 'standard'}) // Equivalent to static_renditions: ['highest']
`

More information can be found on Mux's documentation.

$3

To edit max_resolution_tier to support other resolutions other than 1080p, add max_resolution_tier: '1080p' | '1440p' | '2160p' to the options of your mux.video schema type. Defaults to 1080p.

`js
import {muxInput} from 'sanity-plugin-mux-input'

export default defineConfig({
plugins: [muxInput({max_resolution_tier: '2160p'})],
})
`

When uploading new assets, editors can still choose a lower resolution for each video than configured globally. This option controls the maximum resolution encoded or processed for the uploaded video. The option is particularly important to manage costs when uploaded videos are higher than 1080p resolution. More information on the feature is available on Mux's docs. Also, read more on this feature announcement on Mux's blog.

$3

The video quality level informs the cost, quality, and available platform features for the asset. You can choose between plus and basic at the plugin configuration. Defaults to plus.

`js
import {muxInput} from 'sanity-plugin-mux-input'

export default defineConfig({
plugins: [muxInput({video_quality: 'basic'})],
})
`

If video_quality: 'plus', editors can still choose to use the basic video quality level on a per-video basis when uploading new assets.

More information on the feature is available on Mux's documentation. Also, read more on the feature announcement on Mux's blog

$3

If you are using 'plus' video quality level, you can use Mux's auto-generated subtitles feature. Unless you pass disableTextTrackConfig: true to the configuration, users will be able to choose a language to auto-generate subtitles for uploaded videos. Refer to Mux's documentation for the list of supported languages.

You can also define a default language for the upload configuration form:

`js
import {muxInput} from 'sanity-plugin-mux-input'

export default defineConfig({
plugins: [
muxInput({
video_quality: 'plus',
defaultAutogeneratedSubtitleLang: 'en', // choose from one of the supported languages
}),
],
})
`

If your videos are always spoken in a specific language and you want to include captions by default, you can use disableTextTrackConfig: true together with defaultAutogeneratedSubtitleLang to transcribe captions for every uploaded asset without needing user interaction.

$3

By default, the plugin accepts both video and audio files (['video/', 'audio/']). You can configure which file types are accepted either globally at the plugin level or per-field at the schema level.

#### Plugin-level configuration

Configure accepted file types for all mux.video fields globally:

`js
import {muxInput} from 'sanity-plugin-mux-input'

export default defineConfig({
plugins: [
muxInput({
acceptedMimeTypes: ['video/*'], // Only accept video files
// or
acceptedMimeTypes: ['audio/*'], // Only accept audio files
// or
acceptedMimeTypes: ['video/', 'audio/'], // Accept both (default)
}),
],
})
`

#### Schema-level configuration

You can also configure acceptedMimeTypes for individual fields in your schema, which will override the plugin-level configuration:

`js
import { defineField, defineType } from "sanity";

export default defineType({
name: "muxTest",
title: "Mux Files",
type: "document",
fields: [
defineField({
name: "audioFile",
title: "Audio File",
type: "mux.video",
options: {
acceptedMimeTypes: ["audio/*"],
},
}),
defineField({
name: "videoFile",
title: "Video File",
type: "mux.video",
options: {
acceptedMimeTypes: ["video/*"],
},
}),
defineField({
name: "either",
title: "Either File",
type: "mux.video",
}),
],
});
`

The acceptedMimeTypes option controls the accept attribute on the file input, which filters which file types users can select when uploading. This affects both the file picker dialog and drag-and-drop file validation.

📌 Note: This option accepts an array of MIME type patterns. The valid values are:
- 'video/*' - Accepts all video file types
- 'audio/*' - Accepts all audio file types

For more information on the accept attribute, refer to the MDN documentation.

$3

You can configure maximum file size and video duration limits to prevent users from uploading videos that exceed your requirements. These validations run before the upload starts, providing immediate feedback to users.

#### Plugin-level configuration

Set validation limits for all mux.video fields globally:

`js
import {muxInput} from 'sanity-plugin-mux-input'

export default defineConfig({
plugins: [
muxInput({
maxAssetFileSize: 1024 1024 1024, // 1 GB in bytes
maxAssetDuration: 2 60 60, // 2 hours in seconds
}),
],
})
`

#### Schema-level configuration

You can override the global limits for specific fields, allowing different validation rules for different use cases:

`js
import { defineType, defineField } from "sanity";

export default defineType({
name: "muxTest",
title: "Mux Files",
type: "document",
fields: [
defineField({
name: "shortVideo",
title: "Short Video (max 1 minute)",
type: "mux.video",
options: {
maxAssetFileSize: 100 1024 1024, // 100 MB
maxAssetDuration: 60, // 1 minute
},
}),
defineField({
name: 'longVideo',
title: 'Long Video (max 2 hours)',
type: 'mux.video',
options: {
maxAssetFileSize: 1024 1024 1024, // 1 GB
maxAssetDuration: 2 60 60, // 2 hours
},
}),
defineField({
name: 'unlimitedVideo',
title: 'Unlimited Video',
type: 'mux.video',
// Uses plugin defaults or no validation if not configured
}),
]
})
`

Contributing

Issues are actively monitored and PRs are welcome. When developing this plugin the easiest setup is:

1. Fork this repo.
1. Create a studio v3 project: npm create sanity@dev-preview. Follow the prompts, starting out with the blog template is a good way to go.
1. cd into your project directory, run npm install && npm start - your sanity studio should be running on http://localhost:3333.
1. cd into the plugins directory of your project.
1. Fork this repo and clone your fork into the plugins directory inside your project git clone git@github.com:your-fork/sanity-plugin-mux-input.git.
1. Open sanity.json, go to the plugins array and add mux-input.
1. Re-start the sanity studio server with npm start.
1. Edit schemas/post.js and add follow the plugin documentation to add a mux.video type field.
1. Your studio should reload, and now when you edit the plugin code it should reload the studio, when you're done creating a branch, put in a PR and a maintainer will review it. Thank you!

$3

You can run the "CI and Release" workflow>).
Make sure to select the main branch and check "Release new version".

Semantic release will only release on configured branches, so it is safe to run release on any branch.

On the studio-v2 branch this will result in:

- a new version on the latest dist-tag.
- running yarn add sanity-plugin-mux-input or npm i sanity-plugin-mux-input will fetch the new version.
- running sanity install mux-input will fetch the new version.
- studio-v3 users are unaffected.

On the main branch this will result in:

- a new prerelease version on the studio-v3 dist-tag.
- running yarn add sanity-plugin-mux-input@studio-v3 or npm i sanity-plugin-mux-input@studio-v3 will fetch the new version.
- running sanity install mux-input won't fetch the new version.

After Studio v3 turns stable this behavior will change. The v2 version will then be available on the studio-v2 dist-tag, and studio-v3 is upgraded to live on latest.

$3

You can run the example locally by doing the following:

1. run npm install and npm dev on the root of the repo
2. In the terminal, a command with yalc will be shown, that command will allow you to run the version that you have locally directly on the example or on your own app.
3. run npm install and npm dev on the /example` directory where the app with the example exists or in your own app
4. the studio and app should auto reload with your changes in the plugin package you have locally

$3

Run "CI & Release" workflow.
Make sure to select the main branch and check "Release new version".

Semantic release will only release on configured branches, so it is safe to run release on any branch.

License

MIT-licensed. See LICENSE.