payload-mux

Set Mux credentials

The plugin and the Mux SDK read the standard MUX_* environment variables automatically, so the plugin call itself takes no arguments.

MUX_TOKEN_ID=...
MUX_TOKEN_SECRET=...
MUX_WEBHOOK_SECRET=...
NEXT_PUBLIC_SERVER_URL=https://your-site.com   # your site URL — becomes the upload CORS origin

Add the plugin

Zero-config reads the env vars above. For browser uploads, cors_origin resolves to options.uploadSettings.cors_origin ?? process.env.NEXT_PUBLIC_SERVER_URL ?? '*'. Pass options only to override: a non-standard env var name, a custom CORS origin, or signed playback.

import { buildConfig } from 'payload'
import { muxPlugin } from '@pro-laico/payload-mux'

export default buildConfig({
  plugins: [muxPlugin()], // credentials from MUX_*, cors_origin from NEXT_PUBLIC_SERVER_URL
})

MUX_SIGNING_KEY=...
MUX_PRIVATE_KEY=...

muxPlugin({
  options: {
    playbackPolicy: 'signed',               // new videos upload as signed
    signedUrlOptions: { expiration: '1d' }, // signed URL lifetime
  },
})

Generate the admin import map

The collection registers admin components (the uploader field and the list-view thumbnail cell) by string path, so regenerate the import map, then restart the dev server:

pnpm payload generate:importmap

The plugin has now added a Video (mux-video) collection to the admin. Drop a clip on it and Mux encodes it — no webhook needed yet; the uploader polls Mux for the encoding result.

Relate to a video from your collections

mux-video is a normal collection — reference it with a relationship field wherever you need video:

import type { CollectionConfig } from 'payload'

export const Posts: CollectionConfig = {
  slug: 'posts',
  fields: [
    { name: 'video', type: 'relationship', relationTo: 'mux-video' },
  ],
}

Play it back

Every ready video carries virtual playbackUrl / posterUrl / gifUrl fields, computed on read — no extra API calls. Hand them to any Mux player, e.g. @mux/mux-player-react (pnpm add @mux/mux-player-react):

import config from '@payload-config'
import MuxPlayer from '@mux/mux-player-react'
import { getPayload } from 'payload'

export default async function Page() {
  const payload = await getPayload({ config })
  const post = await payload.findByID({ collection: 'posts', id: '…', depth: 1 })

  const playback = typeof post.video === 'object' ? post.video?.playbackOptions?.[0] : undefined
  if (!playback) return null // still encoding — no playback ids yet

  return <MuxPlayer playbackId={playback.playbackId} src={playback.playbackUrl} poster={playback.posterUrl} />
}

More in Using video.

Once the site is live: point a Mux webhook at it

In the Mux dashboard, send webhooks to https://your-site.com/api/mux/webhook (or <your routes.api>/mux/webhook if you've customized Payload's API route), with MUX_WEBHOOK_SECRET matching the dashboard's signing secret.

The webhook is what finishes videos that encode slower than the upload's ~6s poll and what mirrors Mux-dashboard deletes back into Payload. It can't work locally — Mux has to POST to your site, and it can't reach localhost — but local development doesn't need it: the uploader and doc saves refetch the asset state from Mux on their own. See Endpoints and webhooks for exactly what depends on it.