react-native-video-provider 0.2.2 → 0.2.4

package/lib/typescript/src/components/VideoPlayer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VideoPlayer.d.ts","sourceRoot":"","sources":["../../../../src/components/VideoPlayer.tsx"],"names":[],"mappings":"AACA,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAEhE,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,mBAAgB,CAAC;AAI/E,MAAM,WAAW,gBAAiB,SAAQ,SAAS;IACjD,MAAM,EAAE,WAAW,CAAC;IACpB,oBAAoB;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB;;;;OAIG;IACH,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,eAAe,CAAC;CACzC;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,EAC1B,MAAM,EACN,QAAe,EACf,SAAS,EACT,QAAe,EACf,UAAU,EACV,WAAW,EACX,qBAAqB,EACrB,KAAK,EACL,GAAG,IAAI,EACR,EAAE,gBAAgB,+BAuClB"}
+{"version":3,"file":"VideoPlayer.d.ts","sourceRoot":"","sources":["../../../../src/components/VideoPlayer.tsx"],"names":[],"mappings":"AACA,OAAO,EAA8B,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAsB,CAAC;AAGpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAiB,CAAC;AACrD,OAAO,KAAK,EACV,eAAe,EACf,UAAU,EACV,UAAU,EACV,WAAW,EACZ,MAAM,mBAAgB,CAAC;AAIxB,MAAM,WAAW,gBAAiB,SAAQ,SAAS;IACjD,MAAM,EAAE,WAAW,CAAC;IACpB,oBAAoB;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,iDAAiD;IACjD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,qBAAqB;IACrB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,eAAe,CAAC;IACxC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,+DAA+D;IAC/D,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,aAAa,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC;IACzD,gDAAgD;IAChD,WAAW,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,IAAI,CAAC;IAC3C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;CACvC;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,2GAoGvB,CAAC"}

package/lib/typescript/src/index.d.ts

@@ -3,6 +3,7 @@ export { useVideoManager } from './provider/VideoContext.js';
 export { VideoManager, FULLSCREEN_SURFACE_ID, FLOATING_SURFACE_ID, } from './core/VideoManager.js';
 export { VideoSurface, type VideoSurfaceProps, } from './components/VideoSurface.js';
 export { VideoPlayer, type VideoPlayerProps } from './components/VideoPlayer.js';
+export { VideoFeed, feedSurfaceId, type VideoFeedProps, type VideoFeedRenderInfo, } from './components/VideoFeed.js';
 export { FullscreenPlayer } from './components/FullscreenPlayer.js';
 export { FloatingPlayer, type FloatingPlayerProps, } from './components/FloatingPlayer.js';
 export { MiniPlayer, type MiniPlayerProps } from './components/MiniPlayer.js';

