react-native-transparent-video-player 0.3.2

package/lib/TransparentVideoView.android.d.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+import type { ImplProps } from './types';
+/**
+ * Android implementation: native ExoPlayer + OpenGL (samplerExternalOES)
+ * view. Skia's useVideo is NOT used on Android — its HardwareBuffer importer
+ * cannot sample the YUV/vendor formats hardware decoders emit.
+ */
+export declare function TransparentVideoView({ uri, width, height, loop, paused, style, onEnd, }: ImplProps): React.JSX.Element;

package/lib/TransparentVideoView.android.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransparentVideoView = TransparentVideoView;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const expo_modules_core_1 = require("expo-modules-core");
+const react_1 = require("react");
+const react_native_reanimated_1 = require("react-native-reanimated");
+const NativeView = (0, expo_modules_core_1.requireNativeViewManager)('TransparentVideo');
+// The native view takes a plain boolean; bridge a Reanimated SharedValue
+// (supported for API parity with the iOS Skia path) into React state.
+function useResolvedPaused(paused) {
+    const isShared = typeof paused === 'object' && paused !== null;
+    const [fromShared, setFromShared] = (0, react_1.useState)(isShared ? paused.value : false);
+    (0, react_native_reanimated_1.useAnimatedReaction)(() => (isShared ? paused.value : false), (value, previous) => {
+        if (isShared && value !== previous)
+            (0, react_native_reanimated_1.runOnJS)(setFromShared)(value);
+    }, [paused, isShared]);
+    return isShared ? fromShared : paused;
+}
+/**
+ * Android implementation: native ExoPlayer + OpenGL (samplerExternalOES)
+ * view. Skia's useVideo is NOT used on Android — its HardwareBuffer importer
+ * cannot sample the YUV/vendor formats hardware decoders emit.
+ */
+function TransparentVideoView({ uri, width, height, loop, paused, style, onEnd, }) {
+    const pausedBool = useResolvedPaused(paused);
+    return ((0, jsx_runtime_1.jsx)(NativeView, { sourceUri: uri, loop: loop, paused: pausedBool, onVideoEnd: onEnd, style: [{ width, height }, style] }));
+}

package/lib/TransparentVideoView.d.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+import type { ImplProps } from './types';
+/**
+ * iOS/web implementation: Skia canvas + RuntimeEffect unpack shader.
+ * (Android uses the native ExoPlayer + OpenGL view instead — see
+ * TransparentVideoView.android.tsx.)
+ */
+export declare function TransparentVideoView({ uri, width, height, loop, paused, style, }: ImplProps): React.JSX.Element;

package/lib/TransparentVideoView.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransparentVideoView = TransparentVideoView;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_native_skia_1 = require("@shopify/react-native-skia");
+const react_1 = require("react");
+const react_native_reanimated_1 = require("react-native-reanimated");
+// Recombines an alpha-packed frame: color sampled from the top half,
+// alpha from the same x in the bottom half. The packed video is encoded
+// with PREMULTIPLIED color (see the pack-alpha-video premultiply step), so
+// the rgb passes through as-is — multiplying again here would darken edges.
+const compiledEffect = react_native_skia_1.Skia.RuntimeEffect.Make(`
+uniform shader video;
+uniform float halfH;
+
+half4 main(float2 xy) {
+  half3 rgb = video.eval(xy).rgb;
+  half  a   = video.eval(float2(xy.x, xy.y + halfH)).r;
+  return half4(rgb, a);
+}
+`);
+if (!compiledEffect) {
+    throw new Error('TransparentVideo: failed to compile alpha-unpack shader');
+}
+const unpackAlphaEffect = compiledEffect;
+/**
+ * iOS/web implementation: Skia canvas + RuntimeEffect unpack shader.
+ * (Android uses the native ExoPlayer + OpenGL view instead — see
+ * TransparentVideoView.android.tsx.)
+ */
+function TransparentVideoView({ uri, width, height, loop, paused, style, }) {
+    const { currentFrame } = (0, react_native_skia_1.useVideo)(uri, { looping: loop, paused });
+    // Until the first frame arrives, the Fill would be painted with Skia's
+    // default paint — opaque black — flashing a black rectangle on mount.
+    // Gate it on first-frame readiness instead; an empty Canvas is transparent.
+    const [ready, setReady] = (0, react_1.useState)(false);
+    (0, react_1.useEffect)(() => setReady(false), [uri]);
+    (0, react_native_reanimated_1.useAnimatedReaction)(() => currentFrame.value !== null, (hasFrame, prev) => {
+        if (hasFrame && !prev)
+            (0, react_native_reanimated_1.runOnJS)(setReady)(true);
+    }, [currentFrame]);
+    return ((0, jsx_runtime_1.jsx)(react_native_skia_1.Canvas, { style: [{ width, height }, style], children: ready ? ((0, jsx_runtime_1.jsx)(react_native_skia_1.Fill, { children: (0, jsx_runtime_1.jsx)(react_native_skia_1.Shader, { source: unpackAlphaEffect, uniforms: { halfH: height }, children: (0, jsx_runtime_1.jsx)(react_native_skia_1.ImageShader, { image: currentFrame, fit: "fill", rect: { x: 0, y: 0, width, height: height * 2 } }) }) })) : null }));
+}

