@meta-sam/react 0.1.5

package/LICENSE

@@ -0,0 +1,61 @@
+SAM License
+Last Updated: November 19, 2025
+
+“Agreement” means the terms and conditions for use, reproduction, distribution and modification of the SAM Materials set forth herein.
+
+
+“SAM Materials” means, collectively, Documentation and the models, software and algorithms, including machine-learning model code, trained model weights, inference-enabling code, training-enabling code, fine-tuning enabling code, and other elements of the foregoing distributed by Meta and made available under this Agreement.
+
+“Documentation” means the specifications, manuals and documentation accompanying
+SAM Materials distributed by Meta.
+
+
+“Licensee” or “you” means you, or your employer or any other person or entity (if you are entering into this Agreement on such person or entity’s behalf), of the age required under applicable laws, rules or regulations to provide legal consent and that has legal authority to bind your employer or such other person or entity if you are entering in this Agreement on their behalf.
+
+
+“Meta” or “we” means Meta Platforms Ireland Limited (if you are located in or, if you are an entity, your principal place of business is in the EEA or Switzerland) or Meta Platforms, Inc. (if you are located outside of the EEA or Switzerland).
+
+
+“Sanctions” means any economic or trade sanctions or restrictions administered or enforced by the United States (including the Office of Foreign Assets Control of the U.S. Department of the Treasury (“OFAC”), the U.S. Department of State and the U.S. Department of Commerce), the United Nations, the European Union, or the United Kingdom.
+
+
+“Trade Controls” means any of the following: Sanctions and applicable export and import controls.
+
+By using or distributing any portion or element of the SAM Materials, you agree to be bound by this Agreement.
+
+
+1. License Rights and Redistribution.
+
+
+a. Grant of Rights. You are granted a non-exclusive, worldwide, non-transferable and royalty-free limited license under Meta’s intellectual property or other rights owned by Meta embodied in the SAM Materials to use, reproduce, distribute, copy, create derivative works of, and make modifications to the SAM Materials.
+
+b. Redistribution and Use.
+i. Distribution of SAM Materials, and any derivative works thereof, are subject to the terms of this Agreement. If you distribute or make the SAM Materials, or any derivative works thereof, available to a third party, you may only do so under the terms of this Agreement and you shall provide a copy of this Agreement with any such SAM Materials.
+
+
+ii.  If you submit for publication the results of research you perform on, using, or otherwise in connection with SAM Materials, you must acknowledge the use of SAM Materials in your publication.
+
+
+iii. Your use of the SAM Materials must comply with applicable laws and regulations, including Trade Control Laws and applicable privacy and data protection laws.
+iv. Your use of the SAM Materials will not involve or encourage others to reverse engineer, decompile or discover the underlying components of the SAM Materials.
+v. You are not the target of Trade Controls and your use of SAM Materials must comply with Trade Controls. You agree not to use, or permit others to use, SAM Materials for any activities subject to the International Traffic in Arms Regulations (ITAR) or end uses prohibited by Trade Controls, including those related to military or warfare purposes, nuclear industries or applications, espionage, or the development or use of guns or illegal weapons.
+2. User Support. Your use of the SAM Materials is done at your own discretion; Meta does not process any information nor provide any service in relation to such use.  Meta is under no obligation to provide any support services for the SAM Materials. Any support provided is “as is”, “with all faults”, and without warranty of any kind.
+
+
+3. Disclaimer of Warranty. UNLESS REQUIRED BY APPLICABLE LAW, THE SAM MATERIALS AND ANY OUTPUT AND RESULTS THEREFROM ARE PROVIDED ON AN “AS IS” BASIS, WITHOUT WARRANTIES OF ANY KIND, AND META DISCLAIMS ALL WARRANTIES OF ANY KIND, BOTH EXPRESS AND IMPLIED, INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. YOU ARE SOLELY RESPONSIBLE FOR DETERMINING THE APPROPRIATENESS OF USING OR REDISTRIBUTING THE SAM MATERIALS AND ASSUME ANY RISKS ASSOCIATED WITH YOUR USE OF THE SAM MATERIALS AND ANY OUTPUT AND RESULTS.
+
+4. Limitation of Liability. IN NO EVENT WILL META OR ITS AFFILIATES BE LIABLE UNDER ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, TORT, NEGLIGENCE, PRODUCTS LIABILITY, OR OTHERWISE, ARISING OUT OF THIS AGREEMENT, FOR ANY LOST PROFITS OR ANY DIRECT OR INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL, EXEMPLARY OR PUNITIVE DAMAGES, EVEN IF META OR ITS AFFILIATES HAVE BEEN ADVISED OF THE POSSIBILITY OF ANY OF THE FOREGOING.
+
+5. Intellectual Property.
+
+
+a. Subject to Meta’s ownership of SAM Materials and derivatives made by or for Meta, with respect to any derivative works and modifications of the SAM Materials that are made by you, as between you and Meta, you are and will be the owner of such derivative works and modifications.
+
+b. If you institute litigation or other proceedings against Meta or any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the SAM Materials, outputs or results, or any portion of any of the foregoing, constitutes infringement of intellectual property or other rights owned or licensable by you, then any licenses granted to you under this Agreement shall terminate as of the date such litigation or claim is filed or instituted. You will indemnify and hold harmless Meta from and against any claim by any third party arising out of or related to your use or distribution of the SAM Materials.
+
+6. Term and Termination. The term of this Agreement will commence upon your acceptance of this Agreement or access to the SAM Materials and will continue in full force and effect until terminated in accordance with the terms and conditions herein. Meta may terminate this Agreement if you are in breach of any term or condition of this Agreement. Upon termination of this Agreement, you shall delete and cease use of the SAM Materials. Sections 3, 4 and 7 shall survive the termination of this Agreement.
+
+7. Governing Law and Jurisdiction. This Agreement will be governed and construed under the laws of the State of California without regard to choice of law principles, and the UN Convention on Contracts for the International Sale of Goods does not apply to this Agreement. The courts of California shall have exclusive jurisdiction of any dispute arising out of this Agreement.
+
+
+8. Modifications and Amendments. Meta may modify this Agreement from time to time; provided that they are similar in spirit to the current version of the Agreement, but may differ in detail to address new problems or concerns. All such changes will be effective immediately. Your continued use of the SAM Materials after any modification to this Agreement constitutes your agreement to such modification. Except as provided in this Agreement, no modification or addition to any provision of this Agreement will be binding unless it is in writing and signed by an authorized representative of both you and Meta.