package/lib/typescript/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,KAAK,kBAAkB,GACxB,MAAM,6BAA0B,CAAC;AAClC,OAAO,EAAE,eAAe,EAAE,MAAM,4BAAyB,CAAC;AAC1D,OAAO,EACL,YAAY,EACZ,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,wBAAqB,CAAC;AAE7B,OAAO,EACL,YAAY,EACZ,KAAK,iBAAiB,GACvB,MAAM,8BAA2B,CAAC;AACnC,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,6BAA0B,CAAC;AAC9E,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAA+B,CAAC;AACjE,OAAO,EACL,cAAc,EACd,KAAK,mBAAmB,GACzB,MAAM,gCAA6B,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,4BAAyB,CAAC;AAC3E,OAAO,EACL,aAAa,EACb,KAAK,kBAAkB,GACxB,MAAM,+BAA4B,CAAC;AACpC,OAAO,EACL,cAAc,EACd,KAAK,mBAAmB,GACzB,MAAM,gCAA6B,CAAC;AAErC,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAkB,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAqB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,0BAAuB,CAAC;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAgB,CAAC;AACxC,OAAO,EACL,cAAc,EACd,KAAK,kBAAkB,GACxB,MAAM,2BAAwB,CAAC;AAEhC,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAoB,CAAC;AAEhD,YAAY,EACV,WAAW,EACX,UAAU,EACV,eAAe,EACf,UAAU,EACV,cAAc,EACd,UAAU,EACV,UAAU,EACV,gBAAgB,EAChB,mBAAmB,EACnB,aAAa,EACb,cAAc,GACf,MAAM,kBAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,KAAK,kBAAkB,GACxB,MAAM,6BAA0B,CAAC;AAClC,OAAO,EAAE,eAAe,EAAE,MAAM,4BAAyB,CAAC;AAC1D,OAAO,EACL,YAAY,EACZ,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,wBAAqB,CAAC;AAE7B,OAAO,EACL,YAAY,EACZ,KAAK,iBAAiB,GACvB,MAAM,8BAA2B,CAAC;AACnC,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,6BAA0B,CAAC;AAC9E,OAAO,EACL,SAAS,EACT,aAAa,EACb,KAAK,cAAc,EACnB,KAAK,mBAAmB,GACzB,MAAM,2BAAwB,CAAC;AAChC,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAA+B,CAAC;AACjE,OAAO,EACL,cAAc,EACd,KAAK,mBAAmB,GACzB,MAAM,gCAA6B,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,4BAAyB,CAAC;AAC3E,OAAO,EACL,aAAa,EACb,KAAK,kBAAkB,GACxB,MAAM,+BAA4B,CAAC;AACpC,OAAO,EACL,cAAc,EACd,KAAK,mBAAmB,GACzB,MAAM,gCAA6B,CAAC;AAErC,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAkB,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAqB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,0BAAuB,CAAC;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAgB,CAAC;AACxC,OAAO,EACL,cAAc,EACd,KAAK,kBAAkB,GACxB,MAAM,2BAAwB,CAAC;AAEhC,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAoB,CAAC;AAEhD,YAAY,EACV,WAAW,EACX,UAAU,EACV,eAAe,EACf,UAAU,EACV,cAAc,EACd,UAAU,EACV,UAAU,EACV,gBAAgB,EAChB,mBAAmB,EACnB,aAAa,EACb,cAAc,GACf,MAAM,kBAAS,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-video-provider",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Singleton-engine video library for React Native (one native player, many surfaces)",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",
@@ -18,6 +18,7 @@
     "android",
     "ios",
     "cpp",
+    "scripts/postinstall.js",
     "*.podspec",
     "react-native.config.js",
     "!ios/build",
@@ -35,6 +36,7 @@
     "example": "yarn workspace react-native-video-provider-example",
     "clean": "del-cli android/build example/android/build example/android/app/build example/ios/build lib",
     "prepare": "bob build",
+    "postinstall": "node scripts/postinstall.js",
     "typecheck": "tsc",
     "test": "jest",
     "lint": "eslint \"**/*.{js,ts,tsx}\""
@@ -46,14 +48,14 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/grdp99/react-native-au-video.git"
+    "url": "git+https://github.com/gurdeep99/react-native-au-video.git"
   },
   "author": "Gurdeep Singh <grdp99@gmail.com> (https://gurdeep.net)",
   "license": "MIT",
   "bugs": {
-    "url": "https://github.com/grdp99/react-native-au-video/issues"
+    "url": "https://github.com/gurdeep99/react-native-au-video/issues"
   },
-  "homepage": "https://github.com/grdp99/react-native-au-video#readme",
+  "homepage": "https://github.com/gurdeep99/react-native-au-video#readme",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
   },

package/scripts/postinstall.js

