@igorpache/expo-video-editor 0.1.0

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

@@ -0,0 +1,27 @@
+package expo.modules.videoeditor
+
+import android.graphics.Bitmap
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.effect.BitmapOverlay
+import androidx.media3.common.OverlaySettings
+
+@UnstableApi
+class GifOverlay(
+  private val frames: List<Bitmap>,
+  private val frameDurationsUs: LongArray,
+  private val settings: OverlaySettings,
+) : BitmapOverlay() {
+  private val totalUs = frameDurationsUs.sum().coerceAtLeast(1)
+
+  override fun getBitmap(presentationTimeUs: Long): Bitmap {
+    val t = presentationTimeUs % totalUs
+    var acc = 0L
+    for (i in frames.indices) {
+      acc += frameDurationsUs[i]
+      if (t < acc) return frames[i]
+    }
+    return frames.last()
+  }
+
+  override fun getOverlaySettings(presentationTimeUs: Long): OverlaySettings = settings
+}

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

@@ -0,0 +1,44 @@
+package expo.modules.videoeditor
+
+import expo.modules.kotlin.records.Field
+import expo.modules.kotlin.records.Record
+
+class VideoSourceRecord : Record {
+  @Field val uri: String = ""
+}
+
+class SeekRecord : Record {
+  @Field val seq: Int = 0
+  @Field val positionMs: Int = 0
+}
+
+class OverlayRecord : Record {
+  @Field val uri: String = ""
+  @Field val animated: Boolean = false
+  @Field val centerX: Double = 0.5
+  @Field val centerY: Double = 0.5
+  @Field val widthFraction: Double = 0.0
+  @Field val heightFraction: Double = 0.0
+  @Field val rotationDeg: Double = 0.0
+}
+
+class AudioRecord : Record {
+  @Field val uri: String = ""
+  @Field val trimStartMs: Int = 0
+  @Field val trimEndMs: Int = 0
+  @Field val volume: Double = 1.0
+  @Field val loop: Boolean = true
+}
+
+class ExportPayload : Record {
+  @Field val sourceUri: String = ""
+  @Field val startMs: Int = 0
+  @Field val endMs: Int = 0
+  @Field val imageDurationMs: Int = 0
+  @Field val resolution: Int = 0
+  @Field val bitrate: Int = 0
+  @Field val colorMatrix: List<Double> = emptyList()
+  @Field val overlays: List<OverlayRecord> = emptyList()
+  @Field val audio: AudioRecord? = null
+  @Field val originalVolume: Double = 1.0
+}

package/eslint.config.cjs

@@ -0,0 +1,16 @@
+const { defineConfig } = require('eslint/config');
+const universe = require('eslint-config-universe/flat/native');
+const universeWeb = require('eslint-config-universe/flat/web');
+
+module.exports = defineConfig([
+  { ignores: ['build'] },
+  ...universe,
+  ...universeWeb,
+  {
+    rules: {
+      'react-hooks/immutability': 'off',
+      'react-hooks/refs': 'off',
+      'react-hooks/set-state-in-effect': 'off',
+    },
+  },
+]);

package/expo-module.config.json

@@ -0,0 +1,9 @@
+{
+  "platforms": ["apple", "android"],
+  "apple": {
+    "modules": ["ExpoVideoEditorModule"]
+  },
+  "android": {
+    "modules": ["expo.modules.videoeditor.ExpoVideoEditorModule"]
+  }
+}

package/ios/AudioMixBuilder.swift

