Working with video

Learn how to handle video content in Sanity's Media Library.

Media Library's video streaming capabilities let you present high-quality, adaptive video content directly from your centralized asset storage. Videos uploaded to your Media Library are automatically processed and optimized for streaming through Mux, providing reliable video delivery with adaptive quality and global CDN distribution. You can also download the original file you uploaded and static renditions of it from the Media Library interface, separate from the playback stream.

This guide explains how to effectively present videos from your Media Library in your front-end applications. For information about uploading videos or configuring Media Library, see the Media Library documentation.

• A Sanity project with Media Library enabled and Studio v4.0.1 or later.
• Video addon enabled for your project. Video is an addon feature of Media Library and is not enabled by default. Contact sales to learn more.
• Video assets uploaded to your Media Library.

Before implementing videos in your front-end, it's important to understand how Media Library handles videos:

• Video fields are created using the defineVideoField helper from sanity/media-library
• Videos are processed to generate playback IDs for streaming
• Each video asset contains metadata, including aspect ratio, duration, and framerate

Note: Both public and private videos are supported. Private videos play through short-lived signed URLs rather than a public URL.

Media Library accepts most common video formats for upload.

Supported formats:

• MP4 (recommended)
• MOV
• AVI
• MKV
• WebM
• And most other standard video formats

Considerations:

• Processing time varies based on video length and resolution.
• Higher resolution videos (4K+) may take longer to process.

For best performance and compatibility, we recommend uploading videos in MP4 format with H.264 encoding. To minimize processing time, follow Mux's standard input specifications.

Video assets in your Media Library have a nested structure:

{
  "_id": "2yg9Un9RMsQjuf3WDqEo70ggi8D",
  "_type": "sanity.asset",
  "assetType": "sanity.videoAsset",
  "title": "video-filename.mp4",
  "versions": [
    {
      "instance": {
        "_id": "2yg9UGEpG8H4xjgMj8YSstwpfVh",
        "_type": "sanity.videoAsset",
        "originalFilename": "video-filename.mp4",
        "metadata": {
          "_type": "sanity.videoMetadata",
          "aspectRatio": 0.5625,
          "duration": 8.86,
          "playbacks": [
            {
              "_id": "V5uFaHghtnzgV6lYlBkrbehGkvd5KNGHYU7w2Eo7HoQ", // Mux playback ID
              "_type": "sanity.videoMetadata.playback",
              "policy": "public" // Only public videos are currently supported
            }
          ]
        },
        "mimeType": "video/mp4",
        "originalFilename": "video-filename.mp4"
      }
    }
  ]
}

Use the defineVideoField helper to create video fields in your studio schemas:

import { defineVideoField } from 'sanity/media-library'

export default {
  name: 'videoDocument',
  title: 'Video Document',
  type: 'document',
  fields: [
    defineVideoField({
      title: 'Featured Video',
      name: 'video',
    }),
    // ... other fields
  ]
}

There are two methods to fetch video data from your Media Library: using the Sanity client (recommended) or using GROQ queries.

The Sanity client provides a getPlaybackInfo() method that retrieves all necessary video information in a single call. This method requires API version v2025-03-25 or later.

First, configure your client to use Media Library:

import {createClient} from '@sanity/client'

const client = createClient({
  apiVersion: '2025-03-25',
  useCdn: false,
  token: 'your-token',
  '~experimental_resource': {
    type: 'media-library',
    id: 'your-media-library-id',
  },
})

Query for the document with your video field:

*[_type == 'videoDocument'] {
  title,
  video
}

{
  "title": "My Video Document",
  "video": {
    "_type": "sanity.video",
    "asset": {
      "_ref": "media-library:mlZxz9rvqf76:video-30rh9U3GDEK3ToiId1Zje4uvalC-mp4",
      "_type": "reference"
    }
  }
}

Fetch playback information using the video asset reference:

const document = await client.fetch(
  `*[_type == 'videoDocument']{ title, video }`
)

const playbackInfo = await client.mediaLibrary.video.getPlaybackInfo(
  document.video.asset
)

