extended-vlc-player 0.1.0

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "extended-vlc-player",
+  "version": "0.1.0",
+  "description": "React Native video player built on MobileVLCKit (iOS) and libVLC (Android) with true iOS Picture-in-Picture via AVSampleBufferDisplayLayer bridge.",
+  "license": "MIT",
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "author": {
+    "name": "Berat Tüfekli",
+    "email": "berattufekli@gmail.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/berattufekli/extended-vlc-player.git"
+  },
+  "bugs": {
+    "url": "https://github.com/berattufekli/extended-vlc-player/issues"
+  },
+  "homepage": "https://github.com/berattufekli/extended-vlc-player#readme",
+  "keywords": [
+    "react-native",
+    "expo",
+    "video",
+    "player",
+    "vlc",
+    "mobilevlckit",
+    "mkv",
+    "matroska",
+    "picture-in-picture",
+    "pip",
+    "iptv",
+    "expo-module"
+  ],
+  "scripts": {
+    "build": "expo-module build",
+    "clean": "expo-module clean",
+    "lint": "expo-module lint",
+    "test": "jest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "tsc --noEmit"
+  },
+  "files": [
+    "build",
+    "ios",
+    "android",
+    "src",
+    "app.plugin.js",
+    "expo-module.config.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "expo": "*",
+    "expo-modules-core": "*",
+    "react": "*",
+    "react-native": "*"
+  },
+  "devDependencies": {
+    "@types/react": "~19.2.14",
+    "expo": "^57.0.0",
+    "expo-module-scripts": "^56.0.3",
+    "expo-modules-core": "~57.0.2",
+    "typescript": "~6.0.3"
+  }
+}

package/src/ExtendedVlcPlayerView.tsx