@@ -0,0 +1,44 @@
+'use strict';
+
+/**
+ * Prints a banner after install. Wrapped so it can NEVER fail a consumer's
+ * `npm install` — any error is swallowed and the process always exits 0.
+ * Skipped in CI and non-interactive shells to avoid polluting build logs.
+ */
+
+const BANNER = `
+                                                                                       ++
+                       +++                              +++                      +++++++++++    ++
+      ++++++++++++++  ++++++++++         ++++++++++++++ +++                    +++++++ ++      +++
+      ++    +++   +++ ++++++++++++       +++      +++++ ++++    +++++++   ++++ +++++++ ++      +++
+      ++    +++   +++ ++++     +++       +++++++++++++  ++++ +++++ ++++ +++++  +++++++ ++      +++++++++++
+      +++   +++   +++ ++++    ++++       +++    +++++++ +++++++    +++++++++    +++++++++      ++++    ++++
+      ++++  +++   +++ ++++++++++         ++++++     +++ ++++++    +++++  +++           ++      +++      +++
+      +++   ++    +++ ++++  +++          +++  ++++++++  ++++     ++++   +++      ++++ +++      +++      +++
+                      ++++   ++++                       ++++    +++     ++      +++++ ++       +++     ++++
+        +++++++               ++++                                      ++       ++++++         ++++++++++
+     ++++ ++++        +         +++                       ++++        +                        +++++++++++
+   +++   +++        ++++        +++++        ++++        +++        +++        ++++       ++++        +++
+   ++++++++         ++           ++                       ++                             +++ +        ++
+`;
+
+try {
+  const quiet = process.env.CI || process.env.npm_config_loglevel === 'silent';
+  if (!quiet && process.stdout && process.stdout.isTTY) {
+    const cyan = '\x1b[36m';
+    const dim = '\x1b[2m';
+    const reset = '\x1b[0m';
+    process.stdout.write(cyan + BANNER + reset + '\n');
+    process.stdout.write(
+      dim +
+        '  react-native-video-provider — one native player, many surfaces.\n' +
+        '  Docs: https://github.com/gurdeep99/react-native-video-provider#readme\n' +
+        reset +
+        '\n'
+    );
+  }
+} catch {
+  // Never break an install over a banner.
+}
+
+process.exit(0);

package/src/components/VideoControls.tsx

