Complete props and options reference for MoviieProvider, useMoviiePlayer, MoviieVideo, and MoviieErrorBoundary.

API reference

`<MoviieProvider>`

Place at the root of your app. Provides the Moviie client and viewer token store to the component tree.

Prop	Type	Required	Description
`publishableKey`	`string`	✓	Publishable key (`mvi_pub_*`) from your Moviie organization settings. Never use a secret key on the client.
`children`	`ReactNode`	✓	Your app tree.

<MoviieProvider publishableKey={process.env.EXPO_PUBLIC_MOVIIE_PUBLISHABLE_KEY}>
  <App />
</MoviieProvider>

Fetches playback metadata, creates the expo-video player, and manages native state. Spread its return value onto <MoviieVideo>.

Option	Type	Default	Description
`embedId`	`string`	—	Required. UUID of the embed from the Moviie dashboard.
`autoplay`	`boolean`	dashboard	Override the embed's autoplay setting. Omit to use the dashboard value.
`pictureInPicture`	`boolean`	dashboard	Override the embed's Picture-in-Picture setting. Omit to use the dashboard value.
`pictureInPictureAutoStart`	`boolean`	`false`	Automatically enter PiP when the app moves to the background. Requires PiP enabled.
`backgroundPlayback`	`boolean`	`false`	Keep audio playing when the app is backgrounded. Requires `backgroundPlayback: true` in the config plugin.
`lockScreenNowPlaying`	`boolean`	`false`	Show a Now Playing notification and lock screen controls.
`rememberPosition`	`boolean`	dashboard	Override the embed's "remember position" setting. Requires `expo-secure-store`.

Field	Type	Description
`player`	`VideoPlayer \| null`	The `expo-video` player instance. `null` on web (use the iframe path instead).
`playback`	`MoviiePlaybackData \| null`	Full playback metadata from the API. `null` while loading or on error.
`error`	`Error \| null`	Typed error object when the fetch fails. `null` when healthy. See Error handling.
`isLoading`	`boolean`	`true` while the initial playback fetch is in-flight.
`videoPresentation`	`MoviieVideoPresentationProps`	Pre-computed PiP and linear playback flags derived from `playback` and options. Spread directly onto `<MoviieVideo>`.
`retry`	`() => void`	Re-triggers the playback fetch. Called automatically by the built-in error shell.

Main playback component. Accepts the full return value of useMoviiePlayer spread as props, plus overrides.

Prop	Type	Default	Description
`player`	`VideoPlayer \| null`	—	Player instance from `useMoviiePlayer`.
`playback`	`MoviiePlaybackData \| null`	—	Playback metadata from `useMoviiePlayer`. Controls dashboard defaults.
`aspectRatio`	`number`	—	Width ÷ height ratio. E.g. `16 / 9`, `4 / 3`, `1`.
`isLoading`	`boolean`	—	From `useMoviiePlayer`. Shows a loading indicator in the chrome.
`error`	`Error \| null`	—	From `useMoviiePlayer`. Triggers the built-in error shell.
`retry`	`() => void`	—	From `useMoviiePlayer`. Called by the built-in retry button.

Prop	Type	Default	Description
`native`	`boolean`	`false`	Use the platform's native `VideoView` chrome. When `false`, renders the Moviie custom skin.
`nativeControls`	`boolean`	auto	Show or hide native `VideoView` controls. Only relevant when `native={true}`.
`controlsAutoHideMs`	`number`	`3000`	Milliseconds of inactivity before the Moviie chrome auto-hides.
`controlsVisibleByDefault`	`boolean`	`false`	Show the chrome immediately on mount without requiring a tap.

Prop	Type	Default	Description
`pictureInPicture`	`boolean`	hook / dashboard	Override PiP availability for this component.
`pictureInPictureAutoStart`	`boolean`	`false`	Auto-enter PiP when the app moves to the background.

Prop	Type	Default	Description
`castAdapter`	`MoviieCastAdapter \| null`	—	Chromecast adapter. Create with `createGoogleCastAdapter()` from `@moviie/player-expo/cast`. Without this, the cast button is hidden.
`cast`	`boolean`	dashboard	Override the embed's Chromecast toggle. `false` hides the button and silences the missing-adapter warning. `true` forces the button on even if the dashboard has it off.

