React 參考 | Genie Player

首發範圍僅限播放

Phase 1 documents player setup, caption selection, theming, and read-only hooks. Upload and caption editing stay in the dashboard.

完整範例

import {
  GeniePlayer,
  GenieProvider,
  type GenieTheme,
} from "@genie-player/react";
import "@genie-player/react/styles.css";

const theme = {
  colors: {
    accent: "#a78bfa",
    surface: "#211a36",
    text: "#faf9ff",
    muted: "#b6adc9",
    playerBackground: "#0b0713",
  },
  radius: "18px",
  fontFamily: "Inter, sans-serif",
} satisfies GenieTheme;

export function TranslatedVideo() {
  return (
    <GenieProvider theme={theme} clientKey={import.meta.env.VITE_GENIE_PLAYER_CLIENT_KEY}>
      <GeniePlayer
        jobId="translation-job-id"
        src="https://customer-cdn.example/video.mp4"
        defaultLanguage="es"
        controls
      />
    </GenieProvider>
  );
}

您的影片來源

Bienvenidos a la primera lección.

0:030:42CC

提供者主題

互動式播放預覽——不會送出影片或字幕請求。

Hosted WebVTT playback

Complete caption review before integrating the job. Genie then deletes its temporary video copy and keeps the approved WebVTT files available to authorized player requests.

Open Dashboard → Processing → Links to copy the stable job ID and React example. Direct WebVTT links are useful for testing, but they expire and cannot be used as jobId. Your separately hosted video URL remains the required src.

The player refreshes an authorized WebVTT URL when its browser token expires and attaches it to a native <track>. Do not hardcode expiring caption URLs in your application.

跨來源媒體

GeniePlayer defaults the native video element to crossOrigin="anonymous". This is required for a page to play customer-hosted video while loading Genie-hosted WebVTT tracks from another origin.

Your video CDN must return an Access-Control-Allow-Origin header that permits the player origin. Public media can use *; private media should return the exact origin. The Genie caption service supplies the matching CORS response for authorized WebVTT requests.

元件

Export	Purpose
GenieProvider	Configures the publishable client key or advanced token callback, API origin, and shared theme.
GeniePlayer	Plays the required customer-owned `src` with caption tracks from `jobId`.

`<GenieProvider>`

Prop	Type	說明
clientKey	`string?`	Recommended publishable key. The SDK exchanges it for a job- and origin-bound ten-minute playback token.
getClientToken	`() => Promise<string>`	Advanced alternative for private apps. Returns a short-lived `media:read` token from your backend.
baseUrl	`string?`	Overrides the Genie API origin.
fetch	`typeof fetch?`	Supplies a custom fetch implementation for instrumentation or tests.
theme	`GenieTheme?`	Partially overrides visual tokens for every SDK component.
children	`ReactNode`	Makes the configured playback client available below the provider.

Provide exactly one authentication option: clientKey or getClientToken. The SDK rejects configurations that contain both.

`<GeniePlayer>`

Prop	Type	說明
jobId	`string`	Required ID of the completed dashboard translation job.
src	`string`	Required customer-owned CDN or video-platform URL for the matching video.
defaultLanguage	`string?`	Caption track selected by default.
crossOrigin	`"anonymous" \| "use-credentials" \| ""`	Defaults to `"anonymous"` for cross-origin WebVTT playback. Override only when both media origins support the alternative mode.
video props	`VideoHTMLAttributes`	Native video props except `src`, which remains explicitly required.

Genie 不是您的影片託管服務

A job stores metadata and approved captions, not a playback copy of the source. A WebVTT URL or mediaId cannot substitute for jobId.

唯讀 Hooks

Export	Purpose
useGenieClient	Access the configured read-only browser client.
useGenieTheme	Access the resolved provider theme in custom components.
useTranslationJob	Load the approved job and report loading, ready, authentication, or failure states.
useCaptionTracks	Return the caption tracks currently available on a job.

const { job, error, isLoading } = useTranslationJob(jobId);
const tracks = useCaptionTracks(job);

Browser client

Method	Returns	Purpose
getTranslationJob	`Promise<TranslationJob>`	Retrieves a known approved job and its tracks.
getCaptionFile	`Promise<string>`	Downloads an approved canonical WebVTT file.
authorizeUrl	`Promise<string>`	Creates a short-lived URL for a native caption `<track>`.

主題自訂

Pass a partial GenieTheme to GenieProvider. It is merged with defaultGenieTheme, passed through React context, and applied to the player.

const theme = {
  colors: {
    accent: "#a78bfa",
    surface: "#211a36",
    text: "#faf9ff",
    muted: "#b6adc9",
    playerBackground: "#0b0713",
  },
  radius: "18px",
  fontFamily: "Inter, sans-serif",
} satisfies GenieTheme;

<GenieProvider theme={theme} clientKey={import.meta.env.VITE_GENIE_PLAYER_CLIENT_KEY}>
  <App />
</GenieProvider>

Player states

The launched playback model distinguishes loading, ready, job failure, network failure, authentication failure, and caption authorization failure. Processing and editing states are managed in the dashboard.