react-native-transparent-video-player 0.3.2

package/android/src/main/java/expo/modules/transparentvideo/TransparentVideoModule.kt

@@ -0,0 +1,30 @@
+package expo.modules.transparentvideo
+
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+
+class TransparentVideoModule : Module() {
+  override fun definition() = ModuleDefinition {
+    Name("TransparentVideo")
+
+    View(TransparentVideoView::class) {
+      Events("onVideoEnd")
+
+      Prop("sourceUri") { view: TransparentVideoView, uri: String? ->
+        view.setSource(uri)
+      }
+
+      Prop("loop") { view: TransparentVideoView, loop: Boolean ->
+        view.loop = loop
+      }
+
+      Prop("paused") { view: TransparentVideoView, paused: Boolean ->
+        view.paused = paused
+      }
+
+      OnViewDestroys { view: TransparentVideoView ->
+        view.release()
+      }
+    }
+  }
+}

package/android/src/main/java/expo/modules/transparentvideo/TransparentVideoRenderer.kt

@@ -0,0 +1,246 @@
+/*
+ * Derived from alpha-movie's VideoRenderer
+ * (https://github.com/pavelsiamak/alpha-movie, Copyright 2017 Pavel Semak),
+ * licensed under the Apache License, Version 2.0:
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Modifications for react-native-transparent-video-skia:
+ * - Kotlin port, packed top-color/bottom-alpha shader (after
+ *   status-im/react-native-transparent-video, MIT)
+ * - premultiplied-alpha output: blending disabled, rgb passed through as-is
+ * - Surface handed to the host view via callback instead of a listener chain
+ */
+package expo.modules.transparentvideo
+
+import android.graphics.SurfaceTexture
+import android.opengl.GLES20
+import android.opengl.Matrix
+import android.view.Surface
+import com.alphamovie.lib.GLTextureView
+import java.nio.ByteBuffer
+import java.nio.ByteOrder
+import java.nio.FloatBuffer
+import javax.microedition.khronos.egl.EGLConfig
+import javax.microedition.khronos.opengles.GL10
+
+private const val FLOAT_SIZE_BYTES = 4
+private const val VERTICES_STRIDE_BYTES = 5 * FLOAT_SIZE_BYTES
+private const val VERTICES_POS_OFFSET = 0
+private const val VERTICES_UV_OFFSET = 3
+private const val GL_TEXTURE_EXTERNAL_OES = 0x8D65
+
+// The halves-split must happen in CONTENT space and only then go through the
+// SurfaceTexture transform (uSTMatrix): decoders pad the buffer to 16-row
+// alignment (e.g. 1800 -> 1808), so the matrix carries a crop scale — applying
+// the split after the transform misaligns the alpha matte by several pixels.
+private const val VERTEX_SHADER = """
+uniform mat4 uMVPMatrix;
+uniform mat4 uSTMatrix;
+attribute vec4 aPosition;
+attribute vec4 aTextureCoord;
+varying vec2 vColorCoord;
+varying vec2 vAlphaCoord;
+void main() {
+  gl_Position = uMVPMatrix * aPosition;
+  // SurfaceTexture content space: t=0 is the image BOTTOM. The packed video
+  // shows color on top (t in [0.5, 1]) and the alpha matte below (t in [0, 0.5]).
+  vColorCoord = (uSTMatrix * vec4(aTextureCoord.x, 0.5 + aTextureCoord.y * 0.5, 0.0, 1.0)).xy;
+  vAlphaCoord = (uSTMatrix * vec4(aTextureCoord.x, aTextureCoord.y * 0.5, 0.0, 1.0)).xy;
+}
+"""
+
+// Packed layout: premultiplied color in the top half, alpha matte in the
+// bottom half (content space). rgb is ALREADY premultiplied by the
+// pack-alpha-video CLI — pass it through; multiplying by alpha again
+// would darken antialiased edges.
+private const val FRAGMENT_SHADER = """
+#extension GL_OES_EGL_image_external : require
+precision mediump float;
+varying vec2 vColorCoord;
+varying vec2 vAlphaCoord;
+uniform samplerExternalOES sTexture;
+void main() {
+  vec4 color  = texture2D(sTexture, vColorCoord);
+  float alpha = texture2D(sTexture, vAlphaCoord).r;
+  gl_FragColor = vec4(color.rgb, alpha);
+}
+"""
+
+class TransparentVideoRenderer : GLTextureView.Renderer {
+
+  /** Called on the GL thread whenever a new decoder frame is ready. */
+  var onRequestRender: (() -> Unit)? = null
+
+  /**
+   * Called on the GL thread with a Surface wrapping the freshly created
+   * SurfaceTexture. Fires again after every EGL surface recreation
+   * (view detach/reattach) — the host must re-bind it to the player.
+   */
+  var onSurfaceReady: ((Surface) -> Unit)? = null
+
+  private val triangleVerticesData = floatArrayOf(
+    // x, y, z, u, v
+    -1.0f, -1.0f, 0f, 0f, 0f,
+    1.0f, -1.0f, 0f, 1f, 0f,
+    -1.0f, 1.0f, 0f, 0f, 1f,
+    1.0f, 1.0f, 0f, 1f, 1f,
+  )
+  private val triangleVertices: FloatBuffer = ByteBuffer
+    .allocateDirect(triangleVerticesData.size * FLOAT_SIZE_BYTES)
+    .order(ByteOrder.nativeOrder())
+    .asFloatBuffer()
+    .apply { put(triangleVerticesData).position(0) }
+
+  private val mvpMatrix = FloatArray(16)
+  private val stMatrix = FloatArray(16)
+
+  private var program = 0
+  private var textureId = 0
+  private var mvpMatrixHandle = 0
+  private var stMatrixHandle = 0
+  private var positionHandle = 0
+  private var textureCoordHandle = 0
+
+  private var surfaceTexture: SurfaceTexture? = null
+
+  @Volatile
+  private var frameAvailable = false
+  private val frameLock = Any()
+
+  override fun onSurfaceCreated(gl: GL10?, config: EGLConfig?) {
+    program = createProgram(VERTEX_SHADER, FRAGMENT_SHADER)
+    check(program != 0) { "TransparentVideoRenderer: failed to create GL program" }
+
+    positionHandle = GLES20.glGetAttribLocation(program, "aPosition")
+    textureCoordHandle = GLES20.glGetAttribLocation(program, "aTextureCoord")
+    mvpMatrixHandle = GLES20.glGetUniformLocation(program, "uMVPMatrix")
+    stMatrixHandle = GLES20.glGetUniformLocation(program, "uSTMatrix")
+
+    val textures = IntArray(1)
+    GLES20.glGenTextures(1, textures, 0)
+    textureId = textures[0]
+    GLES20.glBindTexture(GL_TEXTURE_EXTERNAL_OES, textureId)
+    GLES20.glTexParameterf(
+      GL_TEXTURE_EXTERNAL_OES, GLES20.GL_TEXTURE_MIN_FILTER, GLES20.GL_LINEAR.toFloat()
+    )
+    GLES20.glTexParameterf(
+      GL_TEXTURE_EXTERNAL_OES, GLES20.GL_TEXTURE_MAG_FILTER, GLES20.GL_LINEAR.toFloat()
+    )
+    GLES20.glTexParameteri(
+      GL_TEXTURE_EXTERNAL_OES, GLES20.GL_TEXTURE_WRAP_S, GLES20.GL_CLAMP_TO_EDGE
+    )
+    GLES20.glTexParameteri(
+      GL_TEXTURE_EXTERNAL_OES, GLES20.GL_TEXTURE_WRAP_T, GLES20.GL_CLAMP_TO_EDGE
+    )
+
+    Matrix.setIdentityM(stMatrix, 0)
+    Matrix.setIdentityM(mvpMatrix, 0)
+
+    // Release any previous SurfaceTexture (EGL context was lost/recreated).
+    surfaceTexture?.release()
+    val st = SurfaceTexture(textureId)
+    st.setOnFrameAvailableListener {
+      synchronized(frameLock) { frameAvailable = true }
+      onRequestRender?.invoke()
+    }
+    surfaceTexture = st
+
+    onSurfaceReady?.invoke(Surface(st))
+  }
+
+  override fun onSurfaceChanged(gl: GL10?, width: Int, height: Int) {
+    GLES20.glViewport(0, 0, width, height)
+  }
+
+  // GLTextureView extension over stock GLSurfaceView.Renderer: called on the
+  // GL thread when the EGL surface goes away (view detach). The SurfaceTexture
+  // belongs to the dying GL context; a fresh one is created in the next
+  // onSurfaceCreated and re-handed to the player via onSurfaceReady.
+  override fun onSurfaceDestroyed(gl: GL10?) {
+    synchronized(frameLock) { frameAvailable = false }
+    surfaceTexture?.release()
+    surfaceTexture = null
+  }
+
+  override fun onDrawFrame(gl: GL10?) {
+    synchronized(frameLock) {
+      if (frameAvailable) {
+        surfaceTexture?.updateTexImage()
+        surfaceTexture?.getTransformMatrix(stMatrix)
+        frameAvailable = false
+      }
+    }
+
+    // Transparent black is valid premultiplied "nothing".
+    GLES20.glClearColor(0f, 0f, 0f, 0f)
+    GLES20.glClear(GLES20.GL_DEPTH_BUFFER_BIT or GLES20.GL_COLOR_BUFFER_BIT)
+
+    // Output is premultiplied and the quad covers the whole (cleared)
+    // surface — no in-surface blending needed. The Android compositor
+    // blends the TextureView's premultiplied pixels with what's behind it.
+    GLES20.glDisable(GLES20.GL_BLEND)
+
+    GLES20.glUseProgram(program)
+    GLES20.glActiveTexture(GLES20.GL_TEXTURE0)
+    GLES20.glBindTexture(GL_TEXTURE_EXTERNAL_OES, textureId)
+
+    triangleVertices.position(VERTICES_POS_OFFSET)
+    GLES20.glVertexAttribPointer(
+      positionHandle, 3, GLES20.GL_FLOAT, false, VERTICES_STRIDE_BYTES, triangleVertices
+    )
+    GLES20.glEnableVertexAttribArray(positionHandle)
+
+    triangleVertices.position(VERTICES_UV_OFFSET)
+    GLES20.glVertexAttribPointer(
+      textureCoordHandle, 2, GLES20.GL_FLOAT, false, VERTICES_STRIDE_BYTES, triangleVertices
+    )
+    GLES20.glEnableVertexAttribArray(textureCoordHandle)
+
+    GLES20.glUniformMatrix4fv(mvpMatrixHandle, 1, false, mvpMatrix, 0)
+    GLES20.glUniformMatrix4fv(stMatrixHandle, 1, false, stMatrix, 0)
+
+    GLES20.glDrawArrays(GLES20.GL_TRIANGLE_STRIP, 0, 4)
+    GLES20.glFinish()
+  }
+
+  fun release() {
+    surfaceTexture?.release()
+    surfaceTexture = null
+  }
+
+  private fun createProgram(vertexSource: String, fragmentSource: String): Int {
+    val vertexShader = loadShader(GLES20.GL_VERTEX_SHADER, vertexSource)
+    if (vertexShader == 0) return 0
+    val pixelShader = loadShader(GLES20.GL_FRAGMENT_SHADER, fragmentSource)
+    if (pixelShader == 0) return 0
+
+    var program = GLES20.glCreateProgram()
+    if (program == 0) return 0
+    GLES20.glAttachShader(program, vertexShader)
+    GLES20.glAttachShader(program, pixelShader)
+    GLES20.glLinkProgram(program)
+    val linkStatus = IntArray(1)
+    GLES20.glGetProgramiv(program, GLES20.GL_LINK_STATUS, linkStatus, 0)
+    if (linkStatus[0] != GLES20.GL_TRUE) {
+      android.util.Log.e("TransparentVideo", "Could not link program: " + GLES20.glGetProgramInfoLog(program))
+      GLES20.glDeleteProgram(program)
+      program = 0
+    }
+    return program
+  }
+
+  private fun loadShader(shaderType: Int, source: String): Int {
+    var shader = GLES20.glCreateShader(shaderType)
+    if (shader == 0) return 0
+    GLES20.glShaderSource(shader, source)
+    GLES20.glCompileShader(shader)
+    val compiled = IntArray(1)
+    GLES20.glGetShaderiv(shader, GLES20.GL_COMPILE_STATUS, compiled, 0)
+    if (compiled[0] == 0) {
+      android.util.Log.e("TransparentVideo", "Could not compile shader $shaderType: " + GLES20.glGetShaderInfoLog(shader))
+      GLES20.glDeleteShader(shader)
+      shader = 0
+    }
+    return shader
+  }
+}

package/android/src/main/java/expo/modules/transparentvideo/TransparentVideoView.kt

@@ -0,0 +1,101 @@
+package expo.modules.transparentvideo
+
+import android.content.Context
+import android.view.Surface
+import androidx.media3.common.AudioAttributes
+import androidx.media3.common.MediaItem
+import androidx.media3.common.Player
+import androidx.media3.exoplayer.ExoPlayer
+import expo.modules.kotlin.AppContext
+import expo.modules.kotlin.viewevent.EventDispatcher
+import expo.modules.kotlin.views.ExpoView
+import com.alphamovie.lib.GLTextureView
+
+class TransparentVideoView(context: Context, appContext: AppContext) : ExpoView(context, appContext) {
+  private val onVideoEnd by EventDispatcher()
+
+  private val renderer = TransparentVideoRenderer()
+  private val textureView = GLTextureView(context).apply {
+    // Order matters: EGL configuration must precede setRenderer.
+    setEGLContextClientVersion(2)
+    // RGBA8888 — the EGL surface needs a real alpha channel for transparency.
+    setEGLConfigChooser(8, 8, 8, 8, 16, 0)
+    isOpaque = false
+    setPreserveEGLContextOnPause(true)
+  }
+
+  private var player: ExoPlayer? = null
+  private var surface: Surface? = null
+  private var sourceUri: String? = null
+
+  var loop: Boolean = true
+    set(value) {
+      field = value
+      player?.repeatMode = if (value) Player.REPEAT_MODE_ONE else Player.REPEAT_MODE_OFF
+    }
+
+  var paused: Boolean = false
+    set(value) {
+      field = value
+      player?.playWhenReady = !value
+    }
+
+  init {
+    renderer.onRequestRender = { textureView.requestRender() }
+    // Fires on the GL thread on every EGL (re)creation — including view
+    // reattach after RN detached us. Re-bind the fresh Surface each time.
+    renderer.onSurfaceReady = { s ->
+      post {
+        surface?.release()
+        surface = s
+        attachSurfaceAndMaybePrepare()
+      }
+    }
+    textureView.setRenderer(renderer)
+    textureView.renderMode = GLTextureView.RENDERMODE_WHEN_DIRTY
+    addView(textureView, LayoutParams(LayoutParams.MATCH_PARENT, LayoutParams.MATCH_PARENT))
+  }
+
+  fun setSource(uri: String?) {
+    sourceUri = uri
+    attachSurfaceAndMaybePrepare()
+  }
+
+  // Main thread only — ExoPlayer is single-threaded by contract.
+  private fun attachSurfaceAndMaybePrepare() {
+    val uri = sourceUri ?: return
+    val p = player ?: ExoPlayer.Builder(context).build().also { built ->
+      // Silent transparent clips must never take audio focus or duck music.
+      built.setAudioAttributes(AudioAttributes.DEFAULT, false)
+      built.volume = 0f
+      built.addListener(object : Player.Listener {
+        override fun onPlaybackStateChanged(playbackState: Int) {
+          if (playbackState == Player.STATE_ENDED) {
+            onVideoEnd(mapOf())
+          }
+        }
+      })
+      player = built
+    }
+    surface?.let { p.setVideoSurface(it) }
+    p.repeatMode = if (loop) Player.REPEAT_MODE_ONE else Player.REPEAT_MODE_OFF
+    if (p.currentMediaItem?.localConfiguration?.uri?.toString() != uri) {
+      p.setMediaItem(MediaItem.fromUri(uri))
+      p.prepare()
+    }
+    p.playWhenReady = !paused
+  }
+
+  // Called from OnViewDestroys (main thread) when RN destroys the view for
+  // good. NOT called on mere detach — the player intentionally survives
+  // detach/reattach cycles (lists, tab switches); only the EGL surface is
+  // recreated, and onSurfaceReady re-binds it.
+  fun release() {
+    player?.clearVideoSurface()
+    player?.release()
+    player = null
+    surface?.release()
+    surface = null
+    renderer.release()
+  }
+}

package/cli/pack-transparent-video.mjs

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+/**
+ * pack-transparent-video — convert any video with an alpha channel (ProRes 4444,
+ * VP9/VP8 WebM, PNG/QTRLE/FFV1/Ut Video in .mov/.mkv/.avi) into an
+ * "alpha-packed" MP4 for <TransparentVideo>.
+ *
+ * The trick: the output MP4 is a completely normal H.264 video, twice as tall
+ * as the source. Top half = the color image (premultiplied), bottom half = the
+ * alpha channel repainted as a grayscale matte. At render time a Skia shader
+ * recombines the halves into a transparent image on the GPU. No codec alpha
+ * support needed → plays on every iOS/Android hardware decoder.
+ *
+ * Works on Windows, macOS and Linux; needs ffmpeg + ffprobe in PATH.
+ *
+ * Usage:
+ *   npx pack-transparent-video <input.mov> [more.webm ...] [options]
+ *
+ * Options:
+ *   -o, --out-dir <dir>    output directory                       (default: cwd)
+ *       --fps <n>          frame rate of the packed output        (default: 24)
+ *       --quality <0-100>  quality in percent, 75 ≈ visually lossless (default: 75)
+ *       --scale <percent>  resize to this % of the source size    (default: 100)
+ *       --width <px>       or: resize to exact width, keeps aspect
+ *       --size <WxH>       or: exact output frame from any aspect ratio —
+ *                          scales to fit and pads with TRANSPARENT pixels
+ *       --crf <n>          advanced: raw x264 CRF, overrides --quality
+ *
+ * The output height must be divisible by 8 (packed height by 16) — Android
+ * hardware decoders align buffers to 16 rows, and non-aligned packed videos
+ * get a crop transform that shifts the alpha mask ~1px against the color.
+ * The CLI refuses misaligned resolutions and suggests the nearest valid one.
+ *
+ * Output: <out-dir>/<name>-packed.mp4 (a trailing "-4444" is stripped from
+ * the name). Prints the <TransparentVideo> line to paste into your app.
+ *
+ * Recommended source export (any editor/motion tool): QuickTime with
+ * "Apple ProRes 4444" and the alpha channel enabled, at display resolution
+ * (e.g. 900×900), 24–30 fps.
+ */
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+
+function run(bin, args) {
+  return execFileSync(bin, args, { encoding: 'utf8' }).trim();
+}
+
+function fail(msg) {
+  console.error(`✖ ${msg}`);
+  process.exit(1);
+}
+
+// ---- args -------------------------------------------------------------------
+let parsed;
+try {
+  parsed = parseArgs({
+    allowPositionals: true,
+    options: {
+      'out-dir': { type: 'string', short: 'o', default: process.cwd() },
+      fps: { type: 'string', default: '24' },
+      quality: { type: 'string', default: '75' },
+      scale: { type: 'string', default: '' },
+      width: { type: 'string', default: '' },
+      size: { type: 'string', default: '' },
+      crf: { type: 'string', default: '' },
+      help: { type: 'boolean', short: 'h', default: false },
+    },
+  });
+} catch (e) {
+  fail(e.message);
+}
+const { values, positionals: inputs } = parsed;
+
+if (values.help || inputs.length === 0) {
+  console.log(
+    `Usage: pack-transparent-video <input-with-alpha> [...] [options]
+  -o, --out-dir <dir>    output directory                    (default: cwd)
+      --fps <n>          output frame rate                   (default: 24)
+      --quality <0-100>  quality %, 75 ≈ visually lossless   (default: 75)
+      --scale <percent>  resize to % of source size          (default: 100)
+      --width <px>       or: exact output width, keeps aspect
+      --size <WxH>       or: exact frame (e.g. 900x900) — fits + transparent padding
+      --crf <n>          advanced: raw x264 CRF, overrides --quality`
+  );
+  process.exit(values.help ? 0 : 1);
+}
+
+const OUT_DIR = path.resolve(values['out-dir']);
+const FPS = values.fps;
+
+// Quality percentage → x264 CRF. 100% → 14 (near lossless), 75% → 18
+// (visually lossless, the recommended default), 0% → 30 (small but rough).
+const quality = Math.min(100, Math.max(0, Number(values.quality)));
+if (Number.isNaN(quality)) fail(`--quality must be a number 0-100, got: ${values.quality}`);
+const CRF = values.crf !== '' ? values.crf : String(Math.round(30 - quality * 0.16));
+
+const scalePct = values.scale !== '' ? Number(values.scale) : 100;
+if (Number.isNaN(scalePct) || scalePct <= 0 || scalePct > 400) {
+  fail(`--scale must be a percentage between 1 and 400, got: ${values.scale}`);
+}
+
+let sizeW = 0;
+let sizeH = 0;
+if (values.size !== '') {
+  const m = values.size.match(/^(\d+)x(\d+)$/i);
+  if (!m) fail(`--size must look like 900x900, got: ${values.size}`);
+  sizeW = 2 * Math.round(Number(m[1]) / 2);
+  sizeH = 2 * Math.round(Number(m[2]) / 2);
+}
+
+// ---- preflight ------------------------------------------------------------
+try {
+  run('ffmpeg', ['-version']);
+} catch {
+  fail(
+    'ffmpeg not found — install it first:\n' +
+      '  macOS:   brew install ffmpeg\n' +
+      '  Windows: winget install ffmpeg\n' +
+      '  Linux:   sudo apt install ffmpeg'
+  );
+}
+
+fs.mkdirSync(OUT_DIR, { recursive: true });
+
+// ---- convert each input ---------------------------------------------------
+for (const input of inputs) {
+  if (!fs.existsSync(input)) fail(`input not found: ${input}`);
+
+  // Verify the source actually carries alpha. Most codecs signal it in
+  // pix_fmt; VP8/VP9 WebM signals it via the alpha_mode container tag (their
+  // pix_fmt reads yuv420p even when alpha is present).
+  const probe = JSON.parse(
+    run('ffprobe', [
+      '-v', 'error', '-select_streams', 'v:0',
+      '-show_entries', 'stream=codec_name,pix_fmt,width,height:stream_tags=alpha_mode',
+      '-of', 'json', input,
+    ])
+  );
+  const stream = probe.streams?.[0] ?? {};
+  const pixFmt = stream.pix_fmt ?? '';
+  const codec = stream.codec_name ?? '';
+  const srcW = Number(stream.width);
+  const srcH = Number(stream.height);
+  if (!srcW || !srcH) fail(`${path.basename(input)}: could not read video dimensions`);
+  const vpxAlpha = ['vp8', 'vp9'].includes(codec) && stream.tags?.alpha_mode === '1';
+  if (!pixFmt.includes('a') && !vpxAlpha) {
+    fail(
+      `${path.basename(input)} has no alpha channel (codec: ${codec}, pix_fmt: ${pixFmt}).\n` +
+      '  Re-export as ProRes 4444 with the alpha channel enabled (every editor/motion tool supports this).\n' +
+      '  (Plain H.264/HEVC exports have no alpha; HEVC-with-alpha is not supported — use ProRes 4444 or VP9 WebM.)'
+    );
+  }
+
+  // Strip a "4444" token anywhere in the name: raccoon-4444-idle → raccoon-idle
+  const name = path
+    .basename(input, path.extname(input))
+    .replace(/(^|-)4444(?=-|$)/g, '$1')
+    .replace(/--+/g, '-')
+    .replace(/^-|-$/g, '');
+  const outFile = path.join(OUT_DIR, `${name}-packed.mp4`);
+
+  // Resize stage (runs in rgba so padding can be transparent):
+  //  --size:  scale to fit the exact frame, pad the rest with TRANSPARENT
+  //           pixels (alpha 0) — never stretches, works for any aspect ratio
+  //  --width: exact width, height follows aspect
+  //  --scale: percentage of source
+  //  default: no-op even-ing pass (yuv420p + vstack need even dimensions)
+  const even = (n) => Math.round(n / 2) * 2;
+  let outW;
+  let outH;
+  if (sizeW) {
+    outW = sizeW;
+    outH = sizeH;
+  } else if (values.width) {
+    outW = even(Number(values.width));
+    outH = even((srcH * outW) / srcW);
+  } else {
+    outW = even((srcW * scalePct) / 100 - 0.49);
+    outH = even((srcH * outW) / srcW);
+  }
+
+  // The output height MUST be divisible by 8 (packed = 2x → divisible by 16):
+  // Android hardware decoders align video buffers to 16 rows, and a
+  // non-aligned packed video forces a crop transform whose filtering inset
+  // shifts the alpha mask ~1px against the color on every Android device.
+  if (outH % 8 !== 0) {
+    let fix;
+    if (sizeW) {
+      const lo = Math.floor(outH / 8) * 8;
+      const hi = lo + 8;
+      fix = `use --size ${outW}x${lo}${lo > 0 ? '' : ''} or --size ${outW}x${hi}`;
+    } else {
+      const candidates = [];
+      for (let d = 2; d <= 128 && candidates.length < 2; d += 2) {
+        for (const w of [outW - d, outW + d]) {
+          if (w > 0 && even((srcH * w) / srcW) % 8 === 0 && !candidates.includes(w)) {
+            candidates.push(w);
+          }
+        }
+      }
+      candidates.sort((a, b) => Math.abs(a - outW) - Math.abs(b - outW));
+      fix = candidates.length
+        ? `use ${candidates.map((w) => `--width ${w}`).join(' or ')}`
+        : 'pick a resolution whose height is divisible by 8 (e.g. via --size)';
+    }
+    fail(
+      `${path.basename(input)}: output ${outW}x${outH} — height ${outH} is not divisible by 8.\n` +
+        '  Why: Android hardware decoders align video buffers to 16 rows; a packed video\n' +
+        '  whose height is not 16-aligned gets a crop transform that shifts the alpha mask\n' +
+        '  ~1px against the color on every Android device.\n' +
+        `  Fix: ${fix}  (source is ${srcW}x${srcH})`
+    );
+  }
+
+  const resize = sizeW
+    ? `scale=${sizeW}:${sizeH}:force_original_aspect_ratio=decrease:force_divisible_by=2,` +
+      `pad=${sizeW}:${sizeH}:(ow-iw)/2:(oh-ih)/2:color=black@0,`
+    : `scale=${outW}:${outH},`;
+
+  // fps → resize → premultiply color by alpha (kills edge fringe when the
+  // shader samples with bilinear filtering) → split → alphaextract paints the
+  // alpha as grayscale → vstack glues color above matte into one tall frame.
+  const filter =
+    `[0:v]fps=${FPS},format=rgba,${resize}premultiply=inplace=1,format=rgba,` +
+    `split[c][a];[a]alphaextract[m];[c][m]vstack`;
+
+  console.log(
+    `→ packing ${path.basename(input)} (${codec}/${pixFmt || 'alpha_mode=1'}, ${FPS} fps, quality ${quality}% = crf ${CRF})...`
+  );
+  execFileSync('ffmpeg', [
+    '-y', '-hide_banner', '-loglevel', 'error',
+    // The native vp8/vp9 decoders ignore alpha; the libvpx ones decode it.
+    ...(vpxAlpha ? ['-c:v', codec === 'vp8' ? 'libvpx' : 'libvpx-vp9'] : []),
+    '-i', input,
+    '-filter_complex', filter,
+    '-c:v', 'libx264', '-crf', CRF, '-pix_fmt', 'yuv420p',
+    '-movflags', '+faststart', '-an',
+    outFile,
+  ], { stdio: 'inherit' });
+
+  const mb = (fs.statSync(outFile).size / 1024 / 1024).toFixed(2);
+  console.log(`✔ ${outFile}  (${mb} MB)`);
+  console.log(
+    `  use it:  <TransparentVideo source={require('./${path.basename(outFile)}')} width={...} height={...} />\n`
+  );
+}

package/expo-module.config.json

@@ -0,0 +1,6 @@
+{
+  "platforms": ["android"],
+  "android": {
+    "modules": ["expo.modules.transparentvideo.TransparentVideoModule"]
+  }
+}

package/lib/TransparentVideo.d.ts

@@ -0,0 +1,33 @@
+import React from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+import type { SharedValue } from 'react-native-reanimated';
+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 declare function TransparentVideo({ source, width, height, loop, paused, style, onEnd, }: TransparentVideoProps): React.JSX.Element;

package/lib/TransparentVideo.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransparentVideo = TransparentVideo;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const TransparentVideoView_1 = require("./TransparentVideoView");
+const useResolvedUri_1 = require("./useResolvedUri");
+/**
+ * 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).
+ */
+function TransparentVideo({ source, width, height, loop = true, paused = false, style, onEnd, }) {
+    const uri = (0, useResolvedUri_1.useResolvedUri)(source);
+    return ((0, jsx_runtime_1.jsx)(TransparentVideoView_1.TransparentVideoView, { uri: uri, width: width, height: height, loop: loop, paused: paused, style: style, onEnd: onEnd }));
+}