@igorpache/expo-video-editor 0.1.0

package/.prettierrc

@@ -0,0 +1,8 @@
+{
+  "printWidth": 100,
+  "tabWidth": 2,
+  "singleQuote": true,
+  "bracketSameLine": true,
+  "trailingComma": "es5",
+  "jsxSingleQuote": false,
+}

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015-present 650 Industries, Inc. (aka Expo)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,117 @@
+# expo-video-editor
+
+High-performance, Stories-style video editor for Expo / React Native. Trim, color
+filters, draggable text and Giphy GIF overlays, and a background-music mix — exported
+in a **single hardware-encoded pass** with **no FFmpeg** (Media3 Transformer on Android,
+AVFoundation on iOS).
+
+- **Fast:** hardware decode/encode, GPU effects, gesture work on the UI thread.
+- **What you see is what you export:** the same color matrix drives the live preview and
+  the export.
+- **Agnostic audio:** any local or remote URI — you resolve the source, the editor mixes it.
+
+> Requires a **dev build** (custom native module — not Expo Go), Expo SDK **57+**, and the
+> New Architecture (default on SDK 57).
+
+---
+
+## Install
+
+```sh
+npx expo install expo-video-editor \
+  react-native-gesture-handler react-native-reanimated react-native-worklets \
+  react-native-view-shot expo-image expo-audio expo-file-system expo-video-thumbnails
+```
+
+Then build a dev client:
+
+```sh
+npx expo run:ios      # or run:android
+```
+
+### Peer dependencies
+
+| Package | Why |
+|---|---|
+| `react-native-gesture-handler`, `react-native-reanimated` (+ `react-native-worklets`) | Overlay drag/pinch/rotate, trim + audio handles |
+| `react-native-view-shot` | Rasterizes text overlays at export |
+| `expo-image` | GIF rendering (Giphy grid + preview) |
+| `expo-audio` | Music preview + segment pre-listen |
+| `expo-file-system` | Downloads remote GIF/audio before export |
+| `expo-video-thumbnails` | Trim-timeline frames |
+
+The host app declares its own media permissions (to pick the video/audio). No custom
+config plugin is required by this library.
+
+---
+
+## Usage
+
+```tsx
+import { VideoEditor } from 'expo-video-editor';
+
+<VideoEditor
+  source={{ uri: pickedVideoUri }}
+  giphy={{ apiKey: process.env.GIPHY_KEY }}          // omit to hide the GIF button
+  audio={{ onPickAudio: pickAudioFile }}             // omit to hide the Music button
+  export={{ resolution: 1080 }}
+  onExportComplete={(result) => save(result.uri)}
+  onExportError={(err) => console.warn(err)}
+  onCancel={() => goBack()}
+/>
+```
+
+`onPickAudio` returns any audio URI you resolve — a file picker, a music SDK, a recording:
+
+```ts
+async function pickAudioFile() {
+  const res = await DocumentPicker.getDocumentAsync({ type: 'audio/*' });
+  return res.canceled ? null : { uri: res.assets[0].uri, title: res.assets[0].name };
+}
+```
+
+---
+
+## API
+
+### `<VideoEditor>` props
+
+| Prop | Type | Notes |
+|---|---|---|
+| `source` | `{ uri: string }` | The video to edit (required) |
+| `giphy` | `{ apiKey: string }` | Enables the GIF button |
+| `audio` | `{ onPickAudio?: () => Promise<AudioSource \| null> }` | Enables the Music button |
+| `export` | `{ resolution?: 720 \| 1080 \| 'source'; bitrate?: number }` | Export options |
+| `theme` | `Partial<EditorTheme>` | Color overrides |
+| `onExportStart / Progress / Complete / Error` | callbacks | `Progress` is `0..1` |
+| `onCancel` | `() => void` | Fired when the user cancels |
+
+### Also exported
+
+- `exportVideo(state, options, onProgress)` — imperative, headless export.
+- `useVideoEditor()` — the Zustand store (advanced/headless control).
+- `FILTER_PRESETS`, `getFilterMatrix(key)` — the shared color-matrix presets.
+- `EditorError` (with `code`), and all `types`.
+
+---
+
+## How export works
+
+Overlays are interactive **React Native views** while editing. At export they become
+**data** — text is rasterized (view-shot) to the video resolution; GIFs are decoded
+natively and the frame matching each timestamp is drawn. Everything (trim, color matrix,
+overlays, audio mix) is applied in one encode. Trim with no effects **transmuxes** (no
+re-encode, near-instant).
+
+## Known limitations (v1)
+
+- `export.resolution` / `bitrate` are plumbed but not yet applied — exports use the source
+  resolution. (Downscaling on re-encode is planned.)
+- Overlays are always visible for the whole clip (`timeRange` is modeled; per-overlay
+  timing UI is planned).
+- Filter looks are hand-tuned approximations; fine-tune the matrices in `filters/presets`.
+- Android audio mixing uses the newest Media3 APIs — validate on device.
+
+## License
+
+MIT

package/android/build.gradle

@@ -0,0 +1,27 @@
+plugins {
+  id 'com.android.library'
+  id 'expo-module-gradle-plugin'
+}
+
+group = 'expo.modules.videoeditor'
+version = '0.1.0'
+
+android {
+  namespace "expo.modules.videoeditor"
+  defaultConfig {
+    versionCode 1
+    versionName "0.1.0"
+  }
+  lintOptions {
+    abortOnError false
+  }
+}
+
+dependencies {
+  def media3 = "1.8.0"
+  implementation "androidx.media3:media3-exoplayer:$media3"
+  implementation "androidx.media3:media3-ui:$media3"
+  implementation "androidx.media3:media3-transformer:$media3"
+  implementation "androidx.media3:media3-effect:$media3"
+  implementation "androidx.media3:media3-common:$media3"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest>
+</manifest>

package/android/src/main/java/expo/modules/videoeditor/ColorMatrixEffect.kt

@@ -0,0 +1,25 @@
+package expo.modules.videoeditor
+
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.effect.RgbMatrix
+
+@UnstableApi
+class ColorMatrixEffect(matrix45: FloatArray) : RgbMatrix {
+  private val glMatrix: FloatArray = toColumnMajor(matrix45)
+
+  override fun getMatrix(presentationTimeUs: Long, useHdr: Boolean): FloatArray = glMatrix
+
+  companion object {
+    fun toColumnMajor(m: FloatArray): FloatArray {
+      val rr = m[0]; val rg = m[1]; val rb = m[2]; val rBias = m[4]
+      val gr = m[5]; val gg = m[6]; val gb = m[7]; val gBias = m[9]
+      val br = m[10]; val bg = m[11]; val bb = m[12]; val bBias = m[14]
+      return floatArrayOf(
+        rr, gr, br, 0f,
+        rg, gg, bg, 0f,
+        rb, gb, bb, 0f,
+        rBias, gBias, bBias, 1f,
+      )
+    }
+  }
+}

package/android/src/main/java/expo/modules/videoeditor/ExpoVideoEditorModule.kt

@@ -0,0 +1,61 @@
+package expo.modules.videoeditor
+
+import androidx.media3.common.util.UnstableApi
+import expo.modules.kotlin.Promise
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+
+@UnstableApi
+class ExpoVideoEditorModule : Module() {
+  private var exportRunner: ExportRunner? = null
+
+  override fun definition() = ModuleDefinition {
+    Name("ExpoVideoEditor")
+
+    Events("onExportProgress")
+
+    AsyncFunction("ping") {
+      "ExpoVideoEditor 0.1.0 (android)"
+    }
+
+    AsyncFunction("exportVideo") { payload: ExportPayload, promise: Promise ->
+      val context = appContext.reactContext
+      if (context == null) {
+        promise.reject("EXPORT_FAILED", "No React context available", null)
+        return@AsyncFunction
+      }
+      val runner = ExportRunner(context) { progress ->
+        sendEvent("onExportProgress", mapOf("progress" to progress))
+      }
+      exportRunner = runner
+      runner.export(payload, promise)
+    }
+
+    Function("cancelExport") {
+      exportRunner?.cancel()
+    }
+
+    View(ExpoVideoEditorView::class) {
+      Events("onLoad", "onProgress", "onEnded")
+
+      Prop("source") { view: ExpoVideoEditorView, source: VideoSourceRecord ->
+        view.setSource(source.uri)
+      }
+      Prop("paused") { view: ExpoVideoEditorView, paused: Boolean ->
+        view.setPaused(paused)
+      }
+      Prop("loopStartMs") { view: ExpoVideoEditorView, ms: Int ->
+        view.setLoopStart(ms.toLong())
+      }
+      Prop("loopEndMs") { view: ExpoVideoEditorView, ms: Int ->
+        view.setLoopEnd(ms.toLong())
+      }
+      Prop("seek") { view: ExpoVideoEditorView, seek: SeekRecord ->
+        view.seekTo(seek.positionMs.toLong(), seek.seq)
+      }
+      Prop("colorMatrix") { view: ExpoVideoEditorView, matrix: List<Double> ->
+        view.setColorMatrix(matrix)
+      }
+    }
+  }
+}

package/android/src/main/java/expo/modules/videoeditor/ExpoVideoEditorView.kt

@@ -0,0 +1,109 @@
+package expo.modules.videoeditor
+
+import android.content.Context
+import android.net.Uri
+import android.os.Handler
+import android.os.Looper
+import androidx.media3.common.MediaItem
+import androidx.media3.common.Player
+import androidx.media3.common.VideoSize
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.exoplayer.ExoPlayer
+import androidx.media3.ui.AspectRatioFrameLayout
+import androidx.media3.ui.PlayerView
+import expo.modules.kotlin.AppContext
+import expo.modules.kotlin.viewevent.EventDispatcher
+import expo.modules.kotlin.views.ExpoView
+
+@UnstableApi
+class ExpoVideoEditorView(context: Context, appContext: AppContext) : ExpoView(context, appContext) {
+  private val onLoad by EventDispatcher<Map<String, Any>>()
+  private val onProgress by EventDispatcher<Map<String, Any>>()
+  private val onEnded by EventDispatcher<Map<String, Any>>()
+
+  private val exo = ExoPlayer.Builder(context).build()
+  private val playerView = PlayerView(context).apply {
+    useController = false
+    player = exo
+    resizeMode = AspectRatioFrameLayout.RESIZE_MODE_ZOOM
+  }
+
+  private var loopStartMs: Long = 0
+  private var loopEndMs: Long = 0
+  private var lastSeekSeq: Int = -1
+  private var didEmitLoad = false
+
+  private val handler = Handler(Looper.getMainLooper())
+  private val ticker = object : Runnable {
+    override fun run() {
+      val pos = exo.currentPosition
+      val end = if (loopEndMs > 0) loopEndMs else exo.duration
+      if (end > 0 && pos >= end) {
+        exo.seekTo(if (loopStartMs > 0) loopStartMs else 0)
+      }
+      onProgress(mapOf("positionMs" to pos.toDouble()))
+      handler.postDelayed(this, 50)
+    }
+  }
+
+  init {
+    addView(playerView)
+    exo.addListener(object : Player.Listener {
+      override fun onPlaybackStateChanged(state: Int) {
+        if (state == Player.STATE_READY && !didEmitLoad) {
+          didEmitLoad = true
+          val vs: VideoSize = exo.videoSize
+          onLoad(
+            mapOf(
+              "durationMs" to exo.duration.coerceAtLeast(0).toDouble(),
+              "width" to vs.width,
+              "height" to vs.height,
+              "rotationDeg" to vs.unappliedRotationDegrees
+            )
+          )
+        }
+        if (state == Player.STATE_ENDED) onEnded(emptyMap())
+      }
+    })
+    handler.post(ticker)
+  }
+
+  fun setSource(uri: String) {
+    if (uri.isEmpty()) return
+    didEmitLoad = false
+    exo.setMediaItem(MediaItem.fromUri(Uri.parse(uri)))
+    exo.prepare()
+  }
+
+  fun setPaused(paused: Boolean) {
+    exo.playWhenReady = !paused
+  }
+
+  fun setLoopStart(ms: Long) {
+    loopStartMs = ms
+  }
+
+  fun setLoopEnd(ms: Long) {
+    loopEndMs = ms
+  }
+
+  fun seekTo(positionMs: Long, seq: Int) {
+    if (seq == lastSeekSeq) return
+    lastSeekSeq = seq
+    exo.seekTo(positionMs.coerceAtLeast(0))
+  }
+
+  fun setColorMatrix(matrix: List<Double>) {
+    if (matrix.size >= 20) {
+      exo.setVideoEffects(listOf(ColorMatrixEffect(FloatArray(20) { matrix[it].toFloat() })))
+    } else {
+      exo.setVideoEffects(emptyList())
+    }
+  }
+
+  override fun onDetachedFromWindow() {
+    super.onDetachedFromWindow()
+    handler.removeCallbacks(ticker)
+    exo.release()
+  }
+}

package/android/src/main/java/expo/modules/videoeditor/ExportRunner.kt

@@ -0,0 +1,302 @@
+package expo.modules.videoeditor
+
+import android.content.Context
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
+import android.graphics.Canvas
+import android.graphics.Movie
+import android.media.MediaMetadataRetriever
+import android.net.Uri
+import android.os.Handler
+import android.os.Looper
+import androidx.media3.common.Effect
+import androidx.media3.common.MediaItem
+import androidx.media3.common.MimeTypes
+import androidx.media3.common.audio.AudioProcessor
+import androidx.media3.common.audio.ChannelMixingAudioProcessor
+import androidx.media3.common.audio.ChannelMixingMatrix
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.effect.BitmapOverlay
+import androidx.media3.effect.OverlayEffect
+import androidx.media3.effect.Presentation
+import androidx.media3.effect.StaticOverlaySettings
+import androidx.media3.effect.TextureOverlay
+import androidx.media3.transformer.Composition
+import androidx.media3.transformer.EditedMediaItem
+import androidx.media3.transformer.EditedMediaItemSequence
+import androidx.media3.transformer.Effects
+import androidx.media3.transformer.ExportException
+import androidx.media3.transformer.ExportResult
+import androidx.media3.transformer.ProgressHolder
+import androidx.media3.transformer.Transformer
+import com.google.common.collect.ImmutableList
+import expo.modules.kotlin.Promise
+import java.io.File
+import java.io.FileInputStream
+import java.io.InputStream
+
+@UnstableApi
+class ExportRunner(
+  private val context: Context,
+  private val onProgress: (Double) -> Unit
+) {
+  private var transformer: Transformer? = null
+  private val mainHandler = Handler(Looper.getMainLooper())
+  private val progressHolder = ProgressHolder()
+  private var polling = false
+
+  private val poller = object : Runnable {
+    override fun run() {
+      val t = transformer ?: return
+      val state = t.getProgress(progressHolder)
+      if (state != Transformer.PROGRESS_STATE_NOT_STARTED) {
+        onProgress(progressHolder.progress / 100.0)
+      }
+      if (polling) mainHandler.postDelayed(this, 200)
+    }
+  }
+
+  fun export(payload: ExportPayload, promise: Promise) {
+    mainHandler.post {
+      try {
+        val outFile = File(context.cacheDir, "vieditor-export-${System.nanoTime()}.mp4")
+
+        val isImage = payload.imageDurationMs > 0
+
+        val clipping = if (!isImage && payload.endMs > payload.startMs) {
+          MediaItem.ClippingConfiguration.Builder()
+            .setStartPositionMs(payload.startMs.toLong())
+            .setEndPositionMs(payload.endMs.toLong())
+            .build()
+        } else {
+          MediaItem.ClippingConfiguration.UNSET
+        }
+
+        val mediaItemBuilder = MediaItem.Builder()
+          .setUri(Uri.parse(payload.sourceUri))
+          .setClippingConfiguration(clipping)
+        if (isImage) {
+          mediaItemBuilder
+            .setMimeType(MimeTypes.IMAGE_JPEG)
+            .setImageDurationMs(payload.imageDurationMs.toLong())
+        }
+        val mediaItem = mediaItemBuilder.build()
+
+        val videoEffects = mutableListOf<Effect>()
+        if (payload.colorMatrix.size >= 20) {
+          videoEffects.add(ColorMatrixEffect(FloatArray(20) { payload.colorMatrix[it].toFloat() }))
+        }
+        if (payload.overlays.isNotEmpty()) {
+          val (outW, outH) = if (isImage) readImageSize(payload.sourceUri) else readSourceSize(payload.sourceUri)
+          val overlays = payload.overlays.mapNotNull { buildOverlay(it, outW, outH) }
+          if (overlays.isNotEmpty()) {
+            videoEffects.add(OverlayEffect(ImmutableList.copyOf(overlays)))
+          }
+        }
+        // H.264/HEVC encoders reject odd dimensions (ERROR_CODE_ENCODING_FORMAT_UNSUPPORTED).
+        // A baked image can have an odd width/height, so force even output dimensions.
+        if (isImage) {
+          val (iw, ih) = readImageSize(payload.sourceUri)
+          val ew = iw - (iw % 2)
+          val eh = ih - (ih % 2)
+          if (ew > 0 && eh > 0 && (ew != iw || eh != ih)) {
+            videoEffects.add(Presentation.createForWidthAndHeight(ew, eh, Presentation.LAYOUT_SCALE_TO_FIT))
+          }
+        }
+        val audio = payload.audio
+        val originalAudioProcessors: List<AudioProcessor> =
+          if (!isImage && audio != null && payload.originalVolume != 1.0) {
+            listOf(volumeProcessor(payload.originalVolume.toFloat()))
+          } else {
+            emptyList()
+          }
+        val videoEditedBuilder = EditedMediaItem.Builder(mediaItem)
+          .setEffects(Effects(originalAudioProcessors, videoEffects))
+        if (isImage) {
+          videoEditedBuilder.setFrameRate(30)
+        }
+        val videoEdited = videoEditedBuilder.build()
+
+        val t = Transformer.Builder(context)
+          .addListener(object : Transformer.Listener {
+            override fun onCompleted(composition: Composition, exportResult: ExportResult) {
+              stopPolling()
+              onProgress(1.0)
+              promise.resolve(readResult(outFile, payload))
+            }
+
+            override fun onError(
+              composition: Composition,
+              exportResult: ExportResult,
+              exception: ExportException
+            ) {
+              stopPolling()
+              val detail = "${exception.errorCodeName}: ${exception.cause?.message ?: exception.message}"
+              android.util.Log.e("ExpoVideoEditor", "Export failed ($detail)", exception)
+              promise.reject("EXPORT_FAILED", detail, exception)
+            }
+          })
+          .build()
+
+        transformer = t
+        if (audio != null) {
+          val clipping = if (audio.trimEndMs > audio.trimStartMs) {
+            MediaItem.ClippingConfiguration.Builder()
+              .setStartPositionMs(audio.trimStartMs.toLong())
+              .setEndPositionMs(audio.trimEndMs.toLong())
+              .build()
+          } else {
+            MediaItem.ClippingConfiguration.UNSET
+          }
+          val musicItem = MediaItem.Builder()
+            .setUri(Uri.parse(audio.uri))
+            .setClippingConfiguration(clipping)
+            .build()
+          val musicEdited = EditedMediaItem.Builder(musicItem)
+            .setRemoveVideo(true)
+            .setEffects(Effects(listOf(volumeProcessor(audio.volume.toFloat())), emptyList()))
+            .build()
+          val videoSequence = EditedMediaItemSequence.Builder(videoEdited).build()
+          val musicSequence = EditedMediaItemSequence.Builder(musicEdited).setIsLooping(audio.loop).build()
+          val composition = Composition.Builder(videoSequence, musicSequence).build()
+          t.start(composition, outFile.absolutePath)
+        } else {
+          t.start(videoEdited, outFile.absolutePath)
+        }
+        startPolling()
+      } catch (e: Exception) {
+        promise.reject("EXPORT_FAILED", e.message ?: "Export setup failed", e)
+      }
+    }
+  }
+
+  fun cancel() {
+    mainHandler.post {
+      transformer?.cancel()
+      stopPolling()
+    }
+  }
+
+  private fun startPolling() {
+    polling = true
+    mainHandler.post(poller)
+  }
+
+  private fun stopPolling() {
+    polling = false
+    mainHandler.removeCallbacks(poller)
+  }
+
+  private fun volumeProcessor(volume: Float): AudioProcessor {
+    val processor = ChannelMixingAudioProcessor()
+    processor.putChannelMixingMatrix(ChannelMixingMatrix.create(1, 1).scaleBy(volume))
+    processor.putChannelMixingMatrix(ChannelMixingMatrix.create(2, 2).scaleBy(volume))
+    return processor
+  }
+
+  private fun readSourceSize(uri: String): Pair<Int, Int> {
+    val retriever = MediaMetadataRetriever()
+    return try {
+      retriever.setDataSource(context, Uri.parse(uri))
+      val w = retriever.extractMetadata(MediaMetadataRetriever.METADATA_KEY_VIDEO_WIDTH)?.toIntOrNull() ?: 0
+      val h = retriever.extractMetadata(MediaMetadataRetriever.METADATA_KEY_VIDEO_HEIGHT)?.toIntOrNull() ?: 0
+      val rot = retriever.extractMetadata(MediaMetadataRetriever.METADATA_KEY_VIDEO_ROTATION)?.toIntOrNull() ?: 0
+      if (rot == 90 || rot == 270) Pair(h, w) else Pair(w, h)
+    } catch (_: Exception) {
+      Pair(0, 0)
+    } finally {
+      retriever.release()
+    }
+  }
+
+  private fun readImageSize(uri: String): Pair<Int, Int> {
+    return try {
+      val opts = BitmapFactory.Options().apply { inJustDecodeBounds = true }
+      openStream(uri)?.use { BitmapFactory.decodeStream(it, null, opts) }
+      Pair(opts.outWidth, opts.outHeight)
+    } catch (_: Exception) {
+      Pair(0, 0)
+    }
+  }
+
+  private fun openStream(uriStr: String): InputStream? {
+    return try {
+      val uri = Uri.parse(uriStr)
+      if (uri.scheme == null || uri.scheme == "file") FileInputStream(uri.path ?: uriStr)
+      else context.contentResolver.openInputStream(uri)
+    } catch (_: Exception) {
+      null
+    }
+  }
+
+  private fun loadBitmap(uriStr: String): Bitmap? =
+    openStream(uriStr)?.use { runCatching { BitmapFactory.decodeStream(it) }.getOrNull() }
+
+  private fun decodeGifFrames(uriStr: String): Pair<List<Bitmap>, LongArray>? {
+    val movie = openStream(uriStr)?.use { Movie.decodeStream(it) } ?: return null
+    val w = movie.width()
+    val h = movie.height()
+    if (w <= 0 || h <= 0) return null
+    val duration = movie.duration().coerceAtLeast(1)
+    val stepMs = 50
+    val frames = mutableListOf<Bitmap>()
+    var t = 0
+    while (t < duration) {
+      val bmp = Bitmap.createBitmap(w, h, Bitmap.Config.ARGB_8888)
+      movie.setTime(t)
+      movie.draw(Canvas(bmp), 0f, 0f)
+      frames.add(bmp)
+      t += stepMs
+    }
+    if (frames.isEmpty()) return null
+    return Pair(frames, LongArray(frames.size) { stepMs * 1000L })
+  }
+
+  private fun overlaySettings(rec: OverlayRecord, bmpW: Int, bmpH: Int, outW: Int, outH: Int): StaticOverlaySettings {
+    val sx = (rec.widthFraction * outW / bmpW).toFloat()
+    val sy = (rec.heightFraction * outH / bmpH).toFloat()
+    val bgX = (rec.centerX * 2 - 1).toFloat()
+    val bgY = (1 - rec.centerY * 2).toFloat()
+    return StaticOverlaySettings.Builder()
+      .setScale(sx, sy)
+      .setRotationDegrees((-rec.rotationDeg).toFloat())
+      .setOverlayFrameAnchor(0f, 0f)
+      .setBackgroundFrameAnchor(bgX, bgY)
+      .build()
+  }
+
+  private fun buildOverlay(rec: OverlayRecord, outW: Int, outH: Int): TextureOverlay? {
+    if (outW <= 0 || outH <= 0) return null
+    if (rec.animated) {
+      val (frames, durations) = decodeGifFrames(rec.uri) ?: return null
+      return GifOverlay(frames, durations, overlaySettings(rec, frames[0].width, frames[0].height, outW, outH))
+    }
+    val bmp = loadBitmap(rec.uri) ?: return null
+    if (bmp.width <= 0 || bmp.height <= 0) return null
+    return BitmapOverlay.createStaticBitmapOverlay(bmp, overlaySettings(rec, bmp.width, bmp.height, outW, outH))
+  }
+
+  private fun readResult(file: File, payload: ExportPayload): Map<String, Any> {
+    var width = 0
+    var height = 0
+    var durationMs = (payload.endMs - payload.startMs).toLong().coerceAtLeast(0)
+    val retriever = MediaMetadataRetriever()
+    try {
+      retriever.setDataSource(file.absolutePath)
+      width = retriever.extractMetadata(MediaMetadataRetriever.METADATA_KEY_VIDEO_WIDTH)?.toIntOrNull() ?: 0
+      height = retriever.extractMetadata(MediaMetadataRetriever.METADATA_KEY_VIDEO_HEIGHT)?.toIntOrNull() ?: 0
+      retriever.extractMetadata(MediaMetadataRetriever.METADATA_KEY_DURATION)?.toLongOrNull()?.let {
+        if (it > 0) durationMs = it
+      }
+    } catch (_: Exception) {
+    } finally {
+      retriever.release()
+    }
+    return mapOf(
+      "uri" to Uri.fromFile(file).toString(),
+      "width" to width,
+      "height" to height,
+      "durationMs" to durationMs.toDouble()
+    )
+  }
+}