react-native-video-provider 0.2.3 → 0.2.5

package/AuVideo.podspec

@@ -11,7 +11,7 @@ Pod::Spec.new do |s|
   s.authors      = package["author"]
 
   s.platforms    = { :ios => min_ios_version_supported }
-  s.source       = { :git => "https://github.com/grdp99/react-native-au-video.git", :tag => "#{s.version}" }
+  s.source       = { :git => "https://github.com/gurdeep99/react-native-au-video.git", :tag => "#{s.version}" }
 
   s.source_files = "ios/**/*.{h,m,mm,swift,cpp}"
   s.private_header_files = "ios/**/*.h"

package/README.md

@@ -18,8 +18,14 @@ Feed ──▶ Detail ──▶ Fullscreen (rotation unlocked) ──▶ Floatin
   navigation, tab switches, unmounts, Fast Refresh
 - 🔁 **Same-video handoff** — `setSource` with the same `id` is a no-op for
   the engine; the player just re-parents to the new surface
+- 📱 **Single-engine feed** — `VideoFeed`, a TikTok/Reels-style list where
+  only the scrolled-into-focus video plays, on one player, flat memory
 - 📺 **Fullscreen** — built-in host that unlocks rotation while visible and
   restores the previous orientation lock on exit
+- 🧭 **Orientation control** — force portrait/landscape (+ inverted) per
+  player, scoped to fullscreen, or as a standing lock
+- ⏸️ **Focus-aware** — auto-pause on app background and on screen navigation
+  (React Navigation's `useIsFocused()`)
 - 🎈 **Floating player** — built-in draggable in-app window
 - 🖼 **Picture in Picture** — Android + iOS
 - ⚡ **New Architecture native** — TurboModule + Fabric, typed end to end
@@ -31,11 +37,15 @@ See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full design and
 ## Installation
 
 ```sh
-npm install react-native-video-provider
+npm install react-native-video-provider react-native-svg
 cd ios && pod install
 ```
 
-Requires React Native 0.80+ with the New Architecture enabled.
+`react-native-svg` is a peer dependency (used by the built-in control icons).
+
+Requires the New Architecture. Works on React Native **0.79+** — the
+TurboModule spec uses direct codegen-type imports so it parses on 0.79's
+codegen as well as 0.80+.
 
 ## Quick start
 
@@ -131,7 +141,66 @@ player.attach('feed');     // render here
 ```
 
 `<VideoPlayer>` is the convenience wrapper that does `setSource` + `attach` +
-optional controls in one component.
+optional controls in one component. Handy props:
+
+```tsx
+<VideoPlayer
+  source={video}
+  autoplay muted repeat          // playback flags
+  resizeMode="contain"           // contain | cover | stretch
+  controls                       // built-in chrome (SVG icons)
+  onLoadComplete={(m) => {}}     // duration/dimensions ready
+  onBuffering={(b) => {}}
+  onError={(e) => {}}
+  ref={playerRef}                // → the VideoManager (playerRef.current.seek(…))
+/>
+```
+
+For a live stream (no known duration), the built-in controls automatically
+hide the seek bar and show just mute + fullscreen.
+
+## Video feed (single engine, only the focused one plays)
+
+`<VideoFeed>` is a TikTok/Reels-style vertical feed. It renders many videos in
+a FlatList but plays **only the one scrolled into focus** — on the same single
+engine, so memory and CPU stay flat no matter how long the feed. Each item is
+just a surface; scrolling hands the one player off to the focused item.
+
+```tsx
+import { VideoFeed } from 'react-native-video-provider';
+
+<VideoFeed
+  data={videos} // [{ id, uri, title? }, …] — each needs a stable id
+  renderOverlay={({ item, focused }) => (
+    <Caption title={item.title} paused={!focused} />
+  )}
+/>
+```
+
+Any extra `FlatList` prop passes through (`onEndReached` for infinite scroll,
+`ListHeaderComponent`, …).
+
+## Pausing on focus loss
+
+Both `<VideoPlayer>` and `<VideoFeed>` pause automatically when the **app is
+backgrounded** (opt out with `pauseOnFocusLost={false}` for background audio).
+
+For **screen navigation** (navigating to another screen while the app stays
+foregrounded), pass your navigation library's focus flag — React Navigation
+keeps screens mounted, so there is no other reliable signal:
+
+```tsx
+import { useIsFocused } from '@react-navigation/native';
+
+function Screen() {
+  const isFocused = useIsFocused();
+  return <VideoPlayer source={video} isFocused={isFocused} />;
+  // VideoFeed takes the same prop.
+}
+```
+
+`false` pauses; returning to `true` resumes (reclaiming the engine if another
+video took it while you were away).
 
 ## State & events
 

package/android/build.gradle

@@ -57,3 +57,28 @@ dependencies {
   implementation "androidx.media3:media3-ui:${media3Version}"
   implementation "androidx.core:core-ktx:1.13.1"
 }
+
+// Print the package banner while the app compiles. Best-effort and fully
+// guarded — a missing node binary or any failure never breaks the build.
+tasks.register("auVideoBanner") {
+  doLast {
+    try {
+      def script = new File(projectDir, "../scripts/postinstall.js")
+      if (script.exists()) {
+        def banner = providers.exec {
+          commandLine "node", script.absolutePath, "--force"
+        }.standardOutput.asText.get()
+        logger.lifecycle(banner.trim())
+      }
+    } catch (Exception e) {
+      // Never fail the build over a banner (e.g. node not on PATH).
+      logger.info("auVideoBanner skipped: ${e.message}")
+    }
+  }
+}
+
+afterEvaluate {
+  tasks.matching { it.name == "preBuild" }.configureEach {
+    dependsOn("auVideoBanner")
+  }
+}

package/lib/module/components/VideoFeed.js

@@ -0,0 +1,170 @@
+"use strict";
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { FlatList, StyleSheet, useWindowDimensions, View } from 'react-native';
+import { useVideoManager } from "../provider/VideoContext.js";
+import { VideoSurface } from "./VideoSurface.js";
+
+/** Surface id a feed item registers under. */
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export const feedSurfaceId = id => `feed:${id}`;
+
+/** Minimal shape of a FlatList viewability token (avoids RN type-name drift). */
+
+/**
+ * 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({
+  data,
+  itemHeight,
+  resizeMode,
+  muted = true,
+  repeat = true,
+  visibilityThreshold = 80,
+  renderOverlay,
+  onFocusChange,
+  pauseOnUnmount = true,
+  isFocused,
+  ...rest
+}) {
+  const manager = useVideoManager();
+  const {
+    height: windowHeight
+  } = useWindowDimensions();
+  const height = itemHeight ?? windowHeight;
+  const [focusedId, setFocusedId] = useState(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]);
+  useEffect(() => {
+    if (isFocused === undefined) {
+      return;
+    }
+    if (!isFocused) {
+      if (manager.store.getState().surfaceId === feedSurfaceId(focusedId ?? '')) {
+        manager.pause();
+      }
+      return;
+    }
+    // Screen regained focus — resume the item that was in view.
+    const item = data.find(d => d.id === focusedId);
+    if (item) {
+      manager.setSource(item, {
+        autoplay: true,
+        surfaceId: feedSurfaceId(item.id)
+      });
+    }
+  }, [manager, isFocused, focusedId, data]);
+  const focus = useCallback((item, index) => {
+    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
+  }) => {
+    const focusedToken = viewableItems.find(v => v.isViewable);
+    if (focusedToken) {
+      latest.current.focus(focusedToken.item, focusedToken.index ?? 0);
+    }
+  }).current;
+  const renderItem = useCallback(({
+    item,
+    index
+  }) => /*#__PURE__*/_jsxs(View, {
+    style: [styles.item, {
+      height
+    }],
+    children: [/*#__PURE__*/_jsx(VideoSurface, {
+      surfaceId: feedSurfaceId(item.id),
+      style: StyleSheet.absoluteFill
+    }), renderOverlay?.({
+      item,
+      index,
+      focused: item.id === focusedId
+    })]
+  }), [height, renderOverlay, focusedId]);
+  return /*#__PURE__*/_jsx(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'
+  }
+});
+//# sourceMappingURL=VideoFeed.js.map

package/lib/module/components/VideoFeed.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["useCallback","useEffect","useRef","useState","FlatList","StyleSheet","useWindowDimensions","View","useVideoManager","VideoSurface","jsx","_jsx","jsxs","_jsxs","feedSurfaceId","id","VideoFeed","data","itemHeight","resizeMode","muted","repeat","visibilityThreshold","renderOverlay","onFocusChange","pauseOnUnmount","isFocused","rest","manager","height","windowHeight","focusedId","setFocusedId","mute","unmute","setRepeat","setResizeMode","pause","undefined","store","getState","surfaceId","item","find","d","setSource","autoplay","focus","index","latest","current","viewabilityConfig","itemVisiblePercentThreshold","minimumViewTime","onViewableItemsChanged","viewableItems","focusedToken","v","isViewable","renderItem","style","styles","children","absoluteFill","focused","keyExtractor","getItemLayout","_","length","offset","showsVerticalScrollIndicator","snapToInterval","snapToAlignment","decelerationRate","create","width","backgroundColor","overflow"],"sourceRoot":"../../../src","sources":["components/VideoFeed.tsx"],"mappings":"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","ignoreList":[]}

package/lib/module/components/VideoPlayer.js

@@ -1,8 +1,9 @@
 "use strict";
 
-import { useEffect } from 'react';
-import { StyleSheet, View } from 'react-native';
+import { forwardRef, useEffect, useImperativeHandle, useRef } from 'react';
+import { AppState, StyleSheet, View } from 'react-native';
 import { useVideoManager } from "../provider/VideoContext.js";
+import { useVideoEvents } from "../hooks/useVideoEvents.js";
 import { VideoControls } from "./VideoControls.js";
 import { VideoSurface } from "./VideoSurface.js";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
@@ -14,23 +15,42 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * ```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({
+export const VideoPlayer = /*#__PURE__*/forwardRef(({
   source,
   autoplay = true,
   surfaceId,
   controls = true,
   resizeMode,
+  repeat,
+  muted,
   orientation,
   fullscreenOrientation,
+  pauseOnFocusLost = true,
+  isFocused,
+  onLoadComplete,
+  onBuffering,
+  onError,
   style,
   ...rest
-}) {
+}, ref) => {
   const manager = useVideoManager();
   const id = surfaceId ?? `player:${source.id}`;
+
+  // Read the latest source without retriggering effects on every render
+  // (source is usually a fresh object literal each render).
+  const sourceRef = useRef(source);
+  sourceRef.current = source;
+  useImperativeHandle(ref, () => manager, [manager]);
   useEffect(() => {
+    // Don't autoplay a player that mounts already unfocused (isFocused
+    // false), else it'd flash play → pause on the next screen.
     manager.setSource(source, {
-      autoplay,
+      autoplay: autoplay && isFocused !== false,
       surfaceId: id
     });
     // Attach on mount / when the video identity changes. Other source
@@ -42,6 +62,22 @@ export function VideoPlayer({
       manager.setResizeMode(resizeMode);
     }
   }, [manager, resizeMode]);
+  useEffect(() => {
+    if (repeat === undefined) {
+      return;
+    }
+    manager.setRepeat(repeat);
+  }, [manager, repeat]);
+  useEffect(() => {
+    if (muted === undefined) {
+      return;
+    }
+    if (muted) {
+      manager.mute();
+    } else {
+      manager.unmute();
+    }
+  }, [manager, muted]);
   useEffect(() => {
     if (!orientation || orientation === 'auto') {
       return;
@@ -56,6 +92,47 @@ export function VideoPlayer({
     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]);
+  useEffect(() => {
+    if (isFocused === undefined) {
+      return;
+    }
+    const state = manager.store.getState();
+    if (isFocused) {
+      // Regained screen focus. If the engine is still ours, just resume;
+      // otherwise it moved to another video while we were blurred — reclaim
+      // it (same-id handoff means no reload if it never actually left).
+      if (state.surfaceId === id && state.currentVideo?.id === sourceRef.current.id) {
+        manager.play();
+      } else {
+        manager.setSource(sourceRef.current, {
+          autoplay: true,
+          surfaceId: id
+        });
+      }
+    } else if (state.surfaceId === id) {
+      // Lost screen focus while playing our video — pause. Guarded so we
+      // never pause a video that has already handed off elsewhere.
+      manager.pause();
+    }
+  }, [manager, id, isFocused]);
+  useVideoEvents({
+    onLoad: onLoadComplete,
+    onBuffer: e => onBuffering?.(e.buffering),
+    onError
+  });
   return /*#__PURE__*/_jsxs(View, {
     style: [styles.container, style],
     ...rest,
@@ -64,7 +141,8 @@ export function VideoPlayer({
       style: styles.surface
     }), controls ? /*#__PURE__*/_jsx(VideoControls, {}) : null]
   });
-}
+});
+VideoPlayer.displayName = 'VideoPlayer';
 const styles = StyleSheet.create({
   container: {
     backgroundColor: '#000',

package/lib/module/components/VideoPlayer.js.map

@@ -1 +1 @@
-{"version":3,"names":["useEffect","StyleSheet","View","useVideoManager","VideoControls","VideoSurface","jsx","_jsx","jsxs","_jsxs","VideoPlayer","source","autoplay","surfaceId","controls","resizeMode","orientation","fullscreenOrientation","style","rest","manager","id","setSource","setResizeMode","setOrientation","setFullscreenOrientation","styles","container","children","surface","create","backgroundColor","overflow","position","top","left","right","bottom"],"sourceRoot":"../../../src","sources":["components/VideoPlayer.tsx"],"mappings":";;AAAA,SAASA,SAAS,QAAQ,OAAO;AACjC,SAASC,UAAU,EAAEC,IAAI,QAAwB,cAAc;AAC/D,SAASC,eAAe,QAAQ,6BAA0B;AAE1D,SAASC,aAAa,QAAQ,oBAAiB;AAC/C,SAASC,YAAY,QAAQ,mBAAgB;AAAC,SAAAC,GAAA,IAAAC,IAAA,EAAAC,IAAA,IAAAC,KAAA;AA8B9C;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,WAAWA,CAAC;EAC1BC,MAAM;EACNC,QAAQ,GAAG,IAAI;EACfC,SAAS;EACTC,QAAQ,GAAG,IAAI;EACfC,UAAU;EACVC,WAAW;EACXC,qBAAqB;EACrBC,KAAK;EACL,GAAGC;AACa,CAAC,EAAE;EACnB,MAAMC,OAAO,GAAGjB,eAAe,CAAC,CAAC;EACjC,MAAMkB,EAAE,GAAGR,SAAS,IAAI,UAAUF,MAAM,CAACU,EAAE,EAAE;EAE7CrB,SAAS,CAAC,MAAM;IACdoB,OAAO,CAACE,SAAS,CAACX,MAAM,EAAE;MAAEC,QAAQ;MAAEC,SAAS,EAAEQ;IAAG,CAAC,CAAC;IACtD;IACA;IACA;EACF,CAAC,EAAE,CAACD,OAAO,EAAET,MAAM,CAACU,EAAE,EAAEA,EAAE,CAAC,CAAC;EAE5BrB,SAAS,CAAC,MAAM;IACd,IAAIe,UAAU,EAAE;MACdK,OAAO,CAACG,aAAa,CAACR,UAAU,CAAC;IACnC;EACF,CAAC,EAAE,CAACK,OAAO,EAAEL,UAAU,CAAC,CAAC;EAEzBf,SAAS,CAAC,MAAM;IACd,IAAI,CAACgB,WAAW,IAAIA,WAAW,KAAK,MAAM,EAAE;MAC1C;IACF;IACAI,OAAO,CAACI,cAAc,CAACR,WAAW,CAAC;IACnC,OAAO,MAAMI,OAAO,CAACI,cAAc,CAAC,MAAM,CAAC;EAC7C,CAAC,EAAE,CAACJ,OAAO,EAAEJ,WAAW,CAAC,CAAC;EAE1BhB,SAAS,CAAC,MAAM;IACd,IAAI,CAACiB,qBAAqB,EAAE;MAC1B;IACF;IACAG,OAAO,CAACK,wBAAwB,CAACR,qBAAqB,CAAC;IACvD,OAAO,MAAMG,OAAO,CAACK,wBAAwB,CAAC,IAAI,CAAC;EACrD,CAAC,EAAE,CAACL,OAAO,EAAEH,qBAAqB,CAAC,CAAC;EAEpC,oBACER,KAAA,CAACP,IAAI;IAACgB,KAAK,EAAE,CAACQ,MAAM,CAACC,SAAS,EAAET,KAAK,CAAE;IAAA,GAAKC,IAAI;IAAAS,QAAA,gBAC9CrB,IAAA,CAACF,YAAY;MAACQ,SAAS,EAAEQ,EAAG;MAACH,KAAK,EAAEQ,MAAM,CAACG;IAAQ,CAAE,CAAC,EACrDf,QAAQ,gBAAGP,IAAA,CAACH,aAAa,IAAE,CAAC,GAAG,IAAI;EAAA,CAChC,CAAC;AAEX;AAEA,MAAMsB,MAAM,GAAGzB,UAAU,CAAC6B,MAAM,CAAC;EAC/BH,SAAS,EAAE;IACTI,eAAe,EAAE,MAAM;IACvBC,QAAQ,EAAE;EACZ,CAAC;EACDH,OAAO,EAAE;IACPI,QAAQ,EAAE,UAAU;IACpBC,GAAG,EAAE,CAAC;IACNC,IAAI,EAAE,CAAC;IACPC,KAAK,EAAE,CAAC;IACRC,MAAM,EAAE;EACV;AACF,CAAC,CAAC","ignoreList":[]}
+{"version":3,"names":["forwardRef","useEffect","useImperativeHandle","useRef","AppState","StyleSheet","View","useVideoManager","useVideoEvents","VideoControls","VideoSurface","jsx","_jsx","jsxs","_jsxs","VideoPlayer","source","autoplay","surfaceId","controls","resizeMode","repeat","muted","orientation","fullscreenOrientation","pauseOnFocusLost","isFocused","onLoadComplete","onBuffering","onError","style","rest","ref","manager","id","sourceRef","current","setSource","setResizeMode","undefined","setRepeat","mute","unmute","setOrientation","setFullscreenOrientation","sub","addEventListener","next","store","getState","pause","remove","state","currentVideo","play","onLoad","onBuffer","e","buffering","styles","container","children","surface","displayName","create","backgroundColor","overflow","position","top","left","right","bottom"],"sourceRoot":"../../../src","sources":["components/VideoPlayer.tsx"],"mappings":"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","ignoreList":[]}

package/lib/module/index.js

@@ -5,6 +5,7 @@ export { useVideoManager } from "./provider/VideoContext.js";
 export { VideoManager, FULLSCREEN_SURFACE_ID, FLOATING_SURFACE_ID } from "./core/VideoManager.js";
 export { VideoSurface } from "./components/VideoSurface.js";
 export { VideoPlayer } from "./components/VideoPlayer.js";
+export { VideoFeed, feedSurfaceId } from "./components/VideoFeed.js";
 export { FullscreenPlayer } from "./components/FullscreenPlayer.js";
 export { FloatingPlayer } from "./components/FloatingPlayer.js";
 export { MiniPlayer } from "./components/MiniPlayer.js";

package/lib/module/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["VideoProvider","useVideoManager","VideoManager","FULLSCREEN_SURFACE_ID","FLOATING_SURFACE_ID","VideoSurface","VideoPlayer","FullscreenPlayer","FloatingPlayer","MiniPlayer","VideoControls","GestureOverlay","useVideo","usePlayback","useFullscreen","usePiP","useVideoEvents","formatTime"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;AAAA,SACEA,aAAa,QAER,6BAA0B;AACjC,SAASC,eAAe,QAAQ,4BAAyB;AACzD,SACEC,YAAY,EACZC,qBAAqB,EACrBC,mBAAmB,QACd,wBAAqB;AAE5B,SACEC,YAAY,QAEP,8BAA2B;AAClC,SAASC,WAAW,QAA+B,6BAA0B;AAC7E,SAASC,gBAAgB,QAAQ,kCAA+B;AAChE,SACEC,cAAc,QAET,gCAA6B;AACpC,SAASC,UAAU,QAA8B,4BAAyB;AAC1E,SACEC,aAAa,QAER,+BAA4B;AACnC,SACEC,cAAc,QAET,gCAA6B;AAEpC,SAASC,QAAQ,QAAQ,qBAAkB;AAC3C,SAASC,WAAW,QAAQ,wBAAqB;AACjD,SAASC,aAAa,QAAQ,0BAAuB;AACrD,SAASC,MAAM,QAAQ,mBAAgB;AACvC,SACEC,cAAc,QAET,2BAAwB;AAE/B,SAASC,UAAU,QAAQ,uBAAoB","ignoreList":[]}
+{"version":3,"names":["VideoProvider","useVideoManager","VideoManager","FULLSCREEN_SURFACE_ID","FLOATING_SURFACE_ID","VideoSurface","VideoPlayer","VideoFeed","feedSurfaceId","FullscreenPlayer","FloatingPlayer","MiniPlayer","VideoControls","GestureOverlay","useVideo","usePlayback","useFullscreen","usePiP","useVideoEvents","formatTime"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;AAAA,SACEA,aAAa,QAER,6BAA0B;AACjC,SAASC,eAAe,QAAQ,4BAAyB;AACzD,SACEC,YAAY,EACZC,qBAAqB,EACrBC,mBAAmB,QACd,wBAAqB;AAE5B,SACEC,YAAY,QAEP,8BAA2B;AAClC,SAASC,WAAW,QAA+B,6BAA0B;AAC7E,SACEC,SAAS,EACTC,aAAa,QAGR,2BAAwB;AAC/B,SAASC,gBAAgB,QAAQ,kCAA+B;AAChE,SACEC,cAAc,QAET,gCAA6B;AACpC,SAASC,UAAU,QAA8B,4BAAyB;AAC1E,SACEC,aAAa,QAER,+BAA4B;AACnC,SACEC,cAAc,QAET,gCAA6B;AAEpC,SAASC,QAAQ,QAAQ,qBAAkB;AAC3C,SAASC,WAAW,QAAQ,wBAAqB;AACjD,SAASC,aAAa,QAAQ,0BAAuB;AACrD,SAASC,MAAM,QAAQ,mBAAgB;AACvC,SACEC,cAAc,QAET,2BAAwB;AAE/B,SAASC,UAAU,QAAQ,uBAAoB","ignoreList":[]}

package/lib/typescript/src/components/VideoFeed.d.ts

@@ -0,0 +1,56 @@
+import { type ReactNode } from 'react';
+import { type FlatListProps } from 'react-native';
+import type { ResizeMode, VideoSource } from '../types/video.js';
+/** Surface id a feed item registers under. */
+export declare const feedSurfaceId: (id: string) => string;
+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;
+    /**
+     * Screen-focus flag from your navigation library — e.g. React Navigation's
+     * `useIsFocused()`. `false` pauses the feed; returning to `true` resumes the
+     * item that was in view. Needed because navigating away keeps the feed
+     * mounted and the app foregrounded. Leave undefined if you don't navigate.
+     */
+    isFocused?: 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 declare function VideoFeed<T extends VideoSource>({ data, itemHeight, resizeMode, muted, repeat, visibilityThreshold, renderOverlay, onFocusChange, pauseOnUnmount, isFocused, ...rest }: VideoFeedProps<T>): import("react").JSX.Element;
+//# sourceMappingURL=VideoFeed.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VideoFeed.d.ts","sourceRoot":"","sources":["../../../../src/components/VideoFeed.tsx"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AACf,OAAO,EAKL,KAAK,aAAa,EACnB,MAAM,cAAc,CAAC;AAEtB,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,mBAAgB,CAAC;AAG9D,8CAA8C;AAC9C,eAAO,MAAM,aAAa,GAAI,IAAI,MAAM,WAAiB,CAAC;AAS1D,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,IAAI,EAAE,CAAC,CAAC;IACR,KAAK,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,WAAW,CAAE,SAAQ,IAAI,CACjE,aAAa,CAAC,CAAC,CAAC,EACd,MAAM,GACN,YAAY,GACZ,cAAc,GACd,wBAAwB,GACxB,mBAAmB,GACnB,eAAe,CAClB;IACC,6EAA6E;IAC7E,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,kFAAkF;IAClF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,yEAAyE;IACzE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,8CAA8C;IAC9C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,6EAA6E;IAC7E,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,+EAA+E;IAC/E,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,mBAAmB,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC;IAC5D,wEAAwE;IACxE,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACxD,6DAA6D;IAC7D,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,WAAW,EAAE,EAC/C,IAAI,EACJ,UAAU,EACV,UAAU,EACV,KAAY,EACZ,MAAa,EACb,mBAAwB,EACxB,aAAa,EACb,aAAa,EACb,cAAqB,EACrB,SAAS,EACT,GAAG,IAAI,EACR,EAAE,cAAc,CAAC,CAAC,CAAC,+BA2HnB"}

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

@@ -1,5 +1,7 @@
 import { type ViewProps } from 'react-native';
-import type { OrientationLock, ResizeMode, VideoSource } from '../types/video.js';
+import { VideoManager } from '../core/VideoManager.js';
+import type { VideoEventMap } from '../types/events.js';
+import type { OrientationLock, ResizeMode, VideoError, VideoSource } from '../types/video.js';
 export interface VideoPlayerProps extends ViewProps {
     source: VideoSource;
     /** Default true. */
@@ -13,6 +15,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
@@ -26,6 +32,32 @@ 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;
+    /**
+     * Screen-focus flag from your navigation library — e.g. React Navigation's
+     * `useIsFocused()`. `false` pauses this player; returning to `true` reclaims
+     * the engine and resumes this video. This is the only reliable way to pause
+     * on screen navigation (React Navigation keeps screens mounted and the app
+     * stays foregrounded, so unmount/AppState never fire). Leave undefined if
+     * you don't use navigation.
+     *
+     * ```tsx
+     * const isFocused = useIsFocused(); // @react-navigation/native
+     * <VideoPlayer source={video} isFocused={isFocused} />
+     * ```
+     */
+    isFocused?: 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;
 }
 /**
  * Convenience all-in-one player: `setSource` (same-video handoff aware) +
@@ -35,6 +67,10 @@ 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 declare function VideoPlayer({ source, autoplay, surfaceId, controls, resizeMode, orientation, fullscreenOrientation, style, ...rest }: VideoPlayerProps): import("react").JSX.Element;
+export declare const VideoPlayer: import("react").ForwardRefExoticComponent<VideoPlayerProps & import("react").RefAttributes<VideoManager>>;
 //# sourceMappingURL=VideoPlayer.d.ts.map

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;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,+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,2GA0IvB,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.3",
+  "version": "0.2.5",
   "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,58 @@
+'use strict';
+
+/**
+ * Prints a banner. Wrapped so it can NEVER fail a consumer's `npm install`
+ * or native build — any error is swallowed and the process always exits 0.
+ *
+ * Run modes:
+ *   node scripts/postinstall.js            → install banner (skipped in CI /
+ *                                             non-interactive shells)
+ *   node scripts/postinstall.js --force    → always print (used by the
+ *                                             Android build so it shows while
+ *                                             compiling the app, where stdout
+ *                                             is not a TTY)
+ */
+
+const force =
+  process.argv.includes('--force') || process.env.AU_VIDEO_BANNER === '1';
+
+const BANNER = `
+                                                                                       ++
+                       +++                              +++                      +++++++++++    ++
+      ++++++++++++++  ++++++++++         ++++++++++++++ +++                    +++++++ ++      +++
+      ++    +++   +++ ++++++++++++       +++      +++++ ++++    +++++++   ++++ +++++++ ++      +++
+      ++    +++   +++ ++++     +++       +++++++++++++  ++++ +++++ ++++ +++++  +++++++ ++      +++++++++++
+      +++   +++   +++ ++++    ++++       +++    +++++++ +++++++    +++++++++    +++++++++      ++++    ++++
+      ++++  +++   +++ ++++++++++         ++++++     +++ ++++++    +++++  +++           ++      +++      +++
+      +++   ++    +++ ++++  +++          +++  ++++++++  ++++     ++++   +++      ++++ +++      +++      +++
+                      ++++   ++++                       ++++    +++     ++      +++++ ++       +++     ++++
+        +++++++               ++++                                      ++       ++++++         ++++++++++
+     ++++ ++++        +         +++                       ++++        +                        +++++++++++
+   +++   +++        ++++        +++++        ++++        +++        +++        ++++       ++++        +++
+   ++++++++         ++           ++                       ++                             +++ +        ++
+`;
+
+try {
+  const quiet = process.env.CI || process.env.npm_config_loglevel === 'silent';
+  const show = force || (!quiet && process.stdout && process.stdout.isTTY);
+  if (show) {
+    // Colorize only in a real terminal — under Gradle/CI (--force, not a TTY)
+    // stay plain so the log doesn't fill with raw escape codes.
+    const color = process.stdout && process.stdout.isTTY;
+    const cyan = color ? '\x1b[36m' : '';
+    const dim = color ? '\x1b[2m' : '';
+    const reset = color ? '\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/VideoFeed.tsx

@@ -0,0 +1,231 @@
+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;
+  /**
+   * Screen-focus flag from your navigation library — e.g. React Navigation's
+   * `useIsFocused()`. `false` pauses the feed; returning to `true` resumes the
+   * item that was in view. Needed because navigating away keeps the feed
+   * mounted and the app foregrounded. Leave undefined if you don't navigate.
+   */
+  isFocused?: 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,
+  isFocused,
+  ...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]);
+
+  useEffect(() => {
+    if (isFocused === undefined) {
+      return;
+    }
+    if (!isFocused) {
+      if (
+        manager.store.getState().surfaceId === feedSurfaceId(focusedId ?? '')
+      ) {
+        manager.pause();
+      }
+      return;
+    }
+    // Screen regained focus — resume the item that was in view.
+    const item = data.find((d) => d.id === focusedId);
+    if (item) {
+      manager.setSource(item, {
+        autoplay: true,
+        surfaceId: feedSurfaceId(item.id),
+      });
+    }
+  }, [manager, isFocused, focusedId, data]);
+
+  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, useRef } 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,32 @@ 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;
+  /**
+   * Screen-focus flag from your navigation library — e.g. React Navigation's
+   * `useIsFocused()`. `false` pauses this player; returning to `true` reclaims
+   * the engine and resumes this video. This is the only reliable way to pause
+   * on screen navigation (React Navigation keeps screens mounted and the app
+   * stays foregrounded, so unmount/AppState never fire). Leave undefined if
+   * you don't use navigation.
+   *
+   * ```tsx
+   * const isFocused = useIsFocused(); // @react-navigation/native
+   * <VideoPlayer source={video} isFocused={isFocused} />
+   * ```
+   */
+  isFocused?: 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 +79,152 @@ 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}`;
-
-  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 (resizeMode) {
-      manager.setResizeMode(resizeMode);
-    }
-  }, [manager, resizeMode]);
-
-  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]);
-
-  return (
-    <View style={[styles.container, style]} {...rest}>
-      <VideoSurface surfaceId={id} style={styles.surface} />
-      {controls ? <VideoControls /> : null}
-    </View>
-  );
-}
+export const VideoPlayer = forwardRef<VideoManager, VideoPlayerProps>(
+  (
+    {
+      source,
+      autoplay = true,
+      surfaceId,
+      controls = true,
+      resizeMode,
+      repeat,
+      muted,
+      orientation,
+      fullscreenOrientation,
+      pauseOnFocusLost = true,
+      isFocused,
+      onLoadComplete,
+      onBuffering,
+      onError,
+      style,
+      ...rest
+    },
+    ref
+  ) => {
+    const manager = useVideoManager();
+    const id = surfaceId ?? `player:${source.id}`;
+
+    // Read the latest source without retriggering effects on every render
+    // (source is usually a fresh object literal each render).
+    const sourceRef = useRef(source);
+    sourceRef.current = source;
+
+    useImperativeHandle(ref, () => manager, [manager]);
+
+    useEffect(() => {
+      // Don't autoplay a player that mounts already unfocused (isFocused
+      // false), else it'd flash play → pause on the next screen.
+      manager.setSource(source, {
+        autoplay: autoplay && isFocused !== false,
+        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 (resizeMode) {
+        manager.setResizeMode(resizeMode);
+      }
+    }, [manager, resizeMode]);
+
+    useEffect(() => {
+      if (repeat === undefined) {
+        return;
+      }
+      manager.setRepeat(repeat);
+    }, [manager, repeat]);
+
+    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]);
+
+    useEffect(() => {
+      if (isFocused === undefined) {
+        return;
+      }
+      const state = manager.store.getState();
+      if (isFocused) {
+        // Regained screen focus. If the engine is still ours, just resume;
+        // otherwise it moved to another video while we were blurred — reclaim
+        // it (same-id handoff means no reload if it never actually left).
+        if (
+          state.surfaceId === id &&
+          state.currentVideo?.id === sourceRef.current.id
+        ) {
+          manager.play();
+        } else {
+          manager.setSource(sourceRef.current, {
+            autoplay: true,
+            surfaceId: id,
+          });
+        }
+      } else if (state.surfaceId === id) {
+        // Lost screen focus while playing our video — pause. Guarded so we
+        // never pause a video that has already handed off elsewhere.
+        manager.pause();
+      }
+    }, [manager, id, isFocused]);
+
+    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,