Configuration

<MoviieProvider> props

Place <MoviieProvider> at the root of the subtree that renders players. It provides the Moviie client and the viewer-token store to the hooks and the component.

<MoviieProvider
  publishableKey={process.env.NEXT_PUBLIC_MOVIIE_PUBLISHABLE_KEY!}
  clientInfo={{ platform: "web" }}
>
  <App />
</MoviieProvider>

<MoviieVideo> presentation props

Beyond the playback state spread from useMoviiePlayer, <MoviieVideo> accepts a small set of presentation props. Every one defaults to the configuration the API delivers (the embed's dashboard settings); when you pass a prop, it overrides that value.

The control flags inside controls (for example showChapters, showSpeed, showFullscreen, showProgress) are the same set returned by the playback API. Pass only the flags you want to change:

<MoviieVideo {...moviie} controls={{ showChapters: false, showSpeed: false }} />

API config vs prop override

The rule is the same as the Expo player: the dashboard / embed configuration delivered by the API is the source of truth, and a prop you set overrides it for this component only. Omitting a prop preserves the dashboard value.

This lets you ship one embed configuration and still tailor a specific placement (for example, force autoplay={false} on a hero, or hide chapters in a compact layout) without changing the embed in the dashboard.

// Honors every dashboard setting:
<MoviieVideo {...moviie} aspectRatio={16 / 9} />

// Same embed, but this placement forces autoplay off and a custom accent:
<MoviieVideo {...moviie} aspectRatio={16 / 9} autoplay={false} accentColor="brand" />

Theming

The player ships its visual language as design tokens in @moviie/player-react/styles.css. Import it once (see Installation) and the chrome picks up the tokens automatically.

The accent color is driven by the Vidstack --media-brand custom property:

• By default it resolves to the embed's branding color.
• The accentColor prop overrides it per component.

<MoviieVideo {...moviie} accentColor="brand" />

You can also set --media-brand (and the other player tokens) through your own CSS to theme a wrapper or the whole app:

.my-player {
  --media-brand: #6d28d9;
}

SSR and Next.js App Router

The player is a client component: it renders the media element and binds to the browser at runtime.

• Mark the file that renders <MoviieProvider> / <MoviieVideo> with 'use client'. It hydrates on the client with no mismatch.
• The default in-memory viewerTokenStore is SSR-safe. The LocalStorageViewerTokenStore degrades to a silent no-op when there is no window, so it is safe to construct on the server too.
• AI overlays load on demand: the branded chrome and the AI-menu surfaces are code-split and mount the first time they are needed, keeping the initial bundle lean.
• CSP: the player needs no inline eval and runs under a standard Content Security Policy. Allow your media and API origins for connect-src / media-src as you would for any HLS player.

Playback engine and multiple players

The package bundles its own playback engine, so you do not install or configure one. Each <MoviieVideo> mounts an independent engine instance on its own element, so multiple players render and clean up independently on the same page (each tears its engine down on unmount). If your app already uses the same engine elsewhere, your package manager deduplicates matching versions, so there is no double download; mismatched majors simply resolve to separate copies without conflict, since the player never assumes a shared global.