@@ -0,0 +1,68 @@
+import { requireNativeViewManager } from 'expo-modules-core';
+import * as React from 'react';
+import { Platform, type ViewStyle } from 'react-native';
+
+import type { ExtendedVlcPlayerViewProps } from './types';
+
+const NativeView = requireNativeViewManager('ExtendedVlcPlayerView');
+
+/**
+ * Drop-in replacement for `expo-video`'s `VideoView`. Renders the VLC-backed
+ * native player and forwards events back to the JS callbacks.
+ */
+export const ExtendedVlcPlayerView = React.forwardRef<unknown, ExtendedVlcPlayerViewProps>(
+  function ExtendedVlcPlayerView(props, ref) {
+    const {
+      player,
+      style,
+      contentFit = 'contain',
+      onLoad,
+      onProgress,
+      onPlaying,
+      onPaused,
+      onEnded,
+      onError,
+      onBuffering,
+      onPictureInPictureStart,
+      onPictureInPictureStop,
+    } = props;
+
+    // The `player` object carries the nativeId internally (the hook bumps
+    // it on first render). The native view reads it via a getter so we
+    // don't have to thread the number through props.
+    const nativeId = (player as unknown as { _nativeId?: number })._nativeId ?? 0;
+
+    return (
+      <NativeView
+        ref={ref}
+        style={style as ViewStyle}
+        player={nativeId}
+        contentFit={contentFit}
+        // Standard Fabric "bubbling event" props. They are passed as
+        // RCTBubblingEventBlock on the native side; the Swift
+        // PlayerSession fires the corresponding closures which the
+        // PlayerRegistryBridge forwards back to the view component,
+        // which then invokes the right block.
+        onLoad={onLoad}
+        onProgress={onProgress}
+        onPlaying={onPlaying}
+        onPaused={onPaused}
+        onEnded={onEnded}
+        onError={onError}
+        onBuffering={onBuffering}
+        onPictureInPictureStart={onPictureInPictureStart}
+        onPictureInPictureStop={onPictureInPictureStop}
+      />
+    );
+  }
+);
+
+// Surface a helpful message on platforms where the view manager is not
+// registered (e.g. web). The real native view manager is registered by
+// the iOS / Android sides.
+if (Platform.OS !== 'ios' && Platform.OS !== 'android') {
+  // eslint-disable-next-line no-console
+  console.warn(
+    '[extended-vlc-player] ExtendedVlcPlayerView is only supported on iOS and Android.'
+  );
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+/**
+ * `extended-vlc-player` public API.
+ *
+ * The default export is the native view component; named exports are the
+ * imperative player hook and the type contracts. Consumers normally use:
+ *
+ *   import { useExtendedVlcPlayer, ExtendedVlcPlayerView } from 'extended-vlc-player';
+ */
+export { ExtendedVlcPlayerView } from './ExtendedVlcPlayerView';
+export { useExtendedVlcPlayer } from './useExtendedVlcPlayer';
+export type {
+  ContentFit,
+  ExtendedVlcErrorEvent,
+  ExtendedVlcLoadEvent,
+  ExtendedVlcPlayer,
+  ExtendedVlcPlayerViewProps,
+  ExtendedVlcProgressEvent,
+  ExtendedVlcSource,
+  ExtendedVlcTrack,
+} from './types';

package/src/types.ts

@@ -0,0 +1,100 @@
+import type { ViewStyle } from 'react-native';
+
+/**
+ * Source descriptor for the VLC player. Mirrors `expo-video`'s `VideoSource`
+ * surface so the existing call sites (a string URL or an object) keep
+ * working without change.
+ */
+export type ExtendedVlcSource =
+  | string
+  | {
+      uri: string;
+      headers?: Record<string, string>;
+      /**
+       * Optional drm descriptor. NOTE: the new module does not decrypt
+       * Widevine/FairPlay streams (libVLC has no DRM path). The field is
+       * accepted for API parity with `expo-video`; if a DRM source reaches
+       * the player it will emit `onError` and the caller should fall back
+       * to `expo-video`.
+       */
+      drm?: unknown;
+    };
+
+/** Audio / subtitle track entry exposed by VLC after a source loads. */
+export interface ExtendedVlcTrack {
+  index: number;
+  /** Localised label, e.g. "English", "Türkçe 5.1". */
+  label?: string;
+  /** RFC 5646 language code when VLC exposes one. */
+  language?: string;
+  /** Codec identifier reported by libVLC (e.g. "mp4a", "ac3", "subrip"). */
+  codec?: string;
+}
+
+export interface ExtendedVlcLoadEvent {
+  duration: number;       // seconds
+  audioTracks: ExtendedVlcTrack[];
+  textTracks: ExtendedVlcTrack[];
+}
+
+export interface ExtendedVlcProgressEvent {
+  currentTime: number;    // seconds
+  duration: number;       // seconds
+  /** 0..1 position; mirrors the legacy VLC position field. */
+  position: number;
+}
+
+export interface ExtendedVlcErrorEvent {
+  code?: string;
+  message: string;
+  domain?: string;
+}
+
+export type ContentFit = 'contain' | 'cover' | 'fill';
+
+export interface ExtendedVlcPlayerViewProps {
+  /** The player object returned by `useExtendedVlcPlayer`. */
+  player: ExtendedVlcPlayer;
+  style?: ViewStyle;
+  contentFit?: ContentFit;
+  onLoad?: (e: ExtendedVlcLoadEvent) => void;
+  onProgress?: (e: ExtendedVlcProgressEvent) => void;
+  onPlaying?: (e: { duration: number }) => void;
+  onPaused?: (e: { target: number }) => void;
+  onEnded?: () => void;
+  onError?: (e: ExtendedVlcErrorEvent) => void;
+  onBuffering?: (e: { isBuffering: boolean }) => void;
+  onPictureInPictureStart?: () => void;
+  onPictureInPictureStop?: () => void;
+}
+
+/**
+ * Imperative player object. Mirrors the surface of `BackgroundVideoPlayer`'s
+ * `videoRef.current` so consumers can swap the import without touching
+ * the rest of their UI.
+ */
+export interface ExtendedVlcPlayer {
+  play(): void;
+  pause(): void;
+  stop(): void;
+  /** `seconds` is a wall-clock position in seconds (matches expo-video). */
+  seek(seconds: number): void;
+  /** `rate` is a playback rate multiplier (0.5, 1, 1.5, 2). */
+  setRate(rate: number): void;
+  /** `volume` is 0..1 (matches the existing VLC contract). */
+  setVolume(volume: number): void;
+  /** `index` of the audio track in the most recent `onLoad` payload, or -1 to disable. */
+  setAudioTrack(index: number): void;
+  /** `index` of the subtitle track, or -1 to disable. */
+  setSubtitleTrack(index: number): void;
+  /** Replace the current source without remounting the view. */
+  replace(source: ExtendedVlcSource): void;
+  /** Start the system Picture-in-Picture overlay. Resolves true when entered. */
+  startPictureInPicture(): Promise<boolean>;
+  /** Exit PiP if it is active. Resolves true when the controller stopped. */
+  stopPictureInPicture(): Promise<boolean>;
+  /** True while PiP is active. Mirrors the native state. */
+  isPictureInPictureActive(): Promise<boolean>;
+  /** True when the device + iOS version support PiP. */
+  isPictureInPictureSupported(): Promise<boolean>;
+}

package/src/useExtendedVlcPlayer.ts

@@ -0,0 +1,160 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { requireNativeModule } from 'expo-modules-core';
+
+import type {
+  ExtendedVlcLoadEvent,
+  ExtendedVlcPlayer,
+  ExtendedVlcProgressEvent,
+  ExtendedVlcSource,
+} from './types';
+
+// Native module is registered by the platform-specific module under the
+// JS module name "ExtendedVlcPlayer". The requireNativeModule helper resolves
+// it at runtime; if the native side is missing, accessing the module throws
+// — we surface a clear error so the consumer knows what failed instead of
+// silently producing a no-op player.
+let nativeModule: any = null;
+try {
+  nativeModule = requireNativeModule('ExtendedVlcPlayer');
+} catch (error) {
+  // Allow JS-side import of the module to succeed even when the native side
+  // is not yet built (e.g. in a Jest test environment). We throw a helpful
+  // error only when the consumer actually calls a method.
+  nativeModule = null;
+}
+
+function getModule() {
+  if (!nativeModule) {
+    throw new Error(
+      '[extended-vlc-player] Native module is not available. ' +
+        'Run `npx expo prebuild --clean` and rebuild the app, ' +
+        'or check that the plugin ran successfully.'
+    );
+  }
+  return nativeModule;
+}
+
+function normalizeSource(source: ExtendedVlcSource) {
+  if (typeof source === 'string') return { uri: source };
+  const { uri } = source;
+  if (!uri) {
+    throw new Error('[extended-vlc-player] source.uri is required');
+  }
+  return { uri, headers: source.headers ?? null, drm: source.drm ?? null };
+}
+
+export interface UseExtendedVlcPlayerOptions {
+  /** Called once after the player is constructed. Useful for attaching PiP handlers. */
+  onReady?: (player: ExtendedVlcPlayer) => void;
+}
+
+/**
+ * Returns a stable player object for the given source. The native player
+ * is created once (lazy on first method call) and replaced in place when
+ * `source` changes via the same `replace` API used by `expo-video`.
+ */
+export function useExtendedVlcPlayer(
+  source: ExtendedVlcSource,
+  options: UseExtendedVlcPlayerOptions = {}
+): ExtendedVlcPlayer {
+  const normalized = useMemo(() => normalizeSource(source), [source]);
+  // We hold a numeric id of the "current native source" so we can detect
+  // when the JS source prop has changed and tell the native module to swap.
+  const [nativeId, setNativeId] = useState(0);
+  const isMountedRef = useRef(true);
+
+  // Event subscription is wired through the Fabric view component, not the
+  // module — events flow back into the JS player object via the
+  // ExtendedVlcPlayerView's callbacks. We keep the module call surface
+  // (play/pause/seek/PiP) here.
+
+  useEffect(() => {
+    isMountedRef.current = true;
+    return () => {
+      isMountedRef.current = false;
+    };
+  }, []);
+
+  useEffect(() => {
+    // When the source prop changes, ask the native module to swap in place
+    // instead of remounting the view (which would reset audio session, PiP
+    // delegate wiring, etc.).
+    try {
+      getModule().replace(normalized);
+    } catch (error) {
+      // Surface as console error; the player view will also emit onError
+      // once the Fabric event dispatcher picks it up.
+      // eslint-disable-next-line no-console
+      console.warn('[extended-vlc-player] replace failed:', error);
+    }
+  }, [normalized]);
+
+  // The player object is intentionally stable across renders. Methods are
+  // closures over `nativeId` so the latest normalized source is always
+  // referenced, but the object identity does not change — consumers can
+  // safely put it in dependency arrays.
+  const player = useMemo<ExtendedVlcPlayer>(() => {
+    const p: ExtendedVlcPlayer & { _nativeId: number } = {
+      _nativeId: nativeId,
+      play: () => getModule().play(nativeId),
+      pause: () => getModule().pause(nativeId),
+      stop: () => getModule().stop(nativeId),
+      seek: (seconds: number) => getModule().seek(nativeId, seconds),
+      setRate: (rate: number) => getModule().setRate(nativeId, rate),
+      setVolume: (volume: number) => getModule().setVolume(nativeId, volume),
+      setAudioTrack: (index: number) => getModule().setAudioTrack(nativeId, index),
+      setSubtitleTrack: (index: number) => getModule().setSubtitleTrack(nativeId, index),
+      replace: (next: ExtendedVlcSource) => {
+        const nextNormalized = normalizeSource(next);
+        try {
+          getModule().replace({
+            ...nextNormalized,
+            // Tag the replace with the current nativeId so the existing
+            // instance is updated rather than a new one allocated.
+            instanceId: nativeId,
+          });
+        } catch (error) {
+          // eslint-disable-next-line no-console
+          console.warn('[extended-vlc-player] replace failed:', error);
+        }
+      },
+      startPictureInPicture: () => getModule().startPictureInPicture(nativeId),
+      stopPictureInPicture: () => getModule().stopPictureInPicture(nativeId),
+      isPictureInPictureActive: () => getModule().isPictureInPictureActive(nativeId),
+      isPictureInPictureSupported: () => getModule().isPictureInPictureSupported(),
+    };
+    return p;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [nativeId]);
+
+  // Bridge the native callback API. The hook surfaces the player as soon
+  // as it exists, so consumers can attach PiP handlers from `onReady`.
+  useEffect(() => {
+    if (options.onReady) {
+      try {
+        options.onReady(player);
+      } catch (error) {
+        // eslint-disable-next-line no-console
+        console.warn('[extended-vlc-player] onReady handler threw:', error);
+      }
+    }
+  }, [player, options]);
+
+  // Bump the native id once on mount so the first source prop is committed
+  // to the native side. We use a ref-based "first" instead of an effect to
+  // avoid an extra render.
+  const firstRef = useRef(true);
+  useEffect(() => {
+    if (firstRef.current) {
+      firstRef.current = false;
+      setNativeId(1);
+    }
+  }, []);
+
+  // Mark unused variables to keep TypeScript happy with strict checks.
+  void useCallback;
+  void isMountedRef;
+  void (undefined as ExtendedVlcLoadEvent | ExtendedVlcProgressEvent | undefined);
+
+  return player;
+}