@moviie/player-sdk

Vendor-agnostic JavaScript SDK for the Moviie video platform. Fetch playback metadata, build custom player UIs, and integrate Moviie playback into any runtime: Node.js, browsers, React Native, Expo, or edge workers.

Full documentation: docs.moviie.ai.

Prerequisites

You need a Moviie account and a publishable API key (mvi_pub_*).

1. Create an account at app.moviie.ai/signin.
2. Go to Organization Settings → API Keys and create a Publishable key.
3. Copy the key: it starts with mvi_pub_.

Never use a secret key (mvi_sec_*) in a client app. The playback API rejects it.

Install

pnpm add @moviie/player-sdk

Quick start

import { MoviieClient } from "@moviie/player-sdk"

const client = new MoviieClient({
  publishableKey: process.env.MOVIIE_PUBLISHABLE_KEY,
  clientInfo: {
    platform: "web",
    sdkVersion: "1.0.0",
  },
})

const playback = await client.getPlayback("YOUR-EMBED-UUID")
console.log(playback.playback.uri) // HLS stream URL

The returned MoviiePlaybackData includes the HLS source, poster, captions, chapters, CTAs, and per-embed control flags (Chromecast, PiP, autoplay, etc.). Wire it into any video element or player library.

API

new MoviieClient(options)

| Option | Type | Required | Description | |--------|------|:--------:|-------------| | publishableKey | string | ✓ | Publishable key (mvi_pub_*) from your Moviie organization settings. | | clientInfo | MoviieClientInfo | — | Optional bundle ID, platform, and SDK version. Sent as request headers for analytics and bundle-ID allowlisting. | | sdkVersion | string | — | Optional SDK version string sent with requests. |

client.getPlayback(embedId)

Fetches playback metadata for a public embed. Returns Promise<MoviiePlaybackData>. Throws a typed error on failure:

| Class | .code | Cause | |-------|---------|-------| | MoviieAuthError | auth | Invalid or missing publishable key. | | MoviieNotFoundError | not_found | Embed UUID does not exist. | | MoviieBundleBlockedError | bundle_blocked | Bundle ID not on the embed allowlist. | | MoviieReferrerBlockedError | referrer_blocked | Request origin present but not on the embed allowlist. | | MoviieDirectAccessBlockedError | direct_access_blocked | Video opened directly (no origin) while direct-URL access is blocked. | | MoviieSubscriptionInactiveError | subscription_inactive | Organization subscription is paused or expired. | | MoviieNetworkError | network | Network request failed (timeout, unreachable). | | MoviieRateLimitError | rate_limit | Too many requests in a short period. |

Detect by class or code string:

import { MoviieBundleBlockedError } from "@moviie/player-sdk"

try {
  await client.getPlayback(embedId)
} catch (error) {
  if (error instanceof MoviieBundleBlockedError) {
    // ask the user to update the allowlist in the Moviie dashboard
  }
  if (error?.code === "network") {
    // retry
  }
}

Looking for the React Native / Expo player?

If you're building a mobile app with Expo or React Native, use @moviie/player-expo: it wraps this SDK with a ready-to-use video component, custom chrome, Picture-in-Picture, background audio, and optional Chromecast.

License

MIT: see LICENSE. Copyright (c) 2026 Moviie.