Prop	Type	Default	Description
`onRetry`	`() => void`	—	Replace the default retry behaviour. You must call `moviie.retry()` yourself if you want the fetch to re-run.

Prop	Type	Default	Description
`onEmbedIframeRef`	`(iframe: MoviieWatchEmbedIframeHandle \| null) => void`	—	Callback receiving the iframe element reference. Use to call Player API methods via `postMessage`.
`loadEmbedScript`	`boolean`	`true`	Load the Moviie `embed.js` Player API script inside the iframe. Set `false` only if you manage the script yourself.

MoviieVideo also accepts all VideoViewProps from expo-video, except player (managed internally).

React error boundary that catches crashes inside <MoviieVideo> and prevents them from taking down the rest of your app.

Prop	Type	Default	Description
`children`	`ReactNode`	—	Component tree to protect. Wrap `<MoviieVideo>` here.
`fallback`	`({ error: Error, reset: () => void }) => ReactNode`	built-in shell	Custom fallback UI rendered on crash. Call `reset()` to unmount and remount the player tree.
`onError`	`(error: Error, info: React.ErrorInfo) => void`	—	Called on each caught error. Pass `Sentry.captureException` directly.

Shape of the object returned by useMoviiePlayer as playback (and useMoviiePlayback as data).

Field	Type	Description
`embedId`	`string`	UUID of the embed.
`title`	`string`	Embed title from the dashboard.
`durationSeconds`	`number \| null`	Video duration. `null` for live streams.
`isVertical`	`boolean`	`true` for portrait-oriented videos.
`posterUrl`	`string \| null`	Proxied thumbnail URL, or `null` if no thumbnail.
`smartProgressEnabled`	`boolean`	Whether the smart progress bar is active for this embed.
`playback`	`MoviiePlaybackPayload`	HLS stream URI and content metadata.
`branding`	`{ primaryColor, showWatermark, organizationName }`	Branding values from the dashboard.
`controls`	`MoviiePlaybackControls`	All dashboard control toggles.
`captions`	`MoviieCaption[]`	Available caption tracks.
`chapters`	`MoviieChapter[]`	Chapter markers.
`ctas`	`MoviieCTA[]`	Calls to action configured in the embed.
`telemetry`	`{ bootstrapUrl: string }`	Telemetry bootstrap endpoint.

These reflect the toggles set in the Moviie dashboard. Pass playback to <MoviieVideo> and the component reads them automatically.

Field	Type	Description
`autoplay`	`boolean`	Auto-start playback on load.
`preload`	`boolean`	Pre-buffer the stream before play.
`muted`	`boolean`	Start muted.
`loop`	`boolean`	Loop playback.
`showSpeed`	`boolean`	Show speed selector in the chrome.
`rememberPosition`	`boolean`	Resume from last position.
`chromecast`	`boolean`	Show the Chromecast button (requires `castAdapter`).
`disableAirplay`	`boolean`	Suppress the AirPlay button.
`showProgress`	`boolean`	Show the progress/timeline bar.
`showPlay`	`boolean`	Show the play/pause button.
`showPlayLarge`	`boolean`	Show the large centre play button.
`showCaptions`	`boolean`	Show the captions toggle.
`showSettings`	`boolean`	Show the settings menu.
`showPip`	`boolean`	Show the PiP button.
`showFullscreen`	`boolean`	Show the fullscreen button.
`showCurrentTime`	`boolean`	Show the current time counter.
`showDuration`	`boolean`	Show the total duration.
`showMute`	`boolean`	Show the mute button.
`showVolume`	`boolean`	Show the volume slider.
`seekBackwardEnabled`	`boolean`	Enable the seek-back 10s button.
`seekForwardEnabled`	`boolean`	Enable the seek-forward 10s button.
`showChapters`	`boolean`	Show the chapters menu.
`turboStartEnabled`	`boolean`	Enable turbo start (fast initial render).
`playbackRate`	`number`	Initial playback rate resolved by the server (creator/org default).