FAQ & Troubleshooting

Setup

Why doesn't the player work in Expo Go?

@moviie/player-expo depends on expo-video, a native module not included in the Expo Go binary. Symptom: blank screen or Cannot find native module ExpoVideo.

Solution: use a dev client or an EAS build.

pnpm expo prebuild
pnpm expo run:ios     # or run:android

Can I use the package on web only?

Yes. On Expo Web, useMoviiePlayer returns player: null and MoviieVideo renders a watch-URL iframe. No native modules are loaded, so the package works in any Next.js / Vite / Expo Web project without a prebuild.

See Expo Web.

Where do I set the publishable key?

In an environment variable, then pass it to <MoviieProvider>:

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

The key starts with mvi_pub_*. Never use a secret key (mvi_sec_*) on the client: those are for servers only.

Runtime errors

Please provide a valid embedId (public UUID of the embed)

useMoviiePlayback/useMoviiePlayer received an empty, undefined, or whitespace-only embedId. Verify that the ID comes from the Moviie dashboard (UUID v4 format).

HTTP 401 or HTTP 403 when loading playback

Common causes:

• Invalid or missing publishable key. Check MoviieProvider.publishableKey in the app.
• The embed belongs to a different organization. Verify the UUID in the dashboard.
• The embed is marked private and a viewer token was not negotiated (rare in SDK client; open a ticket).

Network request failed on iOS

The default endpoint is https://api.moviie.ai/v1: ATS allows HTTPS out of the box, so this error should not occur in production. If it does, check for corporate proxies or VPNs intercepting the connection.

HLS broken on Android (audio only)

Usually an unsupported codec on the device. Check:

1. Does the stream play in the web embed? If not, the problem is in the transcode/encode.
2. Check the expo-video log: player.addListener("statusChange", ...) shows the underlying error.

Cast / Chromecast

Cast button doesn't appear

Check in order:

1. Does the embed allow cast? In the dashboard, the "Chromecast" toggle must be ON.
2. Is castAdapter injected? Create it via createGoogleCastAdapter() from the @moviie/player-expo/cast subpath and pass it as a prop or via the registry.
3. Is react-native-google-cast installed? The /cast subpath imports this lib; without it the build fails (TypeScript) or Metro warns.
4. Is the react-native-google-cast plugin in app.json? Add it and run prebuild.
5. Physical device? iOS simulators don't detect Chromecast.

Cast button on Android doesn't open the dialog

react-native-google-cast requires a MediaRouteButton registered for showCastDialog() to work. The adapter creates an off-screen proxy (renderAndroidProxy): verify it is rendered inside the MoviieVideo component tree. The package also applies a native patch (patches/react-native-google-cast@4.9.1.patch) with a fallback via getCurrentActivity().

How do I end a cast session?

castAdapter.endSession() returns a Promise<void>. The local player does not automatically resume position in v1: it stays paused where it was before casting started.

Build

tsc fails with Cannot find module 'react-native-google-cast'

The lib is an optional peer dependency. If you don't use cast, install it as a dev dependency to satisfy TypeScript:

pnpm add -D react-native-google-cast

Or exclude the /cast subpath from your tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@moviie/player-expo/cast": ["./node_modules/@moviie/player-expo/dist/cast.d.ts"]
    }
  }
}

Metro: cannot find native module ExpoVideo

pnpm expo prebuild was not run after installing expo-video. Run prebuild followed by a native build (run:ios/run:android).

Performance

Frequent re-renders during scrubbing

<MoviieVideo> memoizes presentation props internally. If the consumer is recreating playback or player on every render, it breaks memoization. Use useMoviiePlayer (already memoized) and avoid recreating the playback object above the provider.

Final bundle grew significantly

@moviie/player-expo declares sideEffects only for index and layout. The /cast subpath is tree-shakeable: if you don't import it, it won't end up in the bundle.

Verify your bundler respects sideEffects (Metro: yes by default in RN 0.79+).

Getting help

• Moviie Discord: invite link in the dashboard
• GitHub Issues: github.com/moviie/moviie/issues
• Enterprise email: support@moviie.ai