@@ -37,13 +37,19 @@ export function VideoControls({
   onClose,
 }: VideoControlsProps) {
   const manager = useVideoManager();
+  const status = usePlayback((s) => s.status);
   const playing = usePlayback((s) => s.playing);
   const buffering = usePlayback((s) => s.buffering);
+  const loading = usePlayback((s) => s.loading);
   const position = usePlayback((s) => s.position);
   const duration = usePlayback((s) => s.duration);
   const muted = usePlayback((s) => s.muted);
   const fullscreen = usePlayback((s) => s.fullscreen);
 
+  // No known duration once loaded — a live stream or a video with no fixed
+  // end. There's nothing to seek, so hide the seek bar entirely.
+  const live = status !== 'idle' && !loading && duration <= 0;
+
   const [visible, setVisible] = useState(true);
   const hideTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
   const trackWidth = useRef(0);
@@ -85,6 +91,34 @@ export function VideoControls({
 
   const progress = duration > 0 ? Math.min(position / duration, 1) : 0;
 
+  const muteButton = (
+    <Pressable
+      style={styles.button}
+      onPress={() => (muted ? manager.unmute() : manager.mute())}
+      hitSlop={8}
+    >
+      {muted ? (
+        <SvgIcons icon="muteUnmute" size={18} fill="#fff" />
+      ) : (
+        <SvgIcons icon="muteUnmute" type="mute" size={18} fill="#fff" />
+      )}
+    </Pressable>
+  );
+
+  const fullscreenButton = showFullscreenButton ? (
+    <Pressable
+      style={styles.button}
+      onPress={() => manager.toggleFullscreen()}
+      hitSlop={8}
+    >
+      {fullscreen ? (
+        <SvgIcons icon="fullScreen" size={18} fill="#fff" />
+      ) : (
+        <SvgIcons icon="fullScreen" type="full" size={18} fill="#fff" />
+      )}
+    </Pressable>
+  ) : null;
+
   return (
     <View style={StyleSheet.absoluteFill} pointerEvents="box-none">
       <GestureOverlay
@@ -102,22 +136,7 @@ export function VideoControls({
             ) : (
               <View />
             )}
-            <Pressable
-              style={styles.button}
-              onPress={() => (muted ? manager.unmute() : manager.mute())}
-              hitSlop={8}
-            >
-              {muted ? (
-                <SvgIcons icon="muteUnmute" type="mute" size={18} fill="#fff" />
-              ) : (
-                <SvgIcons
-                  icon="muteUnmute"
-                  type="unmute"
-                  size={18}
-                  fill="#fff"
-                />
-              )}
-            </Pressable>
+            {!live ? muteButton : <View />}
           </View>
 
           <Pressable
@@ -138,36 +157,29 @@ export function VideoControls({
           </Pressable>
 
           <View style={styles.bottomRow}>
-            <Text style={styles.time}>{formatTime(position)}</Text>
-            <Pressable
-              style={styles.track}
-              onLayout={onTrackLayout}
-              onPress={onTrackPress}
-            >
-              <View style={styles.trackBg} />
-              <View
-                style={[styles.trackFill, { width: `${progress * 100}%` }]}
-              />
-            </Pressable>
-            <Text style={styles.time}>{formatTime(duration)}</Text>
-            {showFullscreenButton ? (
-              <Pressable
-                style={styles.button}
-                onPress={() => manager.toggleFullscreen()}
-                hitSlop={8}
-              >
-                {fullscreen ? (
-                  <SvgIcons icon="fullScreen" size={18} fill="#fff" />
-                ) : (
-                  <SvgIcons
-                    icon="fullScreen"
-                    type="full"
-                    size={18}
-                    fill="#fff"
+            {live ? (
+              <>
+                {muteButton}
+                <View style={styles.spacer} />
+                {fullscreenButton}
+              </>
+            ) : (
+              <>
+                <Text style={styles.time}>{formatTime(position)}</Text>
+                <Pressable
+                  style={styles.track}
+                  onLayout={onTrackLayout}
+                  onPress={onTrackPress}
+                >
+                  <View style={styles.trackBg} />
+                  <View
+                    style={[styles.trackFill, { width: `${progress * 100}%` }]}
                   />
-                )}
-              </Pressable>
-            ) : null}
+                </Pressable>
+                <Text style={styles.time}>{formatTime(duration)}</Text>
+                {fullscreenButton}
+              </>
+            )}
           </View>
         </View>
       ) : null}
@@ -214,6 +226,9 @@ const styles = StyleSheet.create({
     height: 24,
     justifyContent: 'center',
   },
+  spacer: {
+    flex: 1,
+  },
   trackBg: {
     position: 'absolute',
     left: 0,

package/src/components/VideoFeed.tsx

@@ -0,0 +1,201 @@
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react';
+import {
+  FlatList,
+  StyleSheet,
+  useWindowDimensions,
+  View,
+  type FlatListProps,
+} from 'react-native';
+import { useVideoManager } from '../provider/VideoContext';
+import type { ResizeMode, VideoSource } from '../types/video';
+import { VideoSurface } from './VideoSurface';
+
+/** Surface id a feed item registers under. */
+export const feedSurfaceId = (id: string) => `feed:${id}`;
+
+/** Minimal shape of a FlatList viewability token (avoids RN type-name drift). */
+interface FeedViewToken {
+  item: unknown;
+  index: number | null | undefined;
+  isViewable: boolean;
+}
+
+export interface VideoFeedRenderInfo<T> {
+  item: T;
+  index: number;
+  /** True when this item is the one currently playing. */
+  focused: boolean;
+}
+
+export interface VideoFeedProps<T extends VideoSource> extends Omit<
+  FlatListProps<T>,
+  | 'data'
+  | 'renderItem'
+  | 'keyExtractor'
+  | 'onViewableItemsChanged'
+  | 'viewabilityConfig'
+  | 'getItemLayout'
+> {
+  /** The videos. Each needs a stable `id` (used for the surface + handoff). */
+  data: T[];
+  /** Height of each item. Default: the window height (a full-screen reels feed). */
+  itemHeight?: number;
+  resizeMode?: ResizeMode;
+  /** Start muted. Default `true` (autoplay policies + typical feed UX). */
+  muted?: boolean;
+  /** Loop the focused video. Default `true`. */
+  repeat?: boolean;
+  /** Percent of an item that must be visible to become focused. Default 80. */
+  visibilityThreshold?: number;
+  /** Overlay above each item — captions, like button, a tap-to-pause layer, … */
+  renderOverlay?: (info: VideoFeedRenderInfo<T>) => ReactNode;
+  /** Called when the focused item changes (null when none is visible). */
+  onFocusChange?: (item: T | null, index: number) => void;
+  /** Pause playback when the feed unmounts. Default `true`. */
+  pauseOnUnmount?: boolean;
+}
+
+/**
+ * A single-engine video feed: render many videos in a scrollable list, but
+ * only the one scrolled into focus plays — the rest are stopped. There is
+ * still exactly ONE native player; scrolling hands it off to the focused
+ * item's surface, so memory and CPU stay flat no matter how long the feed.
+ *
+ * Each item is a plain `VideoSurface` (never a `VideoPlayer`, which would
+ * fight for the engine on mount). Focus is driven centrally from FlatList
+ * viewability.
+ *
+ * ```tsx
+ * <VideoFeed
+ *   data={videos} // [{ id, uri, title? }, …]
+ *   renderOverlay={({ item, focused }) => <Caption title={item.title} />}
+ * />
+ * ```
+ */
+export function VideoFeed<T extends VideoSource>({
+  data,
+  itemHeight,
+  resizeMode,
+  muted = true,
+  repeat = true,
+  visibilityThreshold = 80,
+  renderOverlay,
+  onFocusChange,
+  pauseOnUnmount = true,
+  ...rest
+}: VideoFeedProps<T>) {
+  const manager = useVideoManager();
+  const { height: windowHeight } = useWindowDimensions();
+  const height = itemHeight ?? windowHeight;
+  const [focusedId, setFocusedId] = useState<string | null>(null);
+
+  // Global engine settings — apply to whatever is currently playing.
+  useEffect(() => {
+    if (muted) {
+      manager.mute();
+    } else {
+      manager.unmute();
+    }
+  }, [manager, muted]);
+
+  useEffect(() => {
+    manager.setRepeat(repeat);
+  }, [manager, repeat]);
+
+  useEffect(() => {
+    if (resizeMode) {
+      manager.setResizeMode(resizeMode);
+    }
+  }, [manager, resizeMode]);
+
+  useEffect(() => {
+    return () => {
+      if (pauseOnUnmount) {
+        manager.pause();
+      }
+    };
+  }, [manager, pauseOnUnmount]);
+
+  const focus = useCallback(
+    (item: T | null, index: number) => {
+      setFocusedId(item?.id ?? null);
+      if (item) {
+        // Same-id handoff aware: re-focusing the same video never reloads.
+        // A different id replaces the source, which stops the previous one —
+        // so only the focused video ever plays.
+        manager.setSource(item, {
+          autoplay: true,
+          surfaceId: feedSurfaceId(item.id),
+        });
+      }
+      onFocusChange?.(item, index);
+    },
+    [manager, onFocusChange]
+  );
+
+  // FlatList forbids changing these on the fly, so keep them stable and read
+  // the latest `focus`/`data` through a ref.
+  const latest = useRef({ focus, data });
+  latest.current = { focus, data };
+
+  const viewabilityConfig = useRef({
+    itemVisiblePercentThreshold: visibilityThreshold,
+    minimumViewTime: 100,
+  }).current;
+
+  const onViewableItemsChanged = useRef(
+    ({ viewableItems }: { viewableItems: FeedViewToken[] }) => {
+      const focusedToken = viewableItems.find((v) => v.isViewable);
+      if (focusedToken) {
+        latest.current.focus(focusedToken.item as T, focusedToken.index ?? 0);
+      }
+    }
+  ).current;
+
+  const renderItem = useCallback(
+    ({ item, index }: { item: T; index: number }) => (
+      <View style={[styles.item, { height }]}>
+        <VideoSurface
+          surfaceId={feedSurfaceId(item.id)}
+          style={StyleSheet.absoluteFill}
+        />
+        {renderOverlay?.({ item, index, focused: item.id === focusedId })}
+      </View>
+    ),
+    [height, renderOverlay, focusedId]
+  );
+
+  return (
+    <FlatList
+      data={data}
+      keyExtractor={(item) => item.id}
+      renderItem={renderItem}
+      onViewableItemsChanged={onViewableItemsChanged}
+      viewabilityConfig={viewabilityConfig}
+      getItemLayout={(_, index) => ({
+        length: height,
+        offset: height * index,
+        index,
+      })}
+      showsVerticalScrollIndicator={false}
+      snapToInterval={height}
+      snapToAlignment="start"
+      decelerationRate="fast"
+      {...rest}
+    />
+  );
+}
+
+const styles = StyleSheet.create({
+  item: {
+    width: '100%',
+    backgroundColor: '#000',
+    overflow: 'hidden',
+  },
+});

package/src/components/VideoPlayer.tsx

@@ -1,7 +1,15 @@
-import { useEffect } from 'react';
-import { StyleSheet, View, type ViewProps } from 'react-native';
+import { forwardRef, useEffect, useImperativeHandle } from 'react';
+import { AppState, StyleSheet, View, type ViewProps } from 'react-native';
+import { VideoManager } from '../core/VideoManager';
 import { useVideoManager } from '../provider/VideoContext';
-import type { OrientationLock, ResizeMode, VideoSource } from '../types/video';
+import { useVideoEvents } from '../hooks/useVideoEvents';
+import type { VideoEventMap } from '../types/events';
+import type {
+  OrientationLock,
+  ResizeMode,
+  VideoError,
+  VideoSource,
+} from '../types/video';
 import { VideoControls } from './VideoControls';
 import { VideoSurface } from './VideoSurface';
 
@@ -18,6 +26,10 @@ export interface VideoPlayerProps extends ViewProps {
   /** Show built-in controls. Default true. */
   controls?: boolean;
   resizeMode?: ResizeMode;
+  /** Loop playback when it ends. Default false. */
+  repeat?: boolean;
+  /** Default false. */
+  muted?: boolean;
   /**
    * Force the screen into this orientation while the player is mounted:
    * `'landscape'`, `'inverted-landscape'`, `'portrait'` or
@@ -31,6 +43,18 @@ export interface VideoPlayerProps extends ViewProps {
    * when it closes, so the rest of the app is unaffected.
    */
   fullscreenOrientation?: OrientationLock;
+  /**
+   * Pause this player when it loses focus — i.e. the app goes to the
+   * background while this player's surface is the one currently playing.
+   * Default `true`. Set `false` to keep playing (e.g. background audio).
+   * Only the focused player acts, so a video attached elsewhere is untouched.
+   */
+  pauseOnFocusLost?: boolean;
+  /** Fires once metadata (duration, dimensions) is available. */
+  onLoadComplete?: (info: VideoEventMap['onLoad']) => void;
+  /** Fires whenever buffering starts or stops. */
+  onBuffering?: (buffering: boolean) => void;
+  onError?: (error: VideoError) => void;
 }
 
 /**
@@ -41,57 +65,114 @@ export interface VideoPlayerProps extends ViewProps {
  * ```tsx
  * <VideoPlayer source={{ id: '123', uri }} style={{ aspectRatio: 16 / 9 }} />
  * ```
+ *
+ * `ref` exposes the underlying `VideoManager` for imperative control
+ * (`ref.current.play()`, `.seek()`, …) — the same instance `useVideo()`
+ * returns elsewhere in the app.
  */
-export function VideoPlayer({
-  source,
-  autoplay = true,
-  surfaceId,
-  controls = true,
-  resizeMode,
-  orientation,
-  fullscreenOrientation,
-  style,
-  ...rest
-}: VideoPlayerProps) {
-  const manager = useVideoManager();
-  const id = surfaceId ?? `player:${source.id}`;
+export const VideoPlayer = forwardRef<VideoManager, VideoPlayerProps>(
+  (
+    {
+      source,
+      autoplay = true,
+      surfaceId,
+      controls = true,
+      resizeMode,
+      repeat,
+      muted,
+      orientation,
+      fullscreenOrientation,
+      pauseOnFocusLost = true,
+      onLoadComplete,
+      onBuffering,
+      onError,
+      style,
+      ...rest
+    },
+    ref
+  ) => {
+    const manager = useVideoManager();
+    const id = surfaceId ?? `player:${source.id}`;
 
-  useEffect(() => {
-    manager.setSource(source, { autoplay, surfaceId: id });
-    // Attach on mount / when the video identity changes. Other source
-    // fields (title, headers) don't retrigger: identity is source.id.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [manager, source.id, id]);
+    useImperativeHandle(ref, () => manager, [manager]);
 
-  useEffect(() => {
-    if (resizeMode) {
-      manager.setResizeMode(resizeMode);
-    }
-  }, [manager, resizeMode]);
+    useEffect(() => {
+      manager.setSource(source, { autoplay, surfaceId: id });
+      // Attach on mount / when the video identity changes. Other source
+      // fields (title, headers) don't retrigger: identity is source.id.
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [manager, source.id, id]);
 
-  useEffect(() => {
-    if (!orientation || orientation === 'auto') {
-      return;
-    }
-    manager.setOrientation(orientation);
-    return () => manager.setOrientation('auto');
-  }, [manager, orientation]);
+    useEffect(() => {
+      if (resizeMode) {
+        manager.setResizeMode(resizeMode);
+      }
+    }, [manager, resizeMode]);
 
-  useEffect(() => {
-    if (!fullscreenOrientation) {
-      return;
-    }
-    manager.setFullscreenOrientation(fullscreenOrientation);
-    return () => manager.setFullscreenOrientation(null);
-  }, [manager, fullscreenOrientation]);
+    useEffect(() => {
+      if (repeat === undefined) {
+        return;
+      }
+      manager.setRepeat(repeat);
+    }, [manager, repeat]);
 
-  return (
-    <View style={[styles.container, style]} {...rest}>
-      <VideoSurface surfaceId={id} style={styles.surface} />
-      {controls ? <VideoControls /> : null}
-    </View>
-  );
-}
+    useEffect(() => {
+      if (muted === undefined) {
+        return;
+      }
+      if (muted) {
+        manager.mute();
+      } else {
+        manager.unmute();
+      }
+    }, [manager, muted]);
+
+    useEffect(() => {
+      if (!orientation || orientation === 'auto') {
+        return;
+      }
+      manager.setOrientation(orientation);
+      return () => manager.setOrientation('auto');
+    }, [manager, orientation]);
+
+    useEffect(() => {
+      if (!fullscreenOrientation) {
+        return;
+      }
+      manager.setFullscreenOrientation(fullscreenOrientation);
+      return () => manager.setFullscreenOrientation(null);
+    }, [manager, fullscreenOrientation]);
+
+    useEffect(() => {
+      if (!pauseOnFocusLost) {
+        return;
+      }
+      const sub = AppState.addEventListener('change', (next) => {
+        // Only the player currently owning the engine reacts, so a video
+        // attached to another surface keeps playing untouched.
+        if (next !== 'active' && manager.store.getState().surfaceId === id) {
+          manager.pause();
+        }
+      });
+      return () => sub.remove();
+    }, [manager, id, pauseOnFocusLost]);
+
+    useVideoEvents({
+      onLoad: onLoadComplete,
+      onBuffer: (e) => onBuffering?.(e.buffering),
+      onError,
+    });
+
+    return (
+      <View style={[styles.container, style]} {...rest}>
+        <VideoSurface surfaceId={id} style={styles.surface} />
+        {controls ? <VideoControls /> : null}
+      </View>
+    );
+  }
+);
+
+VideoPlayer.displayName = 'VideoPlayer';
 
 const styles = StyleSheet.create({
   container: {

package/src/index.ts

@@ -14,6 +14,12 @@ export {
   type VideoSurfaceProps,
 } from './components/VideoSurface';
 export { VideoPlayer, type VideoPlayerProps } from './components/VideoPlayer';
+export {
+  VideoFeed,
+  feedSurfaceId,
+  type VideoFeedProps,
+  type VideoFeedRenderInfo,
+} from './components/VideoFeed';
 export { FullscreenPlayer } from './components/FullscreenPlayer';
 export {
   FloatingPlayer,