The response contains URLs for stream and images like the thumbnail, as well as useful metadata like duration and aspect ratio.

{
  id: "30rh9U3GDEK3ToiId1Zje4uvalC", // Playback ID
  stream: { url: "https://stream.m.sanity-cdn.com/..." },
  thumbnail: { url: "https://image.m.sanity-cdn.com/..." },
  animated: { url: "https://image.m.sanity-cdn.com/..." },
  storyboard: { url: "https://image.m.sanity-cdn.com/..." },
  duration: 120.5,
  aspectRatio: 1.77
}

You can also fetch video data using GROQ queries. Use the documents::get() function to follow the Global Dataset Reference and access the video asset:

*[_type == 'videoDocument'] {
  title,
  "video": documents::get(video.asset){
    _id,
    "aspectRatio": metadata.aspectRatio,
    "playbackId": metadata.playbacks[policy == "public"][0]._id
  }
}

{
  "title": "My Video Document",
  "video": {
    "_id": "video-30rh9U3GDEK3ToiId1Zje4uvalC-mp4",
    "aspectRatio": 0.5625,
    "playbackId": "V5uFaHghtnzgV6lYlBkrbehGkvd5KNGHYU7w2Eo7HoQ"
  }
}

For more comprehensive video information, you can query additional metadata:

*[_type == 'videoDocument'] {
  title,
  "video": documents::get(video.asset){
    _id,
    "aspectRatio": metadata.aspectRatio,
    "duration": metadata.duration,
    "originalFilename": originalFilename,
    "playbackId": metadata.playbacks[policy == "public"][0]._id
  }
}

To present videos from Media Library in your frontend, we'll use the Mux video player.

Install the Mux React player component:

npm install @mux/mux-player-react

pnpm add @mux/mux-player-react

yarn add @mux/mux-player-react

bun add @mux/mux-player-react

Here's the simplest way to display a video from your Media Library:

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

type VideoPlayerProps = {
  playbackId: string
  aspectRatio: number
}

export default function VideoPlayer({ playbackId, aspectRatio }: VideoPlayerProps) {
  return (
    <MuxPlayer
      customDomain="m.sanity-cdn.com"
      playbackId={playbackId}
      style={{
        width: '100%',
        height: '100%',
        aspectRatio: aspectRatio
      }}
    />
  )
}

Integrate with your GROQ query results:

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

type VideoData = {
  playbackId: string
  aspectRatio: number
  originalFilename: string
}

type DocumentWithVideoProps = {
  video: VideoData
}

export default function DocumentWithVideo({ video }: DocumentWithVideoProps) {
  if (!video?.playbackId) {
    return <div>No video available</div>
  }

  return (
    <div className="video-container">
      <MuxPlayer
        customDomain="m.sanity-cdn.com"
        playbackId={video.playbackId}
        style={{
          width: '100%',
          height: '100%',
          aspectRatio: video.aspectRatio
        }}
      />
    </div>
  )
}

Thumbnail images are automatically generated for your videos. You can use these as poster images:

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

export default function VideoWithPoster({ video }: { video: VideoData }) {
  const posterUrl = `https://image.m.sanity-cdn.com/${video.playbackId}/thumbnail.jpg`

  return (
    <MuxPlayer
      customDomain="m.sanity-cdn.com"
      playbackId={video.playbackId}
      poster={posterUrl}
      style={{
        width: '100%',
        height: '100%',
        aspectRatio: video.aspectRatio
      }}
    />
  )
}

You can also customize the poster image size and format:

// Custom poster with specific dimensions
const posterUrl = `https://image.m.sanity-cdn.com/${video.playbackId}/thumbnail.jpg?width=800&height=${Math.round(800 / video.aspectRatio)}&fit_mode=crop`

// Use WebP format for better compression
const optimizedPoster = `https://image.m.sanity-cdn.com/${video.playbackId}/thumbnail.webp?width=800&fit_mode=preserve`

Media Library provides video streaming and thumbnail generation through Mux. Understanding the URL structure helps you optimize video delivery:

Videos are delivered via HLS (HTTP Live Streaming) using this URL pattern:

https://stream.m.sanity-cdn.com/{playbackId}.m3u8

The Mux Player handles this automatically, but you can access the raw streaming URL if needed:

const hlsUrl = `https://stream.m.sanity-cdn.com/${video.playbackId}.m3u8`

Thumbnails are automatically generated using this URL pattern:

https://image.m.sanity-cdn.com/{playbackId}/thumbnail.{format}

You can customize thumbnails with query parameters, similar to Sanity's image pipeline:

// Basic thumbnail
const thumbnail = `https://image.m.sanity-cdn.com/${video.playbackId}/thumbnail.jpg`

// Specific size and format
const customThumb = `https://image.m.sanity-cdn.com/${video.playbackId}/thumbnail.webp?width=400&height=300`

// Crop and fit options
const croppedThumb = `https://image.m.sanity-cdn.com/${video.playbackId}/thumbnail.jpg?width=200&height=200&fit_mode=crop`

// Thumbnail from specific time (in seconds)
const timeThumb = `https://image.m.sanity-cdn.com/${video.playbackId}/thumbnail.jpg?time=30`

Available thumbnail parameters:

• width and height - Resize the thumbnail
• fit_mode - How to fit within dimensions (crop, preserve, stretch, pad)
• time - Extract thumbnail from specific video timestamp (in seconds)
• Format options: .jpg, .png, .webp

For the complete list of thumbnail transformation options, see the Mux thumbnail documentation.

From an asset's actions in the Media Library interface you can download the original file you uploaded and static renditions generated from it. The original is the exact source file; renditions are transcoded versions of the video.

Configure additional player features:

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

type AdvancedVideoProps = {
  video: {
    playbackId: string
    aspectRatio: number
    originalFilename: string
  }
  autoPlay?: boolean
  muted?: boolean
  onPlay?: () => void
  onEnded?: () => void
}

export default function AdvancedVideo({
  video,
  autoPlay = false,
  muted = false,
  onPlay,
  onEnded
}: AdvancedVideoProps) {
  return (
    <MuxPlayer
      customDomain="m.sanity-cdn.com"
      playbackId={video.playbackId}
      autoPlay={autoPlay}
      muted={muted}
      loop={false}
      preload="metadata"
      style={{
        width: '100%',
        height: '100%',
        aspectRatio: video.aspectRatio
      }}
      onPlay={onPlay}
      onEnded={onEnded}
    />
  )
}

For styling and theming options, see the Mux Player customization guide. The player supports:

• Custom accent colors
• CSS custom properties for extensive styling
• Multiple built-in themes
• Custom CSS for complete control over appearance

For looping, muted, autoplay videos use the dedicated @mux/mux-background-video React component rather than Mux Player. It is lightweight, uses HLS adaptive streaming, and is optimized for this use case.

Choose the right component based on how the video is used:

• Background video: short, looping, muted clips that autoplay silently. No playback controls. Use MuxBackgroundVideo.
• Interactive video: product demos, explainers, or any video the user actively watches with play/pause/seek controls. Use MuxPlayer.

npm install @mux/mux-background-video

pnpm add @mux/mux-background-video

yarn add @mux/mux-background-video

bun add @mux/mux-background-video

Pass the playback ID from your Media Library asset to the component. Include an <img> element as a poster — it displays while the video loads and is important for LCP performance.

import MuxBackgroundVideo from '@mux/mux-background-video'

type HeroBackgroundProps = {
  playbackId: string
}

export default function HeroBackground({ playbackId }: HeroBackgroundProps) {
  return (
    <MuxBackgroundVideo
      customDomain="m.sanity-cdn.com"
      playbackId={playbackId}
      style={{ width: '100%', height: '100%' }}
    >
      <img
        src={`https://image.m.sanity-cdn.com/${playbackId}/thumbnail.webp?width=1920&fit_mode=preserve`}
        alt=""
        aria-hidden="true"
      />
    </MuxBackgroundVideo>
  )
}

Use the maxResolution prop to cap the quality served. This reduces bandwidth usage when the video is displayed at a smaller size — for example, a full-bleed hero rarely needs more than 1080p.

