How to Integrate Mux with Your Headless CMS

What is Mux?

Mux is an API platform for video streaming, live streaming, encoding, playback, and video performance data. Teams use Mux Video to ingest source files, transcode them into adaptive bitrate streams, and deliver playback through Mux Player or standard HLS players. It’s commonly used by media companies, education platforms, marketplaces, SaaS products, and teams that need video infrastructure without running their own encoding pipeline.

Why integrate Mux with a headless CMS?

Video gets messy fast when your editorial workflow and your playback pipeline live in separate places. An editor publishes a lesson, product story, or event recap, but someone still has to upload the file to Mux, copy the playback ID, paste it into the right entry, and check that the frontend uses the correct poster image, captions, and metadata. That works for 10 videos. It breaks when you’re shipping 200 localized product demos or daily clips across multiple channels.

Architecture overview

A typical Sanity and Mux integration starts when an editor publishes a video document in Sanity Studio. The document includes structured fields such as title, slug, sourceFile, posterImage, captions, transcript, and mux metadata. A Sanity webhook triggers on publish, or a Sanity Function runs on the content mutation. The handler receives the document ID, uses @sanity/client and a GROQ query to fetch the exact fields needed, including sourceFile.asset->url, and calls Mux’s Video Assets API with that URL as the input. Mux ingests the file, transcodes it into adaptive bitrate streams, and returns an asset ID while processing continues. When Mux sends a video.asset.ready webhook, your handler patches the original Sanity document with the playback ID, duration, aspect ratio, and ready status. The frontend then queries Sanity for the playback ID and renders the video with Mux Player, while the same structured content can also feed mobile apps, product pages, learning paths, and AI agents through Agent Context.

Common use cases

Step-by-step integration

1. 1

   Create Mux credentials

   Create a Mux account, then generate an access token from Settings > Access Tokens. Store MUX_TOKEN_ID and MUX_TOKEN_SECRET as environment variables. Install the SDK with npm install @mux/mux-node.

2. 2

   Model video content in Sanity Studio

   Create a video schema with fields like title, slug, sourceFile, posterImage, captions, transcript, muxAssetId, muxPlaybackId, muxStatus, duration, and aspectRatio. Keep Mux fields read-only for editors if they’re written by automation.

3. 3

   Create the sync trigger

   Use a Sanity webhook that fires when video documents are published, or use a Sanity Function to run server-side logic on mutations. Filter the trigger so drafts and unrelated document types don’t create Mux assets.

4. 4

   Call the Mux Video Assets API

   In the handler, fetch the published document with GROQ, read the source file URL, and call mux.video.assets.create with input: [{ url }]. Use playback_policy: ['public'] for public videos, or signed playback for gated content.

5. 5

   Patch Mux metadata back into Sanity

   Write muxAssetId and muxStatus back after asset creation. Add a second endpoint for Mux webhooks, especially video.asset.ready and video.asset.errored, so the document reflects the actual processing state.

6. 6

   Build and test playback

   Query the video document from your frontend and render muxPlaybackId with @mux/mux-player-react or the mux-player web component. Test a short MP4 first, then test a larger file, captions, poster images, signed playback if needed, and cache invalidation after publish.

How Sanity + Mux works

CMS approaches to Mux

Keep building

Explore related integrations to complete your content stack.