@@ -0,0 +1,66 @@
+import AVFoundation
+
+enum AudioMixBuilder {
+  static func build(source: AVURLAsset, payload: ExportPayload) async throws -> (AVMutableComposition, AVMutableAudioMix) {
+    let composition = AVMutableComposition()
+
+    let trimStart = CMTime(value: CMTimeValue(payload.startMs), timescale: 1000)
+    let trimDuration: CMTime =
+      payload.endMs > payload.startMs
+      ? CMTime(value: CMTimeValue(payload.endMs - payload.startMs), timescale: 1000)
+      : try await source.load(.duration)
+    let trimRange = CMTimeRange(start: trimStart, duration: trimDuration)
+
+    if let srcVideo = try await source.loadTracks(withMediaType: .video).first,
+      let compVideo = composition.addMutableTrack(withMediaType: .video, preferredTrackID: kCMPersistentTrackID_Invalid) {
+      try compVideo.insertTimeRange(trimRange, of: srcVideo, at: .zero)
+      compVideo.preferredTransform = try await srcVideo.load(.preferredTransform)
+    }
+
+    var parameters: [AVMutableAudioMixInputParameters] = []
+
+    if let srcAudio = try await source.loadTracks(withMediaType: .audio).first,
+      let compAudio = composition.addMutableTrack(withMediaType: .audio, preferredTrackID: kCMPersistentTrackID_Invalid) {
+      try compAudio.insertTimeRange(trimRange, of: srcAudio, at: .zero)
+      let p = AVMutableAudioMixInputParameters(track: compAudio)
+      p.setVolume(Float(payload.originalVolume), at: .zero)
+      parameters.append(p)
+    }
+
+    if let audio = payload.audio, let musicURL = fileURL(audio.uri) {
+      let musicAsset = AVURLAsset(url: musicURL)
+      if let musicTrack = try await musicAsset.loadTracks(withMediaType: .audio).first,
+        let compMusic = composition.addMutableTrack(withMediaType: .audio, preferredTrackID: kCMPersistentTrackID_Invalid) {
+        let segStart = CMTime(value: CMTimeValue(audio.trimStartMs), timescale: 1000)
+        let segEnd: CMTime =
+          audio.trimEndMs > audio.trimStartMs
+          ? CMTime(value: CMTimeValue(audio.trimEndMs), timescale: 1000)
+          : try await musicAsset.load(.duration)
+        let segDuration = CMTimeSubtract(segEnd, segStart)
+
+        if segDuration.seconds > 0 {
+          var inserted = CMTime.zero
+          while inserted < trimDuration {
+            let remaining = CMTimeSubtract(trimDuration, inserted)
+            let chunk = CMTimeMinimum(segDuration, remaining)
+            if chunk.seconds <= 0 { break }
+            try compMusic.insertTimeRange(CMTimeRange(start: segStart, duration: chunk), of: musicTrack, at: inserted)
+            inserted = CMTimeAdd(inserted, chunk)
+            if !audio.loop { break }
+          }
+        }
+        let p = AVMutableAudioMixInputParameters(track: compMusic)
+        p.setVolume(Float(audio.volume), at: .zero)
+        parameters.append(p)
+      }
+    }
+
+    let mix = AVMutableAudioMix()
+    mix.inputParameters = parameters
+    return (composition, mix)
+  }
+
+  private static func fileURL(_ uri: String) -> URL? {
+    uri.hasPrefix("/") ? URL(fileURLWithPath: uri) : (URL(string: uri) ?? URL(fileURLWithPath: uri))
+  }
+}

package/ios/ColorMatrixFilter.swift

@@ -0,0 +1,24 @@
+import AVFoundation
+import CoreImage
+
+enum ColorMatrixFilter {
+  static func makeFilter(_ m: [Double]) -> CIFilter? {
+    guard m.count >= 20, let filter = CIFilter(name: "CIColorMatrix") else { return nil }
+    filter.setValue(CIVector(x: CGFloat(m[0]), y: CGFloat(m[1]), z: CGFloat(m[2]), w: CGFloat(m[3])), forKey: "inputRVector")
+    filter.setValue(CIVector(x: CGFloat(m[5]), y: CGFloat(m[6]), z: CGFloat(m[7]), w: CGFloat(m[8])), forKey: "inputGVector")
+    filter.setValue(CIVector(x: CGFloat(m[10]), y: CGFloat(m[11]), z: CGFloat(m[12]), w: CGFloat(m[13])), forKey: "inputBVector")
+    filter.setValue(CIVector(x: CGFloat(m[15]), y: CGFloat(m[16]), z: CGFloat(m[17]), w: CGFloat(m[18])), forKey: "inputAVector")
+    filter.setValue(CIVector(x: CGFloat(m[4]), y: CGFloat(m[9]), z: CGFloat(m[14]), w: CGFloat(m[19])), forKey: "inputBiasVector")
+    return filter
+  }
+
+  static func videoComposition(for asset: AVAsset, matrix: [Double]) -> AVVideoComposition? {
+    guard let filter = makeFilter(matrix) else { return nil }
+    return AVMutableVideoComposition(asset: asset) { request in
+      let source = request.sourceImage.clampedToExtent()
+      filter.setValue(source, forKey: kCIInputImageKey)
+      let output = filter.outputImage?.cropped(to: request.sourceImage.extent) ?? request.sourceImage
+      request.finish(with: output, context: nil)
+    }
+  }
+}