<MuxBackgroundVideo
  customDomain="m.sanity-cdn.com"
  playbackId={playbackId}
  maxResolution="1080p"
  style={{ width: '100%', height: '100%' }}
>
  <img
    src={`https://image.m.sanity-cdn.com/${playbackId}/thumbnail.webp?width=1920&fit_mode=preserve`}
    alt=""
    aria-hidden="true"
  />
</MuxBackgroundVideo>

Available values: 270p, 360p, 480p, 540p, 720p, 1080p, 1440p, 2160p.

Background videos continue playing when users switch tabs, consuming CPU and battery. Pause playback when the page is hidden using the Page Visibility API:

import MuxBackgroundVideo from '@mux/mux-background-video'
import { useEffect, useRef } from 'react'

export default function HeroBackground({ playbackId }: { playbackId: string }) {
  const videoRef = useRef<HTMLVideoElement>(null)

  useEffect(() => {
    const handleVisibilityChange = () => {
      if (!videoRef.current) return
      if (document.hidden) {
        videoRef.current.pause()
      } else {
        videoRef.current.play()
      }
    }

    document.addEventListener('visibilitychange', handleVisibilityChange)
    return () => document.removeEventListener('visibilitychange', handleVisibilityChange)
  }, [])

  return (
    <MuxBackgroundVideo
      ref={videoRef}
      customDomain="m.sanity-cdn.com"
      playbackId={playbackId}
      maxResolution="1080p"
      style={{ width: '100%', height: '100%' }}
    >
      <img
        src={`https://image.m.sanity-cdn.com/${playbackId}/thumbnail.webp?width=1920&fit_mode=preserve`}
        alt=""
        aria-hidden="true"
      />
    </MuxBackgroundVideo>
  )
}

To maximize performance when displaying videos:

Use appropriate preload settings based on your use case:

• preload="none" - Don't preload anything. Best for pages with many videos.
• preload="metadata" - Preload video metadata only. Default setting.
• preload="auto" - Preload the entire video. Use sparingly, and avoid when loading multiple videos.

Lazy load videos below the fold as users scroll to reduce initial page load time.

Set maxResolution on the player to cap the maximum video quality and reduce bandwidth usage. Available options are "720p", "1080p", "1440p", and "2160p".

<MuxPlayer 
  playbackId={playbackId}  
  maxResolution="1080p"  
  style={{  
    width: '100%',  
    height: '100%',  
    aspectRatio: aspectRatio,
  }} 
/>

Use appropriately sized thumbnails instead of full-resolution images by utilizing the transformation options.

Consider implementing click-to-play for videos that aren't essential to the user experience to save bandwidth.

For above-the-fold videos, always provide a poster image. The <img> element inside MuxBackgroundVideo (or the poster prop on MuxPlayer) is treated as a Largest Contentful Paint candidate. Use an appropriately sized .webp thumbnail from the Mux image CDN to keep LCP fast.

Use minResolution alongside maxResolution to define a quality range. This is useful when your video contains text or fine detail that must remain legible — for example, a screen recording or product demo where 480p would be unacceptable.

<MuxPlayer
  customDomain="m.sanity-cdn.com"
  playbackId={playbackId}
  minResolution="720p"
  maxResolution="1080p"
  style={{ width: '100%', height: '100%', aspectRatio: aspectRatio }}
/>

• Check that the playback ID exists in your query: video.asset->metadata.playbacks[policy == "public"][0]._id
• Ensure your Media Library integration is properly configured
• Verify the GROQ query is returning the expected data structure

• Confirm @mux/mux-player-react is properly installed
• Check browser console for JavaScript errors
• Verify the container element has appropriate dimensions

• Ensure you're using the correct aspect ratio from video.asset->metadata.aspectRatio
• Note that aspect ratio is width/height (e.g., 0.5625 for 9:16 vertical video)
• Set proper container styles to maintain aspect ratio

Mux Player documentation

Complete guide to Mux Player features and customization options.

Media Library documentation

Learn more about configuring and using Media Library.

Creating custom aspects

Add custom metadata fields to your video assets.