package/lib/index.d.ts

@@ -0,0 +1,2 @@
+export { TransparentVideo } from './TransparentVideo';
+export type { TransparentVideoProps } from './TransparentVideo';

package/lib/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransparentVideo = void 0;
+var TransparentVideo_1 = require("./TransparentVideo");
+Object.defineProperty(exports, "TransparentVideo", { enumerable: true, get: function () { return TransparentVideo_1.TransparentVideo; } });

package/lib/types.d.ts

@@ -0,0 +1,19 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+import type { SharedValue } from 'react-native-reanimated';
+/**
+ * Props of the internal per-platform view implementation. Both
+ * TransparentVideoView.tsx (iOS/web, Skia) and
+ * TransparentVideoView.android.tsx (native ExoPlayer + OpenGL) must satisfy
+ * this exact signature so TypeScript checks them interchangeably.
+ */
+export interface ImplProps {
+    /** Already-resolved playable URI (file:// or http(s)), or null while resolving. */
+    uri: string | null;
+    width: number;
+    height: number;
+    loop: boolean;
+    paused: SharedValue<boolean> | boolean;
+    style?: StyleProp<ViewStyle>;
+    /** Fires when a non-looping video finishes. Currently Android-only. */
+    onEnd?: () => void;
+}

package/lib/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/useResolvedUri.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Resolves an asset module to a playable URI. Prefers expo-asset when it is
+ * installed (downloads the asset to the local filesystem, which the video
+ * decoder needs in release builds); falls back to React Native's
+ * Image.resolveAssetSource for bare RN apps without expo-asset.
+ */
+export declare function useResolvedUri(source: number | string): string | null;

package/lib/useResolvedUri.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useResolvedUri = useResolvedUri;
+const react_1 = require("react");
+const react_native_1 = require("react-native");
+/**
+ * Resolves an asset module to a playable URI. Prefers expo-asset when it is
+ * installed (downloads the asset to the local filesystem, which the video
+ * decoder needs in release builds); falls back to React Native's
+ * Image.resolveAssetSource for bare RN apps without expo-asset.
+ */
+function useResolvedUri(source) {
+    const [uri, setUri] = (0, react_1.useState)(typeof source === 'string' ? source : null);
+    (0, react_1.useEffect)(() => {
+        if (typeof source === 'string') {
+            setUri(source);
+            return;
+        }
+        let cancelled = false;
+        let expoAsset = null;
+        try {
+            expoAsset = require('expo-asset');
+        }
+        catch {
+            expoAsset = null;
+        }
+        if (expoAsset) {
+            expoAsset.Asset.fromModule(source)
+                .downloadAsync()
+                .then((asset) => {
+                if (!cancelled)
+                    setUri(asset.localUri ?? asset.uri);
+            })
+                .catch((e) => {
+                console.error('TransparentVideo: failed to resolve asset', e);
+            });
+        }
+        else {
+            const resolved = react_native_1.Image.resolveAssetSource(source);
+            if (resolved?.uri)
+                setUri(resolved.uri);
+            else
+                console.error('TransparentVideo: could not resolve asset module');
+        }
+        return () => {
+            cancelled = true;
+        };
+    }, [source]);
+    return uri;
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "react-native-transparent-video-player",
+  "version": "0.3.2",
+  "description": "Transparent (alpha) video playback for React Native — plays alpha-packed H.264 MP4s on every iOS/Android hardware decoder. Skia-rendered on iOS, native ExoPlayer+OpenGL view on Android. Includes a CLI to pack ProRes 4444 exports.",
+  "license": "MIT",
+  "author": "LucaL1fe",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LucaL1fe/react-native-transparent-video-player.git",
+    "directory": "packages/react-native-transparent-video-player"
+  },
+  "homepage": "https://github.com/LucaL1fe/react-native-transparent-video-player",
+  "keywords": [
+    "react-native",
+    "expo",
+    "skia",
+    "transparent-video",
+    "alpha",
+    "animation",
+    "mascot",
+    "webp-alternative",
+    "gif-alternative"
+  ],
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib",
+    "cli",
+    "src",
+    "android/build.gradle",
+    "android/src",
+    "expo-module.config.json",
+    "THIRD-PARTY-NOTICES.md"
+  ],
+  "bin": {
+    "pack-transparent-video": "cli/pack-transparent-video.mjs"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@shopify/react-native-skia": ">=1.5.0",
+    "expo-asset": "*",
+    "react": ">=18",
+    "react-native": ">=0.74",
+    "react-native-reanimated": ">=3.0.0",
+    "expo-modules-core": "*"
+  },
+  "peerDependenciesMeta": {
+    "expo-asset": {
+      "optional": true
+    },
+    "expo-modules-core": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@shopify/react-native-skia": "^2.2.12",
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0",
+    "react-native": "^0.86.0",
+    "react-native-reanimated": "^4.0.0",
+    "typescript": "^5.6.0",
+    "expo-modules-core": "~57.0.3"
+  }
+}

package/src/TransparentVideo.tsx

@@ -0,0 +1,60 @@
+import React from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+import type { SharedValue } from 'react-native-reanimated';
+
+import { TransparentVideoView } from './TransparentVideoView';
+import { useResolvedUri } from './useResolvedUri';
+
+export interface TransparentVideoProps {
+  /**
+   * An alpha-packed video (color on the top half, grayscale matte on the
+   * bottom half): either a bundled asset module (`require('./x-packed.mp4')`)
+   * or a URI string (file:// or https://).
+   */
+  source: number | string;
+  /** Display width. The packed video's own height is 2x its visible height. */
+  width: number;
+  /** Display height (half the packed video's pixel height). */
+  height: number;
+  /** Loop playback (default true). Set false for one-shot animations. */
+  loop?: boolean;
+  paused?: SharedValue<boolean> | boolean;
+  style?: StyleProp<ViewStyle>;
+  /**
+   * Fires when a non-looping video finishes playing.
+   * Currently Android-only (native player event); on iOS it never fires —
+   * time-based fallbacks remain the caller's responsibility there.
+   */
+  onEnd?: () => void;
+}
+
+/**
+ * Plays an alpha-packed MP4 with real transparency.
+ *
+ * Platform split: iOS/web render through Skia (RuntimeEffect unpack shader);
+ * Android uses a native ExoPlayer + OpenGL view (Metro resolves
+ * ./TransparentVideoView to the .android implementation there).
+ */
+export function TransparentVideo({
+  source,
+  width,
+  height,
+  loop = true,
+  paused = false,
+  style,
+  onEnd,
+}: TransparentVideoProps) {
+  const uri = useResolvedUri(source);
+
+  return (
+    <TransparentVideoView
+      uri={uri}
+      width={width}
+      height={height}
+      loop={loop}
+      paused={paused}
+      style={style}
+      onEnd={onEnd}
+    />
+  );
+}

package/src/TransparentVideoView.android.tsx

@@ -0,0 +1,61 @@
+import { requireNativeViewManager } from 'expo-modules-core';
+import React, { useState } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+import { runOnJS, useAnimatedReaction } from 'react-native-reanimated';
+import type { SharedValue } from 'react-native-reanimated';
+
+import type { ImplProps } from './types';
+
+interface NativeProps {
+  sourceUri: string | null;
+  loop: boolean;
+  paused: boolean;
+  onVideoEnd?: () => void;
+  style?: StyleProp<ViewStyle>;
+}
+
+const NativeView = requireNativeViewManager<NativeProps>('TransparentVideo');
+
+// The native view takes a plain boolean; bridge a Reanimated SharedValue
+// (supported for API parity with the iOS Skia path) into React state.
+function useResolvedPaused(paused: SharedValue<boolean> | boolean): boolean {
+  const isShared = typeof paused === 'object' && paused !== null;
+  const [fromShared, setFromShared] = useState(
+    isShared ? (paused as SharedValue<boolean>).value : false
+  );
+  useAnimatedReaction(
+    () => (isShared ? (paused as SharedValue<boolean>).value : false),
+    (value, previous) => {
+      if (isShared && value !== previous) runOnJS(setFromShared)(value);
+    },
+    [paused, isShared]
+  );
+  return isShared ? fromShared : (paused as boolean);
+}
+
+/**
+ * Android implementation: native ExoPlayer + OpenGL (samplerExternalOES)
+ * view. Skia's useVideo is NOT used on Android — its HardwareBuffer importer
+ * cannot sample the YUV/vendor formats hardware decoders emit.
+ */
+export function TransparentVideoView({
+  uri,
+  width,
+  height,
+  loop,
+  paused,
+  style,
+  onEnd,
+}: ImplProps) {
+  const pausedBool = useResolvedPaused(paused);
+
+  return (
+    <NativeView
+      sourceUri={uri}
+      loop={loop}
+      paused={pausedBool}
+      onVideoEnd={onEnd}
+      style={[{ width, height }, style]}
+    />
+  );
+}

package/src/TransparentVideoView.tsx

@@ -0,0 +1,77 @@
+import {
+  Canvas,
+  Fill,
+  ImageShader,
+  Shader,
+  Skia,
+  useVideo,
+} from '@shopify/react-native-skia';
+import React, { useEffect, useState } from 'react';
+import { runOnJS, useAnimatedReaction } from 'react-native-reanimated';
+
+import type { ImplProps } from './types';
+
+// Recombines an alpha-packed frame: color sampled from the top half,
+// alpha from the same x in the bottom half. The packed video is encoded
+// with PREMULTIPLIED color (see the pack-alpha-video premultiply step), so
+// the rgb passes through as-is — multiplying again here would darken edges.
+const compiledEffect = Skia.RuntimeEffect.Make(`
+uniform shader video;
+uniform float halfH;
+
+half4 main(float2 xy) {
+  half3 rgb = video.eval(xy).rgb;
+  half  a   = video.eval(float2(xy.x, xy.y + halfH)).r;
+  return half4(rgb, a);
+}
+`);
+
+if (!compiledEffect) {
+  throw new Error('TransparentVideo: failed to compile alpha-unpack shader');
+}
+const unpackAlphaEffect = compiledEffect;
+
+/**
+ * iOS/web implementation: Skia canvas + RuntimeEffect unpack shader.
+ * (Android uses the native ExoPlayer + OpenGL view instead — see
+ * TransparentVideoView.android.tsx.)
+ */
+export function TransparentVideoView({
+  uri,
+  width,
+  height,
+  loop,
+  paused,
+  style,
+}: ImplProps) {
+  const { currentFrame } = useVideo(uri, { looping: loop, paused });
+
+  // Until the first frame arrives, the Fill would be painted with Skia's
+  // default paint — opaque black — flashing a black rectangle on mount.
+  // Gate it on first-frame readiness instead; an empty Canvas is transparent.
+  const [ready, setReady] = useState(false);
+  useEffect(() => setReady(false), [uri]);
+  useAnimatedReaction(
+    () => currentFrame.value !== null,
+    (hasFrame, prev) => {
+      if (hasFrame && !prev) runOnJS(setReady)(true);
+    },
+    [currentFrame]
+  );
+
+  return (
+    <Canvas style={[{ width, height }, style]}>
+      {ready ? (
+        <Fill>
+          <Shader source={unpackAlphaEffect} uniforms={{ halfH: height }}>
+            <ImageShader
+              image={currentFrame}
+              fit="fill"
+              rect={{ x: 0, y: 0, width, height: height * 2 }}
+            />
+          </Shader>
+        </Fill>
+      ) : null}
+    </Canvas>
+  );
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { TransparentVideo } from './TransparentVideo';
+export type { TransparentVideoProps } from './TransparentVideo';

package/src/types.ts

@@ -0,0 +1,20 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+import type { SharedValue } from 'react-native-reanimated';
+
+/**
+ * Props of the internal per-platform view implementation. Both
+ * TransparentVideoView.tsx (iOS/web, Skia) and
+ * TransparentVideoView.android.tsx (native ExoPlayer + OpenGL) must satisfy
+ * this exact signature so TypeScript checks them interchangeably.
+ */
+export interface ImplProps {
+  /** Already-resolved playable URI (file:// or http(s)), or null while resolving. */
+  uri: string | null;
+  width: number;
+  height: number;
+  loop: boolean;
+  paused: SharedValue<boolean> | boolean;
+  style?: StyleProp<ViewStyle>;
+  /** Fires when a non-looping video finishes. Currently Android-only. */
+  onEnd?: () => void;
+}

package/src/useResolvedUri.ts

@@ -0,0 +1,60 @@
+import { useEffect, useState } from 'react';
+import { Image } from 'react-native';
+
+// Minimal surface of expo-asset used below — typed locally so the package
+// compiles without expo-asset installed (it is an optional peer).
+interface ExpoAssetModule {
+  Asset: {
+    fromModule(module: number): {
+      downloadAsync(): Promise<{ localUri: string | null; uri: string }>;
+    };
+  };
+}
+
+/**
+ * Resolves an asset module to a playable URI. Prefers expo-asset when it is
+ * installed (downloads the asset to the local filesystem, which the video
+ * decoder needs in release builds); falls back to React Native's
+ * Image.resolveAssetSource for bare RN apps without expo-asset.
+ */
+export function useResolvedUri(source: number | string): string | null {
+  const [uri, setUri] = useState<string | null>(
+    typeof source === 'string' ? source : null
+  );
+
+  useEffect(() => {
+    if (typeof source === 'string') {
+      setUri(source);
+      return;
+    }
+    let cancelled = false;
+
+    let expoAsset: ExpoAssetModule | null = null;
+    try {
+      expoAsset = require('expo-asset') as ExpoAssetModule;
+    } catch {
+      expoAsset = null;
+    }
+
+    if (expoAsset) {
+      expoAsset.Asset.fromModule(source)
+        .downloadAsync()
+        .then((asset) => {
+          if (!cancelled) setUri(asset.localUri ?? asset.uri);
+        })
+        .catch((e: unknown) => {
+          console.error('TransparentVideo: failed to resolve asset', e);
+        });
+    } else {
+      const resolved = Image.resolveAssetSource(source);
+      if (resolved?.uri) setUri(resolved.uri);
+      else console.error('TransparentVideo: could not resolve asset module');
+    }
+
+    return () => {
+      cancelled = true;
+    };
+  }, [source]);
+
+  return uri;
+}