package/README.md

@@ -0,0 +1,250 @@
+# @meta-sam/react
+
+`@meta-sam/react` provides Canvas-only React bindings for Mediabunny playback and
+SAM 3 video segmentation. `Video` owns a media player and segmentation renderer;
+`useMediaPlayer` connects the same player to a caller-owned canvas. The package
+ships no global CSS.
+
+## Installation
+
+```sh
+npm install @meta-sam/react @meta-sam/parser react react-dom
+```
+
+React and React DOM `>=18.2 <20` are peer dependencies. Applications that import
+parser or video types directly should also declare those packages as direct
+dependencies.
+
+## `Video` quick start
+
+`Video` renders one canvas inside a wrapper. It accepts a URL string, `URL`, or
+`Blob`, discovers exact packet metadata through Mediabunny, and composites the
+decoded frame and segmentation into that canvas.
+
+<!-- readme-example -->
+
+```tsx
+'use client';
+
+import { useRef } from 'react';
+import { Video, type VideoRef } from '@meta-sam/react';
+import type { VideoSegmentationResult } from '@meta-sam/parser';
+
+declare const result: VideoSegmentationResult;
+
+export function SegmentedVideo() {
+  const videoRef = useRef<VideoRef>(null);
+
+  return (
+    <div>
+      <button type="button" onClick={() => void videoRef.current?.play()}>
+        Play
+      </button>
+      <button type="button" onClick={() => videoRef.current?.pause()}>
+        Pause
+      </button>
+      <button type="button" onClick={() => void videoRef.current?.seekToFrame(10)}>
+        Go to frame 10
+      </button>
+
+      <Video
+        ref={videoRef}
+        src="/media/clip.webm"
+        result={result}
+        objectFit="contain"
+        devicePixelRatio={() => window.devicePixelRatio || 1}
+        volume={0.8}
+        style={{ width: 640 }}
+        canvasProps={{ 'aria-label': 'Segmented video' }}
+        onTimeChange={(time) => console.log('time', time)}
+        onError={(error) => console.error('Video failed', error)}
+      />
+    </div>
+  );
+}
+```
+
+`result` accepts either a cumulative `VideoSegmentationSnapshot` while parsing is
+in progress or the final `VideoSegmentationResult`. Updating `result`,
+`hiddenIds`, `objectFit`, or `devicePixelRatio` recomposes the retained decoded
+frame without replacing the player or reopening the source.
+
+## Props
+
+| Prop                                      | Behavior                                                                                                    |
+| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `src`                                     | Required media source: string, `URL`, or `Blob`. A new value replaces the source on the existing player.    |
+| `result`                                  | Cumulative video segmentation snapshot or final result. Image results are rejected at runtime.              |
+| `renderer`                                | Optional caller-owned `SegmentationRenderer`. When omitted, `Video` creates and disposes one.               |
+| `hiddenIds`                               | Object IDs omitted from the composition without changing retained segmentation state.                       |
+| `objectFit`                               | `contain` (default), `cover`, or `fill` for both frame and overlay geometry.                                |
+| `devicePixelRatio`                        | Positive number or function read while sizing and rendering the canvas.                                     |
+| `loop`, `playbackRate`, `volume`, `muted` | Controlled playback and audio settings.                                                                     |
+| `initialSeekTime`                         | Initial time used when each new source opens. Changing it alone does not reopen or seek the current source. |
+| `autoPlay`                                | Starts playback after a source opens. Browser user-activation policy still applies.                         |
+| `playerOptions`                           | Construction-only `MediaPlayerOptions` for advanced audio configuration.                                    |
+| `className`, `style`                      | Configure the wrapper. The default wrapper is positioned, clipped, and full width.                          |
+| `canvasProps`                             | Canvas attributes and styles except `ref`, children, and backing width/height, which the component owns.    |
+
+The wrapper adopts the decoded video's aspect ratio after metadata loads unless
+`style.aspectRatio` overrides it. The canvas backing dimensions track its CSS
+size and DPR. A `ResizeObserver` is used when available.
+
+`autoPlay` runs after asynchronous source initialization and therefore cannot preserve
+a caller's user-activation token. Browsers may block Web Audio startup and the player
+will report the fallback through `onAudioWarning`. For reliable audible playback, call
+`videoRef.current?.play()` directly from a trusted click or key handler.
+
+## Callbacks
+
+Callbacks always use the newest committed prop without reconstructing the player:
+
+- `onTimeChange(time)`
+- `onPlayingChange(playing)`
+- `onDurationChange(duration)`
+- `onLoadedMetadata(metadata)`
+- `onFrame({time, frameIndex})`
+- `onAudioStatusChange(status)`
+- `onAudioWarning(warning)`
+- `onError(error)`
+- `onPlayerReady(player)`
+
+`onPlayerReady` reports construction, not source readiness. Use
+`onLoadedMetadata` for a successfully opened source. In development StrictMode,
+more than one short-lived player may be reported; each is disposed by its
+matching effect cleanup.
+
+## `VideoRef`
+
+The imperative ref exposes the Canvas player without exposing a media-element
+reference:
+
+```ts
+interface VideoRef {
+  play(): Promise<void>;
+  pause(): void;
+  seek(time: number): Promise<void>;
+  seekToFrame(frameIndex: number): Promise<void>;
+  nextFrame(): Promise<void>;
+  previousFrame(): Promise<void>;
+  getFrameIndexAtTimeExact(time: number): number;
+  getTimeAtFrameIndexExact(frameIndex: number): number;
+  getPacketAtTimeExact(time: number): VideoPacketMetadata;
+  getVideoPackets(): VideoPacketTimeline;
+  setPlaybackRate(playbackRate: number): void;
+  setVolume(volume: number): void;
+  setMuted(muted: boolean): void;
+  setLoop(loop: boolean): void;
+  forceRender(): Promise<void>;
+  captureFrame(source?: 'composited' | 'raw'): HTMLCanvasElement;
+  getStats(): VideoStats;
+  resetStats(): void;
+}
+```
+
+`captureFrame()` returns a detached canvas owned by the caller. The default
+captures the visible composited frame; `raw` captures the retained decoded frame.
+Canvas security rules still apply if callers later export pixels from that
+snapshot. `getStats()` forwards the player's frozen `PlaybackStats` snapshot,
+including bounded decode/overlay timings, scheduler counters, queue depths,
+signed A/V presentation-window error, and audio gap/underrun/drop diagnostics.
+`resetStats()` clears that measurement interval without changing playback.
+
+Async methods (`play`, both seek forms, frame stepping, and `forceRender`) return
+rejected promises when called through a retained handle after unmount; they never throw
+before returning. Synchronous controls, lookups, capture, and stats throw when no player
+is mounted. React clears a normally attached ref on unmount, so prefer checking
+`ref.current` at the call site.
+
+## Caller-owned canvas with `useMediaPlayer`
+
+Use the hook for custom composition or controls while retaining React lifecycle
+ownership:
+
+<!-- readme-example -->
+
+```tsx
+'use client';
+
+import { useRef } from 'react';
+import { useMediaPlayer } from '@meta-sam/react';
+
+export function CanvasPlayer({ src }: { src: string | URL | Blob }) {
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+  const playerRef = useMediaPlayer({
+    canvasRef,
+    src,
+    volume: 0.5,
+    renderFrame({ ctx, canvas, frame }) {
+      ctx.clearRect(0, 0, canvas.width, canvas.height);
+      ctx.drawImage(frame, 0, 0, canvas.width, canvas.height);
+    },
+    onError(error) {
+      console.error('Playback failed', error);
+    },
+  });
+
+  return (
+    <div>
+      <button type="button" onClick={() => void playerRef.current?.play()}>
+        Play
+      </button>
+      <canvas ref={canvasRef} width={640} height={360} />
+    </div>
+  );
+}
+```
+
+The returned `RefObject<IMediaPlayer | null>` is stable. The hook creates a player after
+the canvas is attached, replaces it only when that canvas node changes, opens a changed
+`src` on the existing player, and disposes owned players on replacement and unmount.
+Failed opens are retryable when the component renders that source again. `renderFrame`
+and all callbacks are read through current refs, so callback changes do not recreate the
+player.
+
+The hook owns the player. Do not dispose a player received through
+`onPlayerReady`; use the component lifecycle instead.
+
+## Renderer ownership and update ordering
+
+When `renderer` is omitted, every effect setup owns one renderer and disposes it
+exactly once. A supplied renderer always remains caller-owned and is never
+disposed by `Video`.
+
+Accepted segmentation values are applied with `{reset: true}` because parser
+snapshots are cumulative. Result work is generation-fenced: a late update from a
+replaced result or renderer cannot trigger a stale redraw. Source replacement is
+independently generation-fenced by `@meta-sam/video`.
+
+## Migration from the previous React surface
+
+| Previous API                                 | Canvas-only API                                        |
+| -------------------------------------------- | ------------------------------------------------------ |
+| `source`                                     | `src` accepting a string, `URL`, or `Blob`             |
+| caller-provided `timeline`                   | Removed; exact packet metadata is read from the source |
+| overlaid native video plus canvas            | One composited canvas                                  |
+| `fit`                                        | `objectFit`                                            |
+| `videoProps`                                 | Removed                                                |
+| `VideoHandle`                                | `VideoRef`                                             |
+| `seek({timestamp})`                          | `seek(time)`                                           |
+| `seek({frameIndex})`                         | `seekToFrame(frameIndex)`                              |
+| `requestRender()`                            | `forceRender()`                                        |
+| `useVideoPlayer({videoRef, canvasRef, ...})` | `useMediaPlayer({canvasRef, src, ...})`                |
+
+The legacy element-backed player, frame timeline, and related errors are not
+exported by `@meta-sam/video` after this migration.
+
+## Runtime and package map
+
+The package is ESM-only and side-effect-free. Importing it does not construct
+browser objects. Mounted players require Canvas 2D, Fetch for URL sources,
+WebCodecs for video decoding, and Web Audio for supported audio playback.
+Missing or unsupported audio degrades to explicit silent playback as described
+by `onAudioStatusChange` and `onAudioWarning`.
+
+Only the package root is public; deep imports are unsupported.
+
+## License
+
+The source is licensed under the SAM License. See `LICENSE` in this package or
+the repository root for the license text.

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { Video } from './video.js';
+export type { VideoCaptureSource, VideoProps, VideoRef, VideoStats } from './video.js';
+export { useMediaPlayer } from './use-media-player.js';
+export type { MediaPlayerCallbacks, MediaPlayerFrame, MediaPlayerLoadedMetadata, UseMediaPlayerOptions, } from './use-media-player.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates. All Rights Reserved.
+ */
+export { Video } from './video.js';
+export { useMediaPlayer } from './use-media-player.js';