package/ios/ExpoVideoEditor.podspec

@@ -0,0 +1,23 @@
+Pod::Spec.new do |s|
+  s.name           = 'ExpoVideoEditor'
+  s.version        = '0.1.0'
+  s.summary        = 'High-performance Stories-style video editor for Expo/React Native'
+  s.description    = 'Native video editing (trim, color filters, text/GIF overlays, audio mixing) built on AVFoundation with a hardware-encoded single-pass export.'
+  s.author         = 'Gleidson Daniel'
+  s.homepage       = 'https://github.com/GleidsonDaniel/expo-video-editor'
+  s.platforms      = {
+    :ios => '16.4',
+    :tvos => '16.4'
+  }
+  s.source         = { git: 'https://github.com/GleidsonDaniel/expo-video-editor.git' }
+  s.static_framework = true
+
+  s.dependency 'ExpoModulesCore'
+
+  # Swift/Objective-C compatibility
+  s.pod_target_xcconfig = {
+    'DEFINES_MODULE' => 'YES',
+  }
+
+  s.source_files = "**/*.{h,m,mm,swift,hpp,cpp}"
+end

package/ios/ExpoVideoEditorModule.swift

@@ -0,0 +1,55 @@
+import ExpoModulesCore
+
+public class ExpoVideoEditorModule: Module {
+  private var exportRunner: ExportRunner?
+
+  public func definition() -> ModuleDefinition {
+    Name("ExpoVideoEditor")
+
+    Events("onExportProgress")
+
+    AsyncFunction("ping") { () -> String in
+      "ExpoVideoEditor 0.1.0 (ios)"
+    }
+
+    AsyncFunction("exportVideo") { (payload: ExportPayload, promise: Promise) in
+      let runner = ExportRunner()
+      self.exportRunner = runner
+      runner.export(
+        payload,
+        onProgress: { [weak self] progress in
+          self?.sendEvent("onExportProgress", ["progress": progress])
+        },
+        resolve: { result in promise.resolve(result) },
+        reject: { code, message in promise.reject(code, message) }
+      )
+    }
+
+    Function("cancelExport") {
+      self.exportRunner?.cancel()
+    }
+
+    View(ExpoVideoEditorView.self) {
+      Events("onLoad", "onProgress", "onEnded")
+
+      Prop("source") { (view: ExpoVideoEditorView, source: VideoSourceRecord) in
+        view.setSource(source.uri)
+      }
+      Prop("paused") { (view: ExpoVideoEditorView, paused: Bool) in
+        view.setPaused(paused)
+      }
+      Prop("loopStartMs") { (view: ExpoVideoEditorView, ms: Int) in
+        view.setLoopStart(ms)
+      }
+      Prop("loopEndMs") { (view: ExpoVideoEditorView, ms: Int) in
+        view.setLoopEnd(ms)
+      }
+      Prop("seek") { (view: ExpoVideoEditorView, seek: SeekRecord) in
+        view.seekTo(seq: seek.seq, positionMs: seek.positionMs)
+      }
+      Prop("colorMatrix") { (view: ExpoVideoEditorView, matrix: [Double]) in
+        view.setColorMatrix(matrix)
+      }
+    }
+  }
+}

package/ios/ExpoVideoEditorView.swift