package/dist/use-media-player.d.ts

@@ -0,0 +1,35 @@
+import { type RefObject } from 'react';
+import { type CustomRenderFunction, type IMediaPlayer, type MediaPlayerAudioError, type MediaPlayerAudioStatus, type MediaPlayerEventMap, type MediaPlayerOptions, type MediaResource } from '@meta-sam/video';
+export type MediaPlayerLoadedMetadata = MediaPlayerEventMap['loadedmetadata'];
+export type MediaPlayerFrame = MediaPlayerEventMap['frame'];
+export interface MediaPlayerCallbacks {
+    readonly onTimeChange?: (time: number) => void;
+    readonly onPlayingChange?: (playing: boolean) => void;
+    readonly onDurationChange?: (duration: number) => void;
+    readonly onLoadedMetadata?: (metadata: MediaPlayerLoadedMetadata) => void;
+    readonly onFrame?: (frame: MediaPlayerFrame) => void;
+    readonly onAudioStatusChange?: (status: MediaPlayerAudioStatus) => void;
+    readonly onAudioWarning?: (warning: MediaPlayerAudioError) => void;
+    readonly onError?: (error: Error) => void;
+    readonly onPlayerReady?: (player: IMediaPlayer) => void;
+}
+export interface UseMediaPlayerOptions extends MediaPlayerCallbacks {
+    readonly canvasRef: RefObject<HTMLCanvasElement | null>;
+    readonly src: MediaResource;
+    /** Applied when this source is first opened. Later changes do not seek it again. */
+    readonly initialSeekTime?: number;
+    readonly loop?: boolean;
+    readonly playbackRate?: number;
+    readonly volume?: number;
+    readonly muted?: boolean;
+    readonly autoPlay?: boolean;
+    readonly renderFrame?: CustomRenderFunction;
+    /** Construction-only options, read when a canvas receives its player. */
+    readonly playerOptions?: MediaPlayerOptions;
+}
+/**
+ * Owns a Canvas-only @meta-sam/video player for a caller-owned canvas.
+ *
+ * The returned ref is stable. The hook owns and disposes every player it creates.
+ */
+export declare function useMediaPlayer(options: UseMediaPlayerOptions): RefObject<IMediaPlayer | null>;

package/dist/use-media-player.js

@@ -0,0 +1,206 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates. All Rights Reserved.
+ */
+'use client';
+import { useEffect, useRef } from 'react';
+import { createMediaPlayer, } from '@meta-sam/video';
+const noSource = Symbol('no-source');
+function isCancelled(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        (error.code === 'operation_cancelled' || error.code === 'player_disposed'));
+}
+/**
+ * Owns a Canvas-only @meta-sam/video player for a caller-owned canvas.
+ *
+ * The returned ref is stable. The hook owns and disposes every player it creates.
+ */
+export function useMediaPlayer(options) {
+    const playerRef = useRef(null);
+    const ownedRef = useRef(null);
+    const optionsRef = useRef(options);
+    optionsRef.current = options;
+    useEffect(() => {
+        const report = (error) => {
+            const normalized = error instanceof Error
+                ? error
+                : new Error('The media player failed with a non-Error value.', {
+                    cause: error,
+                });
+            try {
+                optionsRef.current.onError?.(normalized);
+            }
+            catch {
+                // Error callbacks are terminal observers and must not break lifecycle cleanup.
+            }
+        };
+        const dispose = (owned) => {
+            owned.openGeneration += 1;
+            if (ownedRef.current === owned)
+                ownedRef.current = null;
+            if (playerRef.current === owned.player)
+                playerRef.current = null;
+            owned.player.dispose();
+        };
+        const canvas = optionsRef.current.canvasRef.current;
+        let owned = ownedRef.current;
+        if (owned !== null && owned.canvas !== canvas) {
+            dispose(owned);
+            owned = null;
+        }
+        if (canvas === null)
+            return;
+        if (owned === null) {
+            try {
+                const player = createMediaPlayer(canvas, optionsRef.current.playerOptions);
+                let created;
+                const renderFrame = (context) => optionsRef.current.renderFrame?.(context);
+                created = {
+                    player,
+                    canvas,
+                    renderFrame,
+                    source: noSource,
+                    openingSource: noSource,
+                    openGeneration: 0,
+                    customRendering: false,
+                    lastRenderFrame: undefined,
+                };
+                ownedRef.current = created;
+                playerRef.current = player;
+                owned = created;
+                const current = () => ownedRef.current === created;
+                player.on('timeupdate', ({ time }) => {
+                    if (current())
+                        optionsRef.current.onTimeChange?.(time);
+                });
+                player.on('play', () => {
+                    if (current())
+                        optionsRef.current.onPlayingChange?.(true);
+                });
+                player.on('pause', () => {
+                    if (current())
+                        optionsRef.current.onPlayingChange?.(false);
+                });
+                player.on('ended', () => {
+                    if (current())
+                        optionsRef.current.onPlayingChange?.(false);
+                });
+                player.on('durationchange', ({ duration }) => {
+                    if (current())
+                        optionsRef.current.onDurationChange?.(duration);
+                });
+                player.on('loadedmetadata', (metadata) => {
+                    if (current())
+                        optionsRef.current.onLoadedMetadata?.(metadata);
+                });
+                player.on('frame', (frame) => {
+                    if (current())
+                        optionsRef.current.onFrame?.(frame);
+                });
+                player.on('audiostatuschange', (status) => {
+                    if (current())
+                        optionsRef.current.onAudioStatusChange?.(status);
+                });
+                player.on('audiowarning', ({ warning }) => {
+                    if (current())
+                        optionsRef.current.onAudioWarning?.(warning);
+                });
+                player.on('error', ({ error }) => {
+                    if (!current())
+                        return;
+                    try {
+                        optionsRef.current.onError?.(error);
+                    }
+                    catch {
+                        // MediaPlayer treats error listeners as terminal observers.
+                    }
+                });
+                try {
+                    optionsRef.current.onPlayerReady?.(player);
+                }
+                catch (error) {
+                    report(error);
+                }
+            }
+            catch (error) {
+                report(error);
+                return;
+            }
+        }
+        const currentOptions = optionsRef.current;
+        const useCustomRendering = currentOptions.renderFrame !== undefined;
+        if (owned.customRendering !== useCustomRendering) {
+            owned.customRendering = useCustomRendering;
+            owned.lastRenderFrame = currentOptions.renderFrame;
+            owned.player.setCustomRender(useCustomRendering ? owned.renderFrame : null);
+        }
+        else if (useCustomRendering &&
+            owned.lastRenderFrame !== currentOptions.renderFrame) {
+            owned.lastRenderFrame = currentOptions.renderFrame;
+            void owned.player.forceRender().catch(() => undefined);
+        }
+        if (currentOptions.loop !== undefined &&
+            owned.player.loop !== currentOptions.loop) {
+            owned.player.loop = currentOptions.loop;
+        }
+        if (currentOptions.playbackRate !== undefined &&
+            owned.player.playbackRate !== currentOptions.playbackRate) {
+            owned.player.playbackRate = currentOptions.playbackRate;
+        }
+        if (currentOptions.volume !== undefined &&
+            owned.player.volume !== currentOptions.volume) {
+            owned.player.volume = currentOptions.volume;
+        }
+        if (currentOptions.muted !== undefined &&
+            owned.player.muted !== currentOptions.muted) {
+            owned.player.muted = currentOptions.muted;
+        }
+        if (!Object.is(owned.source, currentOptions.src) &&
+            !Object.is(owned.openingSource, currentOptions.src)) {
+            owned.source = noSource;
+            owned.openingSource = currentOptions.src;
+            const generation = ++owned.openGeneration;
+            const player = owned.player;
+            const source = currentOptions.src;
+            const startTime = currentOptions.initialSeekTime;
+            void Promise.resolve()
+                .then(() => player.open(source, startTime))
+                .then(() => {
+                if (ownedRef.current !== owned || generation !== owned.openGeneration) {
+                    return;
+                }
+                owned.openingSource = noSource;
+                owned.source = source;
+                if (optionsRef.current.autoPlay === true) {
+                    void Promise.resolve()
+                        .then(() => player.play())
+                        .catch(() => {
+                        // MediaPlayer reports fatal play failures through its error event.
+                    });
+                }
+            })
+                .catch((error) => {
+                if (ownedRef.current !== owned || generation !== owned.openGeneration) {
+                    return;
+                }
+                owned.openingSource = noSource;
+                owned.source = noSource;
+                if (isCancelled(error))
+                    return;
+                // MediaPlayer emits fatal open and play failures through its error event.
+            });
+        }
+    });
+    useEffect(() => () => {
+        const owned = ownedRef.current;
+        ownedRef.current = null;
+        if (playerRef.current === owned?.player)
+            playerRef.current = null;
+        if (owned !== null) {
+            owned.openGeneration += 1;
+            owned.player.dispose();
+        }
+    }, []);
+    return playerRef;
+}

package/dist/video.d.ts

@@ -0,0 +1,47 @@
+import { type CSSProperties, type CanvasHTMLAttributes } from 'react';
+import { SegmentationRenderer, type VideoFrameFit } from '@meta-sam/graphics';
+import type { VideoSegmentationResult, VideoSegmentationSnapshot } from '@meta-sam/parser';
+import { type MediaPlayerOptions, type MediaResource, type PlaybackStats, type VideoPacketMetadata, type VideoPacketTimeline } from '@meta-sam/video';
+import { type MediaPlayerCallbacks } from './use-media-player.js';
+export type VideoCaptureSource = 'composited' | 'raw';
+export type VideoStats = PlaybackStats;
+export interface VideoRef {
+    play(): Promise<void>;
+    pause(): void;
+    seek(time: number): Promise<void>;
+    seekToFrame(frameIndex: number): Promise<void>;
+    nextFrame(): Promise<void>;
+    previousFrame(): Promise<void>;
+    getFrameIndexAtTimeExact(time: number): number;
+    getTimeAtFrameIndexExact(frameIndex: number): number;
+    getPacketAtTimeExact(time: number): VideoPacketMetadata;
+    getVideoPackets(): VideoPacketTimeline;
+    setPlaybackRate(playbackRate: number): void;
+    setVolume(volume: number): void;
+    setMuted(muted: boolean): void;
+    setLoop(loop: boolean): void;
+    forceRender(): Promise<void>;
+    /** Returns a detached canvas snapshot that the caller owns. */
+    captureFrame(source?: VideoCaptureSource): HTMLCanvasElement;
+    getStats(): VideoStats;
+    resetStats(): void;
+}
+export interface VideoProps extends MediaPlayerCallbacks {
+    readonly src: MediaResource;
+    readonly result?: VideoSegmentationResult | VideoSegmentationSnapshot;
+    readonly renderer?: SegmentationRenderer;
+    readonly hiddenIds?: ReadonlySet<string> | readonly string[];
+    readonly objectFit?: VideoFrameFit;
+    readonly devicePixelRatio?: number | (() => number);
+    readonly loop?: boolean;
+    readonly playbackRate?: number;
+    readonly volume?: number;
+    readonly muted?: boolean;
+    readonly autoPlay?: boolean;
+    readonly initialSeekTime?: number;
+    readonly playerOptions?: MediaPlayerOptions;
+    readonly className?: string;
+    readonly style?: CSSProperties;
+    readonly canvasProps?: Omit<CanvasHTMLAttributes<HTMLCanvasElement>, 'children' | 'ref' | 'width' | 'height'>;
+}
+export declare const Video: import("react").ForwardRefExoticComponent<VideoProps & import("react").RefAttributes<VideoRef>>;

package/dist/video.js

@@ -0,0 +1,250 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates. All Rights Reserved.
+ */
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef, useCallback, useEffect, useImperativeHandle, useRef, useState, } from 'react';
+import { SegmentationRenderer } from '@meta-sam/graphics';
+import { getPacketAtTimeExact, } from '@meta-sam/video';
+import { useMediaPlayer, } from './use-media-player.js';
+function isExpectedRenderMiss(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        (error.code === 'frame_metadata_unavailable' ||
+            error.code === 'operation_cancelled' ||
+            error.code === 'player_disposed'));
+}
+function resolvePixelRatio(value) {
+    const ratio = typeof value === 'function' ? value() : (value ?? globalThis.devicePixelRatio ?? 1);
+    if (!Number.isFinite(ratio) || ratio <= 0) {
+        throw new TypeError('devicePixelRatio must be finite and greater than zero.');
+    }
+    return ratio;
+}
+function unavailable() {
+    throw new Error('The video player is not mounted.');
+}
+function rejectUnavailable() {
+    return Promise.reject(new Error('The video player is not mounted.'));
+}
+function runPlayerOperation(player, operation) {
+    if (player === null)
+        return rejectUnavailable();
+    try {
+        return operation(player);
+    }
+    catch (error) {
+        return Promise.reject(error);
+    }
+}
+function requirePlayer(player) {
+    return player ?? unavailable();
+}
+function captureCanvas(visibleCanvas, player, source) {
+    const canvas = visibleCanvas ?? unavailable();
+    const media = source === 'composited'
+        ? canvas
+        : (requirePlayer(player).getCurrentFrame() ??
+            (() => {
+                throw new Error('No decoded video frame is available.');
+            })());
+    const snapshot = canvas.ownerDocument.createElement('canvas');
+    snapshot.width = media.width;
+    snapshot.height = media.height;
+    const context = snapshot.getContext('2d');
+    if (context === null)
+        throw new Error('A Canvas 2D context is required.');
+    context.drawImage(media, 0, 0, media.width, media.height);
+    return snapshot;
+}
+export const Video = forwardRef(function Video(props, ref) {
+    const { src, result, renderer: suppliedRenderer, hiddenIds, objectFit, devicePixelRatio, loop, playbackRate, volume, muted, autoPlay, initialSeekTime, playerOptions, className, style, canvasProps, } = props;
+    const canvasRef = useRef(null);
+    const rendererRef = useRef(null);
+    const propsRef = useRef(props);
+    const updateGenerationRef = useRef(0);
+    const metadataRef = useRef(null);
+    const [aspectRatio, setAspectRatio] = useState();
+    propsRef.current = props;
+    const reportError = useCallback((error) => {
+        const normalized = error instanceof Error
+            ? error
+            : new Error('Video failed with a non-Error value.', { cause: error });
+        propsRef.current.onError?.(normalized);
+    }, []);
+    useEffect(() => {
+        const renderer = suppliedRenderer ?? new SegmentationRenderer();
+        rendererRef.current = renderer;
+        return () => {
+            updateGenerationRef.current += 1;
+            if (rendererRef.current === renderer)
+                rendererRef.current = null;
+            if (suppliedRenderer === undefined)
+                renderer.dispose();
+        };
+    }, [suppliedRenderer]);
+    const renderFrame = useCallback((context) => {
+        const current = propsRef.current;
+        rendererRef.current?.renderVideoFrame(context, {
+            ...(current.objectFit === undefined ? {} : { fit: current.objectFit }),
+            devicePixelRatio: () => resolvePixelRatio(current.devicePixelRatio),
+            ...(current.hiddenIds === undefined ? {} : { hiddenIds: current.hiddenIds }),
+        });
+    }, []);
+    const onLoadedMetadata = useCallback((metadata) => {
+        metadataRef.current = metadata;
+        setAspectRatio(`${metadata.width} / ${metadata.height}`);
+        propsRef.current.onLoadedMetadata?.(metadata);
+    }, []);
+    const playerRef = useMediaPlayer({
+        canvasRef,
+        src,
+        ...(initialSeekTime === undefined ? {} : { initialSeekTime }),
+        ...(loop === undefined ? {} : { loop }),
+        ...(playbackRate === undefined ? {} : { playbackRate }),
+        ...(volume === undefined ? {} : { volume }),
+        ...(muted === undefined ? {} : { muted }),
+        ...(autoPlay === undefined ? {} : { autoPlay }),
+        ...(playerOptions === undefined ? {} : { playerOptions }),
+        renderFrame,
+        onLoadedMetadata,
+        onTimeChange: (time) => propsRef.current.onTimeChange?.(time),
+        onPlayingChange: (playing) => propsRef.current.onPlayingChange?.(playing),
+        onDurationChange: (duration) => propsRef.current.onDurationChange?.(duration),
+        onFrame: (frame) => propsRef.current.onFrame?.(frame),
+        onAudioStatusChange: (status) => propsRef.current.onAudioStatusChange?.(status),
+        onAudioWarning: (warning) => propsRef.current.onAudioWarning?.(warning),
+        onError: reportError,
+        onPlayerReady: (player) => propsRef.current.onPlayerReady?.(player),
+    });
+    useEffect(() => {
+        const renderer = rendererRef.current;
+        if (renderer === null)
+            return;
+        if (result !== undefined && result.media !== 'video') {
+            reportError(new TypeError('Video accepts only video segmentation results.'));
+            return;
+        }
+        let active = true;
+        const generation = ++updateGenerationRef.current;
+        const update = result === undefined
+            ? (renderer.clear(), Promise.resolve())
+            : renderer.update(result, { reset: true });
+        void update
+            .then(async () => {
+            if (!active ||
+                generation !== updateGenerationRef.current ||
+                rendererRef.current !== renderer) {
+                return;
+            }
+            try {
+                await playerRef.current?.forceRender();
+            }
+            catch (error) {
+                if (!isExpectedRenderMiss(error))
+                    reportError(error);
+            }
+        })
+            .catch((error) => {
+            if (active &&
+                generation === updateGenerationRef.current &&
+                rendererRef.current === renderer) {
+                reportError(error);
+            }
+        });
+        return () => {
+            active = false;
+        };
+    }, [playerRef, reportError, result, suppliedRenderer]);
+    useEffect(() => {
+        const player = playerRef.current;
+        if (player === null)
+            return;
+        void player.forceRender().catch((error) => {
+            if (!isExpectedRenderMiss(error))
+                reportError(error);
+        });
+    }, [devicePixelRatio, hiddenIds, objectFit, playerRef, reportError]);
+    useEffect(() => {
+        const canvas = canvasRef.current;
+        if (canvas === null)
+            return;
+        const resize = () => {
+            try {
+                const metadata = metadataRef.current;
+                const logicalWidth = canvas.clientWidth || metadata?.width || 0;
+                const logicalHeight = canvas.clientHeight || metadata?.height || 0;
+                if (logicalWidth <= 0 || logicalHeight <= 0)
+                    return;
+                const ratio = resolvePixelRatio(propsRef.current.devicePixelRatio);
+                const width = Math.round(logicalWidth * ratio);
+                const height = Math.round(logicalHeight * ratio);
+                if (canvas.width === width && canvas.height === height)
+                    return;
+                canvas.width = width;
+                canvas.height = height;
+                void playerRef.current?.forceRender().catch((error) => {
+                    if (!isExpectedRenderMiss(error))
+                        reportError(error);
+                });
+            }
+            catch (error) {
+                reportError(error);
+            }
+        };
+        resize();
+        const Observer = globalThis.ResizeObserver;
+        if (Observer === undefined)
+            return;
+        const observer = new Observer(resize);
+        observer.observe(canvas);
+        return () => observer.disconnect();
+    }, [aspectRatio, devicePixelRatio, playerRef, reportError]);
+    useImperativeHandle(ref, () => ({
+        play: () => runPlayerOperation(playerRef.current, (player) => player.play()),
+        pause: () => requirePlayer(playerRef.current).pause(),
+        seek: (time) => runPlayerOperation(playerRef.current, (player) => player.seek(time)),
+        seekToFrame: (frameIndex) => runPlayerOperation(playerRef.current, (player) => player.seekToFrame(frameIndex)),
+        nextFrame: () => runPlayerOperation(playerRef.current, (player) => player.nextFrame()),
+        previousFrame: () => runPlayerOperation(playerRef.current, (player) => player.previousFrame()),
+        getFrameIndexAtTimeExact: (time) => requirePlayer(playerRef.current).getFrameIndexAtTimeExact(time),
+        getTimeAtFrameIndexExact: (frameIndex) => requirePlayer(playerRef.current).getTimeAtFrameIndexExact(frameIndex),
+        getPacketAtTimeExact: (time) => {
+            const player = requirePlayer(playerRef.current);
+            return getPacketAtTimeExact(player.getVideoPackets(), time);
+        },
+        getVideoPackets: () => requirePlayer(playerRef.current).getVideoPackets(),
+        setPlaybackRate: (value) => {
+            requirePlayer(playerRef.current).playbackRate = value;
+        },
+        setVolume: (value) => {
+            requirePlayer(playerRef.current).volume = value;
+        },
+        setMuted: (value) => {
+            requirePlayer(playerRef.current).muted = value;
+        },
+        setLoop: (value) => {
+            requirePlayer(playerRef.current).loop = value;
+        },
+        forceRender: () => runPlayerOperation(playerRef.current, (player) => player.forceRender()),
+        captureFrame: (source = 'composited') => captureCanvas(canvasRef.current, playerRef.current, source),
+        getStats: () => requirePlayer(playerRef.current).getStats(),
+        resetStats: () => requirePlayer(playerRef.current).resetStats(),
+    }), [playerRef]);
+    const rootStyle = {
+        position: 'relative',
+        display: 'inline-block',
+        overflow: 'hidden',
+        width: '100%',
+        ...(aspectRatio === undefined ? {} : { aspectRatio }),
+        ...style,
+    };
+    const canvasStyle = {
+        display: 'block',
+        width: '100%',
+        height: '100%',
+        ...canvasProps?.style,
+    };
+    return (_jsx("span", { className: className, style: rootStyle, children: _jsx("canvas", { ...canvasProps, ref: canvasRef, style: canvasStyle }) }));
+});

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@meta-sam/react",
+  "version": "0.1.5",
+  "description": "Canvas-only React video player for SAM 3 overlays",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://github.com/meta-models/meta-sam#readme",
+  "bugs": {
+    "url": "https://github.com/meta-models/meta-sam/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/meta-models/meta-sam.git",
+    "directory": "typescript/packages/react"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "browser": "./dist/index.js",
+  "engines": {
+    "node": "^20.17.0 || >=22.9.0"
+  },
+  "dependencies": {
+    "@meta-sam/graphics": "0.1.5",
+    "@meta-sam/parser": "0.0.8",
+    "@meta-sam/video": "0.1.2"
+  },
+  "peerDependencies": {
+    "react": ">=18.2 <20",
+    "react-dom": ">=18.2 <20"
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.12",
+    "@types/react-dom": "^19.1.9",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "prepack": "tsc -b --force",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}