@@ -0,0 +1,144 @@
+import AVFoundation
+import ExpoModulesCore
+import UIKit
+
+class ExpoVideoEditorView: ExpoView {
+  private let onLoad = EventDispatcher()
+  private let onProgress = EventDispatcher()
+  private let onEnded = EventDispatcher()
+
+  private let player = AVPlayer()
+  private let playerLayer = AVPlayerLayer()
+  private var timeObserver: Any?
+  private var statusObservation: NSKeyValueObservation?
+
+  private var loopStartMs: Int = 0
+  private var loopEndMs: Int = 0
+  private var lastSeekSeq: Int = -1
+  private var didEmitLoad = false
+  private var colorMatrix: [Double] = []
+
+  required init(appContext: AppContext? = nil) {
+    super.init(appContext: appContext)
+    clipsToBounds = true
+    backgroundColor = .black
+    playerLayer.player = player
+    playerLayer.videoGravity = .resizeAspectFill
+    layer.addSublayer(playerLayer)
+
+    let interval = CMTime(value: 1, timescale: 20)
+    timeObserver = player.addPeriodicTimeObserver(forInterval: interval, queue: .main) { [weak self] time in
+      self?.onTick(time)
+    }
+  }
+
+  deinit {
+    if let observer = timeObserver {
+      player.removeTimeObserver(observer)
+    }
+    statusObservation?.invalidate()
+  }
+
+  override func layoutSubviews() {
+    super.layoutSubviews()
+    playerLayer.frame = bounds
+  }
+
+  func setSource(_ uri: String) {
+    guard let url = Self.urlFrom(uri) else { return }
+    didEmitLoad = false
+    let item = AVPlayerItem(url: url)
+    statusObservation?.invalidate()
+    statusObservation = item.observe(\.status, options: [.new]) { [weak self] observed, _ in
+      guard let self = self, observed.status == .readyToPlay, !self.didEmitLoad else { return }
+      self.didEmitLoad = true
+      self.emitLoad(item)
+      self.applyVideoComposition()
+    }
+    player.replaceCurrentItem(with: item)
+    applyVideoComposition()
+    player.play()
+  }
+
+  func setPaused(_ paused: Bool) {
+    paused ? player.pause() : player.play()
+  }
+
+  func setLoopStart(_ ms: Int) {
+    loopStartMs = ms
+  }
+
+  func setLoopEnd(_ ms: Int) {
+    loopEndMs = ms
+  }
+
+  func seekTo(seq: Int, positionMs: Int) {
+    guard seq != lastSeekSeq else { return }
+    lastSeekSeq = seq
+    let target = CMTime(value: CMTimeValue(max(0, positionMs)), timescale: 1000)
+    player.seek(to: target, toleranceBefore: .zero, toleranceAfter: .zero)
+  }
+
+  func setColorMatrix(_ matrix: [Double]) {
+    colorMatrix = matrix
+    applyVideoComposition()
+  }
+
+  private func applyVideoComposition() {
+    guard let item = player.currentItem else { return }
+    if colorMatrix.count >= 20 {
+      item.videoComposition = ColorMatrixFilter.videoComposition(for: item.asset, matrix: colorMatrix)
+    } else {
+      item.videoComposition = nil
+    }
+  }
+
+  private func onTick(_ time: CMTime) {
+    let seconds = CMTimeGetSeconds(time)
+    guard seconds.isFinite else { return }
+    let posMs = Int(seconds * 1000)
+
+    let itemSeconds = player.currentItem.map { CMTimeGetSeconds($0.duration) } ?? 0
+    let itemDurMs = itemSeconds.isFinite ? Int(itemSeconds * 1000) : 0
+    let end = loopEndMs > 0 ? loopEndMs : itemDurMs
+    if end > 0 && posMs >= end {
+      let start = CMTime(value: CMTimeValue(max(0, loopStartMs)), timescale: 1000)
+      player.seek(to: start, toleranceBefore: .zero, toleranceAfter: .zero)
+    }
+    onProgress(["positionMs": posMs])
+  }
+
+  private func emitLoad(_ item: AVPlayerItem) {
+    Task {
+      let asset = item.asset
+      let durationSeconds = (try? await asset.load(.duration).seconds) ?? 0
+      let durationMs = durationSeconds.isFinite ? Int(durationSeconds * 1000) : 0
+
+      var width = 0
+      var height = 0
+      var rotationDeg = 0
+      if let track = try? await asset.loadTracks(withMediaType: .video).first {
+        let naturalSize = (try? await track.load(.naturalSize)) ?? .zero
+        let transform = (try? await track.load(.preferredTransform)) ?? .identity
+        let resolved = naturalSize.applying(transform)
+        width = Int(abs(resolved.width))
+        height = Int(abs(resolved.height))
+        rotationDeg = Int((atan2(transform.b, transform.a) * 180 / .pi).rounded())
+      }
+
+      await MainActor.run {
+        self.onLoad([
+          "durationMs": durationMs,
+          "width": width,
+          "height": height,
+          "rotationDeg": rotationDeg,
+        ])
+      }
+    }
+  }
+
+  static func urlFrom(_ uri: String) -> URL? {
+    if uri.hasPrefix("/") { return URL(fileURLWithPath: uri) }
+    return URL(string: uri)
+  }
+}

package/ios/ExportRunner.swift

@@ -0,0 +1,135 @@
+import AVFoundation
+import Foundation
+
+class ExportRunner {
+  private var session: AVAssetExportSession?
+  private var progressTimer: Timer?
+
+  func export(
+    _ payload: ExportPayload,
+    onProgress: @escaping (Double) -> Void,
+    resolve: @escaping (Any?) -> Void,
+    reject: @escaping (String, String) -> Void
+  ) {
+    Task {
+      do {
+        let source: AVURLAsset
+        if payload.imageDurationMs > 0 {
+          let stillURL = try await ImageVideoWriter.makeSilentVideo(
+            imageUri: payload.sourceUri,
+            durationMs: payload.imageDurationMs,
+            maxSide: payload.resolution
+          )
+          source = AVURLAsset(url: stillURL)
+        } else {
+          guard let url = Self.urlFrom(payload.sourceUri) else {
+            reject("SOURCE_LOAD", "Invalid source URI")
+            return
+          }
+          source = AVURLAsset(url: url)
+        }
+
+        let hasComposition = payload.colorMatrix.count >= 20 || !payload.overlays.isEmpty
+        let hasAudio = payload.audio != nil
+
+        let exportAsset: AVAsset
+        var audioMix: AVAudioMix?
+        var trimBaked = false
+        if hasAudio {
+          let (composition, mix) = try await AudioMixBuilder.build(source: source, payload: payload)
+          exportAsset = composition
+          audioMix = mix
+          trimBaked = true
+        } else {
+          exportAsset = source
+        }
+
+        let needsReencode = hasComposition || hasAudio
+        let preset = needsReencode ? AVAssetExportPresetHighestQuality : AVAssetExportPresetPassthrough
+        guard let session = AVAssetExportSession(asset: exportAsset, presetName: preset) else {
+          reject("EXPORT_FAILED", "Could not create export session")
+          return
+        }
+
+        let outURL = FileManager.default.temporaryDirectory
+          .appendingPathComponent("vieditor-export-\(UUID().uuidString).mp4")
+        session.outputURL = outURL
+        session.outputFileType = .mp4
+        session.shouldOptimizeForNetworkUse = true
+
+        if !trimBaked, payload.endMs > payload.startMs {
+          let start = CMTime(value: CMTimeValue(payload.startMs), timescale: 1000)
+          let duration = CMTime(value: CMTimeValue(payload.endMs - payload.startMs), timescale: 1000)
+          session.timeRange = CMTimeRange(start: start, duration: duration)
+        }
+        if hasComposition {
+          session.videoComposition = FrameComposer.videoComposition(
+            for: exportAsset,
+            matrix: payload.colorMatrix,
+            overlays: payload.overlays
+          )
+        }
+        if let audioMix = audioMix {
+          session.audioMix = audioMix
+        }
+        self.session = session
+
+        await MainActor.run {
+          self.progressTimer = Timer.scheduledTimer(withTimeInterval: 0.2, repeats: true) { _ in
+            onProgress(Double(session.progress))
+          }
+        }
+
+        session.exportAsynchronously { [weak self] in
+          Task { @MainActor in
+            self?.progressTimer?.invalidate()
+            self?.progressTimer = nil
+          }
+          switch session.status {
+          case .completed:
+            onProgress(1.0)
+            Task { resolve(await Self.readResult(outURL)) }
+          case .cancelled:
+            reject("CANCELLED", "Export cancelled")
+          default:
+            reject("EXPORT_FAILED", session.error?.localizedDescription ?? "Export failed")
+          }
+        }
+      } catch {
+        reject("EXPORT_FAILED", error.localizedDescription)
+      }
+    }
+  }
+
+  func cancel() {
+    session?.cancelExport()
+  }
+
+  private static func readResult(_ url: URL) async -> [String: Any] {
+    let asset = AVURLAsset(url: url)
+    let durationSeconds = (try? await asset.load(.duration).seconds) ?? 0
+    let durationMs = durationSeconds.isFinite ? Int(durationSeconds * 1000) : 0
+
+    var width = 0
+    var height = 0
+    if let track = try? await asset.loadTracks(withMediaType: .video).first {
+      let naturalSize = (try? await track.load(.naturalSize)) ?? .zero
+      let transform = (try? await track.load(.preferredTransform)) ?? .identity
+      let resolved = naturalSize.applying(transform)
+      width = Int(abs(resolved.width))
+      height = Int(abs(resolved.height))
+    }
+
+    return [
+      "uri": url.absoluteString,
+      "width": width,
+      "height": height,
+      "durationMs": durationMs,
+    ]
+  }
+
+  static func urlFrom(_ uri: String) -> URL? {
+    if uri.hasPrefix("/") { return URL(fileURLWithPath: uri) }
+    return URL(string: uri)
+  }
+}

package/ios/FrameComposer.swift

@@ -0,0 +1,94 @@
+import AVFoundation
+import CoreImage
+import ImageIO
+
+enum FrameComposer {
+  private struct LoadedOverlay {
+    let frames: [CIImage]
+    let cumulative: [Double]
+    let total: Double
+    let rec: OverlayRecord
+
+    func image(at time: Double) -> CIImage {
+      if frames.count <= 1 || total <= 0 { return frames[0] }
+      let t = time.truncatingRemainder(dividingBy: total)
+      for (i, end) in cumulative.enumerated() where t < end { return frames[i] }
+      return frames[frames.count - 1]
+    }
+  }
+
+  static func videoComposition(
+    for asset: AVAsset,
+    matrix: [Double],
+    overlays: [OverlayRecord]
+  ) -> AVVideoComposition? {
+    let filter = ColorMatrixFilter.makeFilter(matrix)
+    let loaded = overlays.compactMap { load($0) }
+    if filter == nil && loaded.isEmpty { return nil }
+
+    return AVMutableVideoComposition(asset: asset) { request in
+      let extent = request.sourceImage.extent
+      var image = request.sourceImage.clampedToExtent()
+      if let filter = filter {
+        filter.setValue(image, forKey: kCIInputImageKey)
+        image = filter.outputImage?.cropped(to: extent) ?? image
+      }
+      let time = request.compositionTime.seconds
+      for overlay in loaded {
+        image = composite(overlay: overlay.image(at: time), over: image, frame: extent, rec: overlay.rec)
+      }
+      request.finish(with: image, context: nil)
+    }
+  }
+
+  private static func composite(overlay: CIImage, over base: CIImage, frame: CGRect, rec: OverlayRecord) -> CIImage {
+    let oe = overlay.extent
+    guard oe.width > 0, oe.height > 0, frame.width > 0, frame.height > 0 else { return base }
+    let sx = (rec.widthFraction * frame.width) / oe.width
+    let sy = (rec.heightFraction * frame.height) / oe.height
+    let cx = frame.minX + rec.centerX * frame.width
+    let cy = frame.minY + (1 - rec.centerY) * frame.height
+
+    let transform = CGAffineTransform(translationX: cx, y: cy)
+      .rotated(by: -rec.rotationDeg * .pi / 180)
+      .scaledBy(x: sx, y: sy)
+      .translatedBy(x: -oe.midX, y: -oe.midY)
+
+    return overlay.transformed(by: transform).composited(over: base)
+  }
+
+  private static func load(_ rec: OverlayRecord) -> LoadedOverlay? {
+    guard let url = fileURL(rec.uri) else { return nil }
+    if rec.animated, let source = CGImageSourceCreateWithURL(url as CFURL, nil) {
+      let count = CGImageSourceGetCount(source)
+      if count > 1 {
+        var frames: [CIImage] = []
+        var cumulative: [Double] = []
+        var acc = 0.0
+        for i in 0..<count {
+          guard let cg = CGImageSourceCreateImageAtIndex(source, i, nil) else { continue }
+          frames.append(CIImage(cgImage: cg))
+          acc += gifDelay(source, i)
+          cumulative.append(acc)
+        }
+        if !frames.isEmpty {
+          return LoadedOverlay(frames: frames, cumulative: cumulative, total: acc, rec: rec)
+        }
+      }
+    }
+    guard let image = CIImage(contentsOf: url) else { return nil }
+    return LoadedOverlay(frames: [image], cumulative: [0], total: 0, rec: rec)
+  }
+
+  private static func gifDelay(_ source: CGImageSource, _ index: Int) -> Double {
+    guard let props = CGImageSourceCopyPropertiesAtIndex(source, index, nil) as? [CFString: Any],
+          let gif = props[kCGImagePropertyGIFDictionary] as? [CFString: Any] else { return 0.1 }
+    let unclamped = gif[kCGImagePropertyGIFUnclampedDelayTime] as? Double
+    let delay = unclamped ?? (gif[kCGImagePropertyGIFDelayTime] as? Double) ?? 0.1
+    return delay > 0 ? delay : 0.1
+  }
+
+  private static func fileURL(_ uri: String) -> URL? {
+    uri.hasPrefix("/") ? URL(fileURLWithPath: uri) : (URL(string: uri) ?? URL(fileURLWithPath: uri))
+  }
+}