munim-ffmpeg 0.1.0 → 0.2.0

package/NitroMunimFfmpeg.podspec

@@ -27,10 +27,11 @@ Pod::Spec.new do |s|
 
   s.dependency 'React-jsi'
   s.dependency 'React-callinvoker'
-  s.dependency 'ffmpeg-kit-ios-https-alt', '6.0'
+  s.dependency 'ffmpeg-kit-ios-full-gpl-alt', '6.0'
 
   # ffmpeg-kit 6.0 declares negative Level values with an unsigned backing type.
   # Xcode 26 rejects that header when Nitro enables Swift C++ interoperability.
+  # The script locates Level.h by globbing, so it survives a change of FFmpegKit pod.
   s.script_phase = {
     :name => 'Patch FFmpegKit Level enum for Xcode 26',
     :script => '"${RUBY_EXECUTABLE:-/usr/bin/ruby}" "${PODS_TARGET_SRCROOT}/scripts/patch-ffmpegkit-level.rb"',

package/README.md

@@ -1,33 +1,274 @@
-# munim-ffmpeg
+<p align="center">
+  <a href="https://github.com/munimtechnologies/munim-ffmpeg">
+    <img alt="Munim Technologies" height="128" src="https://raw.githubusercontent.com/munimtechnologies/munim-ffmpeg/main/.github/resources/banner.png?v=1" />
+    <h1 align="center">munim-ffmpeg</h1>
+  </a>
+</p>
 
-Fast FFmpeg and FFprobe for Expo and React Native, powered by [Nitro Modules](https://nitro.margelo.com/).
+<p align="center">
+  <a aria-label="Package version" href="https://www.npmjs.com/package/munim-ffmpeg">
+    <img alt="Package version" src="https://img.shields.io/npm/v/munim-ffmpeg.svg?style=flat-square&label=Version&labelColor=000000&color=0066CC" />
+  </a>
+  <a aria-label="Package is free to use" href="https://github.com/munimtechnologies/munim-ffmpeg/blob/main/LICENSE">
+    <img alt="License: Apache-2.0" src="https://img.shields.io/badge/License-Apache%202.0-success.svg?style=flat-square&color=33CC12" />
+  </a>
+  <a aria-label="Monthly package downloads" href="https://www.npmtrends.com/munim-ffmpeg">
+    <img alt="Monthly downloads" src="https://img.shields.io/npm/dm/munim-ffmpeg.svg?style=flat-square&labelColor=gray&color=33CC12&label=Downloads" />
+  </a>
+  <a aria-label="Total package downloads" href="https://www.npmjs.com/package/munim-ffmpeg">
+    <img alt="Total downloads" src="https://img.shields.io/npm/dt/munim-ffmpeg.svg?style=flat-square&labelColor=gray&color=0066CC&label=Total%20Downloads" />
+  </a>
+  <a aria-label="Expo development builds" href="https://docs.expo.dev/develop/development-builds/introduction/">
+    <img alt="Expo development builds" src="https://img.shields.io/badge/Expo-Development%20Build-000020?style=flat-square&logo=expo&logoColor=white" />
+  </a>
+  <a aria-label="iOS 15.1 or newer" href="https://developer.apple.com/ios/">
+    <img alt="iOS 15.1+" src="https://img.shields.io/badge/iOS-15.1%2B-000000?style=flat-square&logo=apple&logoColor=white" />
+  </a>
+  <a aria-label="Android API 24 or newer" href="https://developer.android.com/">
+    <img alt="Android API 24+" src="https://img.shields.io/badge/Android-API%2024%2B-3DDC84?style=flat-square&logo=android&logoColor=white" />
+  </a>
+  <a aria-label="Powered by Nitro Modules" href="https://nitro.margelo.com/">
+    <img alt="Nitro Modules 0.36.5+" src="https://img.shields.io/badge/Nitro%20Modules-0.36.5%2B-7C3AED?style=flat-square" />
+  </a>
+</p>
 
-## Features
+<p align="center">
+  <a aria-label="Works with Expo" href="https://docs.expo.dev/develop/development-builds/introduction/"><b>Works with Expo development builds</b></a>
+  &ensp;•&ensp;
+  <a aria-label="Documentation" href="https://www.munimtech.com/opensource/munim-ffmpeg">Read the Documentation</a>
+  &ensp;•&ensp;
+  <a aria-label="Report issues" href="https://github.com/munimtechnologies/munim-ffmpeg/issues">Report Issues</a>
+</p>
 
-- Execute FFmpeg and FFprobe with argument arrays—no shell-string escaping.
-- Receive FFmpeg logs and encoding statistics in JavaScript.
-- Inspect media as parsed FFprobe JSON.
-- Cancel one session or all active sessions.
-- Autolinks in Expo development builds and bare React Native apps.
+<h6 align="center">Follow Munim Technologies</h6>
+<p align="center">
+  <a aria-label="Munim Technologies on GitHub" href="https://github.com/munimtechnologies">
+    <img alt="Munim Technologies on GitHub" src="https://img.shields.io/badge/GitHub-222222?style=for-the-badge&logo=github&logoColor=white" />
+  </a>&nbsp;
+  <a aria-label="Munim Technologies on LinkedIn" href="https://linkedin.com/in/sheehanmunim">
+    <img alt="Munim Technologies on LinkedIn" src="https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white" />
+  </a>&nbsp;
+  <a aria-label="Munim Technologies website" href="https://www.munimtech.com">
+    <img alt="Munim Technologies website" src="https://img.shields.io/badge/Website-0066CC?style=for-the-badge&logo=googlechrome&logoColor=white" />
+  </a>
+</p>
 
-## Installation
+## Introduction
 
-```sh
+**munim-ffmpeg** provides fast, typed FFmpeg and FFprobe access for Expo and React Native. It executes argument arrays directly through native FFmpeg libraries, streams logs and encoding statistics to JavaScript, returns structured session results, inspects media with FFprobe, and cancels one running session or every active session.
+
+**Built with React Native Nitro Modules.** One TypeScript specification generates the C++, Swift, and Kotlin bindings used by the package.
+
+**Designed for Expo development builds and bare React Native.** This package contains native code and cannot run in Expo Go.
+
+> **Licensing note:** The JavaScript and Nitro bridge are Apache-2.0. The bundled native FFmpeg builds are not: the Android artifact is **GPLv3** (it links x264, x265, and xvid) and the iOS artifact is **LGPLv3**. Distributing either carries obligations. Read [Bundled FFmpeg builds](#bundled-ffmpeg-builds) before shipping.
+
+## Table of contents
+
+- [📚 Documentation](#-documentation)
+- [🚀 Features](#-features)
+- [Platform support matrix](#platform-support-matrix)
+- [Bundled FFmpeg builds](#bundled-ffmpeg-builds)
+- [📦 Installation](#-installation)
+- [Working with media paths](#working-with-media-paths)
+- [⚡ Quick start](#-quick-start)
+- [🔧 API reference](#-api-reference)
+- [📖 Usage examples](#-usage-examples)
+- [Licensing](#licensing)
+- [🔍 Troubleshooting](#-troubleshooting)
+- [Development](#development)
+- [👏 Contributing](#-contributing)
+- [📄 License](#-license)
+
+## 📚 Documentation
+
+- [Munim Technologies package documentation](https://www.munimtech.com/opensource/munim-ffmpeg)
+- [Installation](#-installation)
+- [API reference](#-api-reference)
+- [Usage examples](#-usage-examples)
+- [Troubleshooting](#-troubleshooting)
+
+## 🚀 Features
+
+### FFmpeg execution
+
+- 🎬 **Argument-array commands:** Avoid platform-specific shell parsing and quoting
+- ⚡ **Asynchronous sessions:** Keep the React Native thread responsive during native work
+- 📝 **Live logs:** Receive FFmpeg output as it is produced
+- 📈 **Encoding statistics:** Track time, size, bitrate, speed, frames, FPS, and quality
+- 🎯 **Targeted cancellation:** Capture a native session ID immediately and cancel only that command
+- 🛑 **Global cancellation:** Stop all active sessions during workflow or screen cleanup
+
+### FFprobe and media inspection
+
+- 🔎 **FFprobe execution:** Run custom probing commands with the same typed session result
+- 🧾 **Parsed media information:** Inspect format, streams, chapters, codecs, duration, and metadata as JSON
+- ✅ **Structured completion:** Read return code, state, duration, output, cancellation state, and failure details
+
+### React Native integration
+
+- 📱 **iOS and Android:** Native implementations in Swift and Kotlin
+- 🧬 **Nitro Modules:** Generated high-performance native bindings
+- 🚀 **Expo compatible:** Autolinking, config plugin, and an Expo development example
+- 🧪 **Capability discovery:** Ask the bundled build which encoders and decoders it actually has
+- 🎯 **TypeScript:** Complete public callback and result types
+- 🗂️ **16 KB Android support:** Uses a maintained FFmpegKit-compatible Android artifact with 16 KB page-size support
+
+## Platform support matrix
+
+| Capability                   | iOS             | Android         | Notes                                                                                                                                                   |
+| ---------------------------- | --------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| FFmpeg argument execution    | ✅              | ✅              | Commands run asynchronously through the native compatibility library.                                                                                   |
+| FFprobe argument execution   | ✅              | ✅              | Custom FFprobe arguments return `FFmpegSessionResult`.                                                                                                  |
+| Parsed media information     | ✅              | ✅              | `getMediaInformation()` returns parsed FFprobe JSON.                                                                                                    |
+| Log callback                 | ✅              | ✅              | Logs are delivered while a session is active.                                                                                                           |
+| Encoding-statistics callback | ✅              | ✅              | Available for FFmpeg execution.                                                                                                                         |
+| Immediate session ID         | ✅              | ✅              | `onSessionCreated` fires after the native session is created.                                                                                           |
+| Cancel one FFmpeg session    | ✅              | ✅              | Pass the positive safe-integer ID received by `execute`'s `onSessionCreated`. The native dependency does not expose FFprobe cancellation.               |
+| Cancel all FFmpeg sessions   | ✅              | ✅              | Use `cancelAll()` or call `cancel()` without an ID.                                                                                                     |
+| Expo Go                      | ❌              | ❌              | A native development build is required.                                                                                                                 |
+| Capability discovery         | ✅              | ✅              | `listEncoders()`, `listDecoders()`, and `pickEncoder()` report what the bundled build supports.                                                          |
+| H.264 encoding               | VideoToolbox    | libx264         | The builds differ; use `pickEncoder(['libx264', 'h264_videotoolbox'])` instead of hard-coding an encoder.                                                |
+| Remote HTTP(S) inputs        | ✅              | ✅              | Both builds link GnuTLS. Remote server behaviour still varies; prefer local files for predictable app workflows.                                         |
+
+Codec availability is determined by the native FFmpeg builds described in [Bundled FFmpeg builds](#bundled-ffmpeg-builds). Do not assume every FFmpeg codec or external library is present.
+
+## Bundled FFmpeg builds
+
+FFmpegKit was retired upstream in 2025 and its official binaries were withdrawn, so this package depends on maintained community rebuilds. The two platforms are **not** the same build:
+
+| | iOS | Android |
+| --- | --- | --- |
+| Artifact | `ffmpeg-kit-ios-full-gpl-alt` 6.0 | `io.github.jamaismagic.ffmpeg:ffmpeg-kit-main-16kb` 6.1.7 |
+| FFmpeg | n6.0 | n6.1.4 |
+| Effective license | LGPLv3 | **GPLv3** |
+| Hardware codecs | VideoToolbox, AudioToolbox | MediaCodec |
+| 16 KB page size | n/a | ✅ (required by Google Play) |
+
+Despite its name, the iOS pod ships FFmpeg's non-GPL configuration: it has no `libx264`, `libx265`, or `libxvid`. No public GPL build of FFmpegKit for iOS exists since the upstream retirement.
+
+### Encoders
+
+Verified by running the example's device suite on both platforms: iOS reports 201 encoders, Android 196, with 181 in common. Everything FFmpeg builds natively (`aac`, `alac`, `flac`, `mpeg4`, `mjpeg`, `png`, `gif`, `pcm_*`, …) is available on both, as are `libmp3lame`, `libopus`, `libvpx` (VP8), and `libvpx-vp9`.
+
+The differences that matter:
+
+| Encoder | iOS | Android |
+| --- | --- | --- |
+| `libx264` / `libx264rgb` (H.264, software) | ❌ | ✅ |
+| `libx265` (HEVC, software) | ❌ | ✅ |
+| `h264_videotoolbox`, `hevc_videotoolbox`, `prores_videotoolbox` | ✅ | ❌ |
+| `h264_mediacodec`, `hevc_mediacodec`, `vp8_mediacodec`, `vp9_mediacodec`, `av1_mediacodec` | ❌ | ✅ |
+| `libkvazaar` (HEVC, software) | ✅ | ❌ |
+| `libtheora`, `libvorbis`, `libwebp` | ✅ | ❌ |
+| `libspeex`, `libshine`, `libtwolame`, `libilbc`, `libopencore_amrnb`, `libvo_amrwbenc` | ✅ | ❌ |
+| `aac_at`, `alac_at`, `ilbc_at` (AudioToolbox) | ✅ | ❌ |
+
+iOS additionally links libass, so subtitle burn-in filters work there but not on Android.
+
+Both platforms can encode H.264 and HEVC — just not with the same encoder name. Resolve it at runtime instead of branching on `Platform.OS`:
+
+```typescript
+import { execute, pickEncoder } from 'munim-ffmpeg'
+
+const h264 = await pickEncoder(['libx264', 'h264_videotoolbox'])
+if (!h264) throw new Error('No H.264 encoder in this build')
+
+await execute(['-y', '-i', inputPath, '-c:v', h264, outputPath])
+```
+
+Decoding is far more uniform: both builds decode H.264, HEVC, VP8/VP9, AV1 (`libdav1d`), MPEG-4, MP3, AAC, Vorbis, Opus, FLAC, and the usual container formats. Both link GnuTLS, so `https://` inputs work.
+
+The Android build is compiled with `--disable-indev=lavfi`, so `-f lavfi -i testsrc=...` and other virtual inputs are iOS-only. Feed real files or raw frames instead.
+
+> **Avoid the `-full` and `-full-gpl` Android artifacts.** Their `libavdevice.so` references hidapi symbols that nothing in the package provides, so FFmpegKit fails to initialise at runtime with `UnsatisfiedLinkError: cannot locate symbol "PLATFORM_hid_write"`.
+
+## 📦 Installation
+
+### React Native CLI
+
+```bash
+npm install munim-ffmpeg react-native-nitro-modules
+# or
+yarn add munim-ffmpeg react-native-nitro-modules
+```
+
+Install iOS pods after adding the dependency:
+
+```bash
+cd ios
+pod install
+cd ..
+```
+
+FFmpegKit and React Native both provide `libc++_shared.so`. Resolve that duplicate in the Android application module:
+
+```groovy
+android {
+  packagingOptions {
+    jniLibs {
+      pickFirsts += ['**/libc++_shared.so']
+    }
+  }
+}
+```
+
+### Expo
+
+```bash
 npx expo install munim-ffmpeg react-native-nitro-modules
 ```
 
-This package contains native code, so it does not run in Expo Go. Create a development build after installing it:
+The package includes an Expo config plugin. If your project manages its plugin list explicitly, add it to `app.json`:
+
+```json
+{
+  "expo": {
+    "plugins": ["munim-ffmpeg"]
+  }
+}
+```
+
+The plugin also configures Android to select one shared C++ runtime when React Native and FFmpegKit contribute the same `libc++_shared.so` path.
+
+Create a native development build after installation:
 
-```sh
+```bash
 npx expo prebuild
 npx expo run:ios
 # or
 npx expo run:android
 ```
 
-## Usage
+You can also create an [EAS development build](https://docs.expo.dev/develop/development-builds/create-a-build/).
+
+> **Important:** `munim-ffmpeg` cannot run in Expo Go because Expo Go does not include this package's native libraries.
+
+### Requirements
+
+- React Native with the New Architecture enabled
+- `react-native-nitro-modules` 0.36.5 or newer
+- iOS 15.1 or newer
+- Android API 24 or newer
+- An Expo development build or bare React Native app
+
+No camera, microphone, photo-library, or storage permission is added automatically. Declare only the permissions required by the locations and capture APIs your application uses.
+
+## Working with media paths
+
+FFmpeg runs natively and needs a path or URI the native process can access.
+
+- Prefer files inside your app's document, cache, or temporary directory.
+- `file://` URIs and plain local paths both work. The package strips the `file://` scheme and percent-decoding for you, so a path containing spaces or non-ASCII characters is handled correctly; passing the raw URI straight to FFmpeg would write to a file literally named `my%20clip.mp4`.
+- On Android, copy a `content://` document into application storage before processing when the native library cannot open it directly.
+- Copy photo-library or document-picker assets when the provider gives temporary or security-scoped access.
+- Ensure the output directory already exists.
+- Use a unique output filename or pass `-y` when replacing an existing file is intentional.
+- Do not include the `ffmpeg` or `ffprobe` executable name in the argument array.
+
+## ⚡ Quick start
 
-```ts
+```typescript
 import {
   cancel,
   execute,
@@ -36,60 +277,429 @@ import {
   probe,
 } from 'munim-ffmpeg'
 
+console.log('FFmpeg:', getFFmpegVersion())
+
 let activeSessionId: number | undefined
 
 const execution = execute(
-  ['-i', inputUri, '-c:v', 'mpeg4', '-c:a', 'aac', outputUri],
+  ['-y', '-i', inputPath, '-c:v', 'mpeg4', '-c:a', 'aac', outputPath],
   (message) => console.log(message),
-  (timeMs, sizeBytes, bitrateKbits, speed) => {
-    console.log({ timeMs, sizeBytes, bitrateKbits, speed })
+  (timeMs, sizeBytes, bitrateKbits, speed, frame, fps, quality) => {
+    console.log({
+      timeMs,
+      sizeBytes,
+      bitrateKbits,
+      speed,
+      frame,
+      fps,
+      quality,
+    })
   },
   (sessionId) => {
     activeSessionId = sessionId
   }
 )
 
-// From a cancel button while the command is running:
-if (activeSessionId !== undefined) cancel(activeSessionId)
+// Call this from a cancel button while the command is running.
+if (activeSessionId !== undefined) {
+  cancel(activeSessionId)
+}
 
 const result = await execution
 
+if (!result.success && !result.cancelled) {
+  throw new Error(result.failStackTrace ?? result.output)
+}
+
+const probeResult = await probe([
+  '-v',
+  'error',
+  '-show_format',
+  '-show_streams',
+  inputPath,
+])
+
+const mediaInformation = await getMediaInformation(inputPath)
+```
+
+## 🔧 API reference
+
+### `execute(arguments, onLog?, onStatistics?, onSessionCreated?)`
+
+Starts an asynchronous FFmpeg session.
+
+```typescript
+function execute(
+  arguments_: string[],
+  onLog?: (message: string) => void,
+  onStatistics?: (
+    timeMs: number,
+    sizeBytes: number,
+    bitrateKbits: number,
+    speed: number,
+    videoFrameNumber: number,
+    fps: number,
+    quality: number
+  ) => void,
+  onSessionCreated?: (sessionId: number) => void
+): Promise<FFmpegSessionResult>
+```
+
+The `onSessionCreated` callback receives the ID before the command completes, allowing targeted cancellation while work is running.
+
+### `probe(arguments, onLog?, onSessionCreated?)`
+
+Starts an asynchronous FFprobe session.
+
+```typescript
+function probe(
+  arguments_: string[],
+  onLog?: (message: string) => void,
+  onSessionCreated?: (sessionId: number) => void
+): Promise<FFmpegSessionResult>
+```
+
+`onSessionCreated` can be used to correlate the native probe session with its eventual result. The bundled native dependency does not expose FFprobe cancellation.
+
+### `getMediaInformation(path)`
+
+Runs FFprobe for the format, streams, and chapters at a local media path, then parses its JSON response.
+
+```typescript
+function getMediaInformation(path: string): Promise<unknown>
+```
+
+Applications should validate or narrow the returned JSON shape before using fields from it.
+
+### `cancel(sessionId?)`
+
+Cancels the given native FFmpeg execution session. Calling `cancel()` without an ID cancels all active FFmpeg sessions. FFprobe cancellation is not exposed by the bundled native dependency.
+
+```typescript
+function cancel(sessionId?: number): void
+```
+
+Session IDs must be positive safe integers received from `onSessionCreated` or `FFmpegSessionResult`.
+
+### `cancelAll()`
+
+Cancels every active FFmpeg session.
+
+```typescript
+function cancelAll(): void
+```
+
+### `getFFmpegVersion()`
+
+Returns the version reported by the bundled native FFmpeg library.
+
+```typescript
+function getFFmpegVersion(): string
+```
+
+### `listEncoders()`
+
+Returns the encoder names the bundled FFmpeg build can write. The result is cached after the first call.
+
+```typescript
+function listEncoders(): Promise<string[]>
+```
+
+### `listDecoders()`
+
+Returns the decoder names the bundled FFmpeg build can read.
+
+```typescript
+function listDecoders(): Promise<string[]>
+```
+
+### `pickEncoder(candidates)`
+
+Returns the first name in `candidates` that the build provides, or `undefined` when none are available. Use it to write one command that runs on both platforms.
+
+```typescript
+function pickEncoder(candidates: string[]): Promise<string | undefined>
+```
+
+```typescript
+const hevc = await pickEncoder(['libx265', 'hevc_videotoolbox'])
+```
+
+### `normalizePath(value)`
+
+Converts a `file://` URI into the plain path FFmpeg expects, and returns anything else untouched.
+
+```typescript
+function normalizePath(value: string): string
+```
+
+`execute()`, `probe()`, and `getMediaInformation()` already apply this to every argument, so you rarely need to call it directly. It is exported for cases where you build a path yourself — a concat list file, for example, whose entries FFmpeg reads verbatim.
+
+### `FFmpegSessionResult`
+
+```typescript
+type FFmpegSessionResult = {
+  sessionId: number
+  returnCode: number
+  success: boolean
+  cancelled: boolean
+  state: string
+  durationMs: number
+  output: string
+  failStackTrace?: string
+}
+```
+
+`state` is one of `created`, `running`, `failed`, or `completed`, and reports the same values on both platforms.
+
+Always check `success` or `cancelled`; Promise resolution means the native session completed, not necessarily that FFmpeg returned a success code.
+
+## 📖 Usage examples
+
+### Inspect media metadata
+
+```typescript
+import { getMediaInformation } from 'munim-ffmpeg'
+
+const information = await getMediaInformation(inputPath)
+console.log(JSON.stringify(information, null, 2))
+```
+
+### Extract an audio track
+
+```typescript
+import { execute } from 'munim-ffmpeg'
+
+const result = await execute([
+  '-y',
+  '-i',
+  inputPath,
+  '-vn',
+  '-c:a',
+  'aac',
+  outputAudioPath,
+])
+
 if (!result.success) {
   throw new Error(result.failStackTrace ?? result.output)
 }
+```
 
-const information = await getMediaInformation(inputUri)
-const probeResult = await probe(['-v', 'error', '-show_streams', inputUri])
-const version = getFFmpegVersion()
+### Transcode to H.264 on both platforms
+
+```typescript
+import { execute, pickEncoder } from 'munim-ffmpeg'
+
+const encoder = await pickEncoder(['libx264', 'h264_videotoolbox'])
+if (!encoder) throw new Error('No H.264 encoder available in this build')
+
+// -preset is an x264 option; VideoToolbox rejects it.
+const quality = encoder === 'libx264' ? ['-preset', 'veryfast', '-crf', '23'] : ['-b:v', '2M']
+
+const result = await execute([
+  '-y',
+  '-i',
+  inputPath,
+  '-c:v',
+  encoder,
+  ...quality,
+  '-c:a',
+  'aac',
+  '-pix_fmt',
+  'yuv420p',
+  outputPath,
+])
+
+if (!result.success) throw new Error(result.failStackTrace ?? result.output)
 ```
 
-Use native filesystem paths or `file://` URIs that the app can access. Android `content://` input may need to be copied into application storage first.
+### Generate a thumbnail
 
-## API
+```typescript
+import { execute } from 'munim-ffmpeg'
 
-- `execute(arguments, onLog?, onStatistics?, onSessionCreated?)` returns `Promise<FFmpegSessionResult>`.
-- `probe(arguments, onLog?, onSessionCreated?)` returns `Promise<FFmpegSessionResult>`.
-- `getMediaInformation(path)` returns parsed FFprobe JSON.
-- `cancel(sessionId?)` cancels one running session using the ID from `onSessionCreated`, or all sessions when no ID is supplied.
-- `cancelAll()` cancels all sessions.
-- `getFFmpegVersion()` returns the bundled FFmpeg version.
+const result = await execute([
+  '-y',
+  '-ss',
+  '00:00:01.000',
+  '-i',
+  inputPath,
+  '-frames:v',
+  '1',
+  outputImagePath,
+])
+```
 
-## Native dependencies and licensing
+### Cancel a long-running command
 
-The JavaScript and native bridge code in this repository is Apache-2.0 licensed. The distributed native FFmpeg dependencies are separate works with their own licenses:
+```typescript
+import { cancel, execute } from 'munim-ffmpeg'
 
-- Android: `io.github.jamaismagic.ffmpeg:ffmpeg-kit-main-16kb:6.1.4`
-- iOS: `ffmpeg-kit-ios-https-alt` 6.0
+let sessionId: number | undefined
 
-Those packages are FFmpegKit-compatible builds. FFmpeg and optional linked libraries may impose LGPL, GPL, attribution, or source-offer obligations depending on the build and codecs you distribute. Review the dependency licenses for your application before shipping.
+const execution = execute(
+  ['-i', inputPath, '-c:v', 'mpeg4', outputPath],
+  undefined,
+  undefined,
+  (createdSessionId) => {
+    sessionId = createdSessionId
+  }
+)
 
-## Requirements
+const cancelCurrentCommand = () => {
+  if (sessionId !== undefined) {
+    cancel(sessionId)
+  }
+}
 
-- Expo development build or bare React Native app with the New Architecture enabled
-- React Native Nitro Modules
-- iOS 15.1 or newer (as determined by the React Native minimum)
-- Android API 24 or newer
+const result = await execution
+console.log(result.cancelled)
+```
+
+### Run a custom FFprobe query
+
+```typescript
+import { probe } from 'munim-ffmpeg'
+
+const result = await probe([
+  '-v',
+  'error',
+  '-select_streams',
+  'v:0',
+  '-show_entries',
+  'stream=codec_name,width,height,duration',
+  '-of',
+  'json',
+  inputPath,
+])
+
+if (result.success) {
+  console.log(result.output)
+}
+```
+
+## Licensing
+
+The JavaScript, TypeScript, Swift, Kotlin, and generated Nitro bridge code in this repository are Apache-2.0. The native FFmpeg binaries are not, and the two platforms differ:
+
+| Platform | Native dependency | Version | Effective license |
+| -------- | ----------------- | ------- | ----------------- |
+| iOS      | `ffmpeg-kit-ios-full-gpl-alt` | 6.0 | LGPLv3 (`--enable-version3`, no GPL libraries linked) |
+| Android  | `io.github.jamaismagic.ffmpeg:ffmpeg-kit-main-16kb` | 6.1.7 | **GPLv3** (`--enable-gpl` with x264 and x265) |
+
+The Android artifact's published Maven metadata claims LGPL-3.0. That metadata is wrong: the shipped `libavcodec.so` is configured with `--enable-gpl` and the AAR bundles the x264 and x265 license notices. Treat the Android build as GPLv3.
+
+Distributing an Android application built against it can trigger GPLv3 source, license, and redistribution obligations for your application. If that does not suit your product, replace the Android dependency in `android/build.gradle` with a non-GPL FFmpegKit artifact; H.264 encoding then relies on `h264_mediacodec`.
+
+Before distributing an application:
+
+1. Review the license and notices shipped by each native dependency.
+2. Identify the codecs and linked libraries your product actually uses.
+3. Follow the applicable LGPL, GPL, attribution, relinking, and source-offer requirements.
+4. Reassess licensing whenever you replace a native dependency.
+
+See [FFmpeg legal guidance](https://ffmpeg.org/legal.html). This section is an engineering reminder, not legal advice.
+
+## 🔍 Troubleshooting
+
+### `munim-ffmpeg` is unavailable in Expo Go
+
+This is expected. Install the package and create an Expo development build with `npx expo run:ios`, `npx expo run:android`, or EAS Build.
+
+### Nitro reports that `MunimFfmpeg` cannot be found
+
+Rebuild the native app after installing both `munim-ffmpeg` and `react-native-nitro-modules`. Restarting Metro alone cannot add a native module to an existing binary.
+
+### FFmpeg cannot open an input or output
+
+- Confirm the file exists and the app can read it.
+- Confirm the output directory already exists and is writable.
+- Copy Android `content://` inputs into app storage.
+- Copy temporary picker or photo-library assets when necessary.
+- Log the exact argument array and native output while removing private path data from bug reports.
+
+### A codec or filter is missing
+
+Native FFmpeg variants do not bundle every codec, filter, or third-party library, and the iOS and Android builds are not identical. Call `listEncoders()` or `listDecoders()` to see what the running build actually has, and prefer `pickEncoder()` over a hard-coded name. `libx264` in particular exists only on Android — see [Bundled FFmpeg builds](#bundled-ffmpeg-builds).
+
+### The Promise resolved but the command failed
+
+Inspect `result.success`, `result.cancelled`, `result.returnCode`, `result.output`, and `result.failStackTrace`. A resolved Promise represents a completed native session; FFmpeg can still finish with a nonzero return code.
+
+### iOS pod or build errors
+
+Run `pod install` after installation and rebuild from a clean native development build. The package includes a narrowly scoped Xcode 26 compatibility patch for the FFmpegKit `Level` enum, which Nitro's Swift/C++ bridge otherwise rejects. The patch locates the header by globbing, so it keeps working if you swap the FFmpegKit pod.
+
+### `building for iOS Simulator, but linking ... built for iOS`
+
+The FFmpegKit pod tells consuming apps to exclude `arm64` from Simulator builds, which breaks Apple Silicon Macs even though its xcframework contains an `arm64` Simulator slice. The Expo config plugin removes that exclusion automatically. In a bare React Native app, add the same fix to your `Podfile`:
+
+```ruby
+post_install do |installer|
+  installer.pods_project.build_configurations.each do |config|
+    config.build_settings.delete('EXCLUDED_ARCHS[sdk=iphonesimulator*]')
+  end
+  installer.aggregate_targets.each do |aggregate_target|
+    aggregate_target.xcconfigs.each do |config_name, xcconfig|
+      xcconfig.attributes.delete('EXCLUDED_ARCHS[sdk=iphonesimulator*]')
+      xcconfig.save_as(Pathname.new(aggregate_target.xcconfig_path(config_name)))
+    end
+  end
+end
+```
+
+### Android build errors
+
+Use Android API 24 or newer, JDK 17, and the React Native New Architecture. Clear stale Gradle build output after changing native dependency versions.
+
+If the build fails on duplicate `libc++_shared.so`, make sure the config plugin ran (Expo) or add `android.packagingOptions.pickFirsts=**/libc++_shared.so` to `gradle.properties` (bare React Native). FFmpegKit and React Native both ship that library.
+
+## Development
+
+```bash
+npm install
+npm run check   # codegen, typecheck, example typecheck, build, pack dry-run
+```
+
+Individual steps are available as `npm run codegen`, `typecheck`, `typecheck:example`, and `build`.
+
+Nitrogen output under `nitrogen/generated` is committed. Change the `.nitro.ts` specification and rerun `npm run codegen` instead of editing generated files directly.
+
+### Example app
+
+`example/` is an Expo app that runs a 24-check device suite: H.264 and HEVC encoding, VP9/Opus in WebM, MP3, AAC, scaling and multi-step filter graphs, muxing, demuxing, trimming, concatenation, thumbnails, audio resampling, awkward file paths, concurrent sessions, single and global cancellation, protocol support, and both failure paths. Fixtures are generated in JavaScript, so the suite needs no network or bundled media. Results are rendered on screen, written to `munim-ffmpeg-suite.json` in the app's document directory, and logged as `MUNIM_FFMPEG_SUITE_RESULT`.
+
+```bash
+npm run example:ios
+# or
+npm run example:android
+```
+
+FFmpeg encoding is slow in a simulator or emulator; run the suite on a physical device.
+
+### Releasing
+
+Releases run locally from a clean `main`; this repository does not use GitHub Actions.
+
+```bash
+npm run check
+npm run release:local
+```
+
+`release:local` runs semantic-release with the npm token from the macOS Keychain and the GitHub CLI token, so commit messages must follow Conventional Commits.
+
+## 👏 Contributing
+
+Issues and pull requests are welcome. Include the following when reporting a problem:
+
+- iOS or Android version and device architecture
+- Expo SDK and React Native versions
+- `react-native-nitro-modules` version
+- Command arguments with private paths and URLs removed
+- `FFmpegSessionResult` and relevant native logs
+
+Please keep licensing implications explicit when proposing a new FFmpeg binary variant, codec, or linked library.
 
-## License
+## 📄 License
 
-Apache-2.0
+The `munim-ffmpeg` source is available under the [Apache License 2.0](./LICENSE). Native FFmpeg dependencies are licensed separately as described above.

package/android/build.gradle

@@ -140,5 +140,8 @@ dependencies {
   implementation project(":react-native-nitro-modules")
 
   // Maintained FFmpegKit-compatible Android artifact with 16 KB page support.
-  implementation "io.github.jamaismagic.ffmpeg:ffmpeg-kit-main-16kb:6.1.4"
+  // Do not move to the `-full`/`-full-gpl` variants: their libavdevice.so
+  // references hidapi symbols that nothing provides, so FFmpegKit fails to load
+  // at runtime with UnsatisfiedLinkError.
+  implementation "io.github.jamaismagic.ffmpeg:ffmpeg-kit-main-16kb:6.1.7"
 }

package/android/src/main/java/com/margelo/nitro/munimffmpeg/HybridMunimFfmpeg.kt

@@ -43,8 +43,8 @@ class HybridMunimFfmpeg : HybridMunimFfmpegSpec() {
             statistics.bitrate,
             statistics.speed,
             statistics.videoFrameNumber.toDouble(),
-            statistics.videoFps,
-            statistics.videoQuality,
+            statistics.videoFps.toDouble(),
+            statistics.videoQuality.toDouble(),
           )
         },
       )

package/app.plugin.js

@@ -1,5 +1,93 @@
+const fs = require('node:fs')
+const path = require('node:path')
+const {
+  withDangerousMod,
+  withGradleProperties,
+} = require('expo/config-plugins')
+
+const PICK_FIRSTS_PROPERTY = 'android.packagingOptions.pickFirsts'
+const CXX_SHARED_LIBRARY = '**/libc++_shared.so'
+
+const PODFILE_MARKER = '# munim-ffmpeg: allow arm64 iOS Simulator builds'
+const PODFILE_SNIPPET = `    ${PODFILE_MARKER}
+    # The FFmpegKit pod excludes arm64 from Simulator builds, which breaks Apple
+    # Silicon Macs even though its xcframework ships an arm64 Simulator slice.
+    installer.pods_project.build_configurations.each do |config|
+      config.build_settings.delete('EXCLUDED_ARCHS[sdk=iphonesimulator*]')
+    end
+    installer.aggregate_targets.each do |aggregate_target|
+      aggregate_target.xcconfigs.each do |config_name, xcconfig|
+        xcconfig.attributes.delete('EXCLUDED_ARCHS[sdk=iphonesimulator*]')
+        xcconfig.save_as(Pathname.new(aggregate_target.xcconfig_path(config_name)))
+      end
+    end
+`
+
+function withAndroidPackaging(config) {
+  return withGradleProperties(config, (gradleConfig) => {
+    const existing = gradleConfig.modResults.find(
+      (item) => item.type === 'property' && item.key === PICK_FIRSTS_PROPERTY
+    )
+
+    if (existing) {
+      const values = new Set(
+        existing.value
+          .split(',')
+          .map((value) => value.trim())
+          .filter(Boolean)
+      )
+      values.add(CXX_SHARED_LIBRARY)
+      existing.value = [...values].join(',')
+    } else {
+      gradleConfig.modResults.push({
+        type: 'property',
+        key: PICK_FIRSTS_PROPERTY,
+        value: CXX_SHARED_LIBRARY,
+      })
+    }
+
+    return gradleConfig
+  })
+}
+
+function withSimulatorArchitectures(config) {
+  return withDangerousMod(config, [
+    'ios',
+    (modConfig) => {
+      const podfilePath = path.join(
+        modConfig.modRequest.platformProjectRoot,
+        'Podfile'
+      )
+
+      if (!fs.existsSync(podfilePath)) return modConfig
+
+      const contents = fs.readFileSync(podfilePath, 'utf8')
+      if (contents.includes(PODFILE_MARKER)) return modConfig
+
+      const postInstall = /^([ \t]*)post_install do \|(\w+)\|[ \t]*$/m
+      const match = contents.match(postInstall)
+
+      if (!match) {
+        console.warn(
+          'munim-ffmpeg: no post_install block found in the Podfile; arm64 Simulator builds may fail.'
+        )
+        return modConfig
+      }
+
+      const snippet = PODFILE_SNIPPET.replace(/\binstaller\b/g, match[2])
+      const patched = contents.replace(
+        postInstall,
+        (line) => `${line}\n${snippet}`
+      )
+
+      fs.writeFileSync(podfilePath, patched)
+      return modConfig
+    },
+  ])
+}
+
 module.exports = function withMunimFfmpeg(config) {
-  return config
+  return withSimulatorArchitectures(withAndroidPackaging(config))
 }
 
 module.exports.default = module.exports

package/ios/HybridMunimFfmpeg.swift

@@ -128,6 +128,18 @@ final class HybridMunimFfmpeg: HybridMunimFfmpegSpec {
     FFmpegKit.cancel()
   }
 
+  // `String(describing:)` on the imported NS_ENUM yields "sessionstate(rawvalue: 3)".
+  // Android reports the Java enum name, so map to the same lowercase names here.
+  private static func stateName(_ state: SessionState) -> String {
+    switch state {
+    case .created: return "created"
+    case .running: return "running"
+    case .failed: return "failed"
+    case .completed: return "completed"
+    @unknown default: return "unknown"
+    }
+  }
+
   private static func result(from session: Session) -> FFmpegSessionResult {
     let returnCode = session.getReturnCode()
     return FFmpegSessionResult(
@@ -135,7 +147,7 @@ final class HybridMunimFfmpeg: HybridMunimFfmpegSpec {
       returnCode: Double(returnCode?.getValue() ?? -1),
       success: ReturnCode.isSuccess(returnCode),
       cancelled: ReturnCode.isCancel(returnCode),
-      state: String(describing: session.getState()).lowercased(),
+      state: Self.stateName(session.getState()),
       durationMs: Double(session.getDuration()),
       output: session.getOutput() ?? "",
       failStackTrace: session.getFailStackTrace()

package/lib/index.d.ts

@@ -1,10 +1,33 @@
 import type { FFmpegLogCallback, FFmpegSessionResult, FFmpegSessionCreatedCallback, FFmpegStatisticsCallback, MunimFfmpeg as MunimFfmpegSpec } from './specs/MunimFfmpeg.nitro';
 declare const MunimFfmpeg: MunimFfmpegSpec;
 export type { FFmpegLogCallback, FFmpegSessionResult, FFmpegSessionCreatedCallback, FFmpegStatisticsCallback, MunimFfmpegSpec, };
+/**
+ * Converts a `file://` URI into the plain path FFmpeg expects.
+ *
+ * `expo-file-system` and `react-native-fs` hand back percent-encoded URIs, but
+ * FFmpeg's file protocol treats what follows `file://` literally: a path with a
+ * space silently becomes a file named `my%20clip.mp4`. Anything that is not a
+ * `file://` URI is returned untouched, so pipes, `content://`, and remote URLs
+ * still work.
+ */
+export declare function normalizePath(value: string): string;
 export declare function execute(arguments_: string[], onLog?: FFmpegLogCallback, onStatistics?: FFmpegStatisticsCallback, onSessionCreated?: FFmpegSessionCreatedCallback): Promise<FFmpegSessionResult>;
 export declare function probe(arguments_: string[], onLog?: FFmpegLogCallback, onSessionCreated?: FFmpegSessionCreatedCallback): Promise<FFmpegSessionResult>;
 export declare function getMediaInformation(path: string): Promise<unknown>;
 export declare function cancel(sessionId?: number): void;
 export declare function cancelAll(): void;
 export declare function getFFmpegVersion(): string;
+/** Encoder names the bundled FFmpeg build can write, e.g. `libx264`. */
+export declare function listEncoders(): Promise<string[]>;
+/** Decoder names the bundled FFmpeg build can read, e.g. `h264`. */
+export declare function listDecoders(): Promise<string[]>;
+/**
+ * Returns the first available encoder from `candidates`, so one command can
+ * run on both platforms:
+ *
+ * ```ts
+ * const encoder = await pickEncoder(['libx264', 'h264_videotoolbox'])
+ * ```
+ */
+export declare function pickEncoder(candidates: string[]): Promise<string | undefined>;
 export default MunimFfmpeg;

package/lib/index.js

@@ -1,13 +1,34 @@
 import { NitroModules } from 'react-native-nitro-modules';
 const MunimFfmpeg = NitroModules.createHybridObject('MunimFfmpeg');
+const FILE_URI_SCHEME = /^file:\/\//;
+/**
+ * Converts a `file://` URI into the plain path FFmpeg expects.
+ *
+ * `expo-file-system` and `react-native-fs` hand back percent-encoded URIs, but
+ * FFmpeg's file protocol treats what follows `file://` literally: a path with a
+ * space silently becomes a file named `my%20clip.mp4`. Anything that is not a
+ * `file://` URI is returned untouched, so pipes, `content://`, and remote URLs
+ * still work.
+ */
+export function normalizePath(value) {
+    if (!FILE_URI_SCHEME.test(value))
+        return value;
+    const path = value.replace(FILE_URI_SCHEME, '');
+    try {
+        return decodeURIComponent(path);
+    }
+    catch {
+        return path;
+    }
+}
 export function execute(arguments_, onLog, onStatistics, onSessionCreated) {
-    return MunimFfmpeg.execute(arguments_, onLog, onStatistics, onSessionCreated);
+    return MunimFfmpeg.execute(arguments_.map(normalizePath), onLog, onStatistics, onSessionCreated);
 }
 export function probe(arguments_, onLog, onSessionCreated) {
-    return MunimFfmpeg.probe(arguments_, onLog, onSessionCreated);
+    return MunimFfmpeg.probe(arguments_.map(normalizePath), onLog, onSessionCreated);
 }
 export function getMediaInformation(path) {
-    return MunimFfmpeg.getMediaInformation(path).then((value) => JSON.parse(value));
+    return MunimFfmpeg.getMediaInformation(normalizePath(path)).then((value) => JSON.parse(value));
 }
 export function cancel(sessionId) {
     MunimFfmpeg.cancel(sessionId);
@@ -18,4 +39,53 @@ export function cancelAll() {
 export function getFFmpegVersion() {
     return MunimFfmpeg.ffmpegVersion;
 }
+// The bundled FFmpeg builds differ per platform: Android ships libx264/libx265,
+// iOS ships the VideoToolbox hardware encoders instead. Asking the binary what
+// it supports is more reliable than hard-coding a per-platform table.
+const codecCache = new Map();
+function listCodecs(flag) {
+    const cached = codecCache.get(flag);
+    if (cached)
+        return cached;
+    const request = execute(['-hide_banner', flag])
+        .then((result) => {
+        if (!result.success) {
+            throw new Error(result.failStackTrace ?? result.output);
+        }
+        // Each entry is printed as `<capability flags> <name> <description>`
+        // below a line of dashes.
+        const body = result.output.split(/^\s*-+\s*$/m).pop() ?? '';
+        return body
+            .split('\n')
+            .map((line) => line.trim().split(/\s+/))
+            .filter((columns) => columns.length >= 2 && /^[A-Z.]{6}$/.test(columns[0]))
+            .map((columns) => columns[1]);
+    })
+        .catch((error) => {
+        codecCache.delete(flag);
+        throw error;
+    });
+    codecCache.set(flag, request);
+    return request;
+}
+/** Encoder names the bundled FFmpeg build can write, e.g. `libx264`. */
+export function listEncoders() {
+    return listCodecs('-encoders');
+}
+/** Decoder names the bundled FFmpeg build can read, e.g. `h264`. */
+export function listDecoders() {
+    return listCodecs('-decoders');
+}
+/**
+ * Returns the first available encoder from `candidates`, so one command can
+ * run on both platforms:
+ *
+ * ```ts
+ * const encoder = await pickEncoder(['libx264', 'h264_videotoolbox'])
+ * ```
+ */
+export async function pickEncoder(candidates) {
+    const encoders = new Set(await listEncoders());
+    return candidates.find((candidate) => encoders.has(candidate));
+}
 export default MunimFfmpeg;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "munim-ffmpeg",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Fast FFmpeg and FFprobe for Expo and React Native, powered by Nitro Modules",
   "main": "lib/index",
   "module": "lib/index",
@@ -23,23 +23,28 @@
     "ios/**/*.mm",
     "ios/**/*.cpp",
     "ios/**/*.swift",
-    "scripts",
     "app.plugin.js",
     "nitro.json",
     "*.podspec",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "scripts/patch-ffmpegkit-level.rb"
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "clean": "rm -rf android/build node_modules/**/android/build lib",
-    "lint": "eslint \"**/*.{js,ts,tsx}\" --fix",
-    "lint-ci": "eslint \"**/*.{js,ts,tsx}\" -f @jamesacarr/github-actions --max-warnings 0",
+    "typecheck:example": "tsc --noEmit -p example/tsconfig.json",
+    "clean": "rm -rf lib android/build example/ios example/android",
+    "lint": "eslint .",
+    "codegen": "nitrogen --logLevel=\"debug\"",
+    "specs": "npm run codegen",
     "build": "npm run typecheck && tsc",
     "prepack": "npm run build",
-    "typescript": "tsc",
-    "codegen": "nitrogen --logLevel=\"debug\"",
-    "specs": "npm run codegen"
+    "check": "npm run codegen && npm run typecheck && npm run typecheck:example && npm run build && npm pack --dry-run",
+    "example:start": "npm --workspace example run start",
+    "example:ios": "npm --workspace example run ios",
+    "example:android": "npm --workspace example run android",
+    "release:local": "node scripts/release-local.mjs",
+    "format": "prettier --write \"**/*.{ts,tsx,js,cjs,mjs,json,md}\""
   },
   "keywords": [
     "react-native",
@@ -53,8 +58,17 @@
     "typescript",
     "nitro",
     "nitro-modules",
+    "react-native-ffmpeg",
+    "expo-plugin",
+    "video-processing",
+    "audio-processing",
+    "media-processing",
+    "transcoding",
     "munim-technologies"
   ],
+  "workspaces": [
+    "example"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/munimtechnologies/munim-ffmpeg.git"
@@ -77,49 +91,30 @@
     ]
   },
   "devDependencies": {
-    "@react-native/eslint-config": "0.85.3",
+    "@eslint/eslintrc": "^3.3.6",
+    "@eslint/js": "^9.39.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
     "@types/react": "^19.2.15",
+    "conventional-changelog-conventionalcommits": "^9.3.1",
     "eslint": "^9.39.4",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.5",
+    "globals": "^17.11.0",
     "nitrogen": "0.36.5",
     "prettier": "^3.8.3",
     "react": "19.2.3",
     "react-native": "0.86.2",
     "react-native-nitro-modules": "^0.36.5",
-    "typescript": "^6.0.3"
+    "semantic-release": "^25.0.9",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.46.0"
   },
   "peerDependencies": {
     "react": "*",
     "react-native": "*",
     "react-native-nitro-modules": ">=0.36.5 <1"
   },
-  "eslintConfig": {
-    "root": true,
-    "extends": [
-      "@react-native",
-      "prettier"
-    ],
-    "plugins": [
-      "prettier"
-    ],
-    "rules": {
-      "prettier/prettier": [
-        "warn",
-        {
-          "quoteProps": "consistent",
-          "singleQuote": true,
-          "tabWidth": 2,
-          "trailingComma": "es5",
-          "useTabs": false
-        }
-      ]
-    }
-  },
-  "eslintIgnore": [
-    "node_modules/",
-    "lib/"
-  ],
   "prettier": {
     "quoteProps": "consistent",
     "singleQuote": true,

package/scripts/patch-ffmpegkit-level.rb

@@ -3,24 +3,22 @@
 require 'fileutils'
 require 'tempfile'
 
+# FFmpegKit 6.0 declares `Level` with an unsigned backing type while assigning
+# negative values to it. Clang accepts that in Objective-C, but Xcode 26 rejects
+# the header once Nitro turns on Swift/C++ interoperability, so every vendored
+# and copied copy of Level.h is rewritten to a signed enum before compiling.
+#
+# The header is located by globbing rather than by pod name: the FFmpegKit
+# republishes lay their xcframeworks out differently (`<pod>/ffmpegkit.xcframework`
+# versus `<pod>/xcframeworks/ffmpegkit.xcframework`), and the pod itself may be
+# swapped for another variant.
 pods_root = ENV.fetch('PODS_ROOT')
 build_products = ENV.fetch('PODS_CONFIGURATION_BUILD_DIR')
-source_root = File.join(pods_root, 'ffmpeg-kit-ios-https-alt', 'ffmpegkit.xcframework')
-
-# Patch only the two vendored slices and CocoaPods' selected build product. Nitro's
-# Swift/C++ bridge imports the selected header after this before-compile phase.
-headers = [
-  File.join(source_root, 'ios-arm64', 'ffmpegkit.framework', 'Headers', 'Level.h'),
-  File.join(source_root, 'ios-arm64_x86_64-simulator', 'ffmpegkit.framework', 'Headers', 'Level.h'),
-  File.join(
-    build_products,
-    'XCFrameworkIntermediates',
-    'ffmpeg-kit-ios-https-alt',
-    'ffmpegkit.framework',
-    'Headers',
-    'Level.h'
-  ),
-].select { |path| File.file?(path) }
+
+headers = [pods_root, build_products]
+          .flat_map { |root| Dir.glob(File.join(root, '**', 'ffmpegkit.framework', 'Headers', 'Level.h')) }
+          .uniq
+          .select { |path| File.file?(path) }
 
 abort('munim-ffmpeg: could not find the expected FFmpegKit Level.h') if headers.empty?
 

package/src/index.ts

@@ -18,13 +18,40 @@ export type {
   MunimFfmpegSpec,
 }
 
+const FILE_URI_SCHEME = /^file:\/\//
+
+/**
+ * Converts a `file://` URI into the plain path FFmpeg expects.
+ *
+ * `expo-file-system` and `react-native-fs` hand back percent-encoded URIs, but
+ * FFmpeg's file protocol treats what follows `file://` literally: a path with a
+ * space silently becomes a file named `my%20clip.mp4`. Anything that is not a
+ * `file://` URI is returned untouched, so pipes, `content://`, and remote URLs
+ * still work.
+ */
+export function normalizePath(value: string): string {
+  if (!FILE_URI_SCHEME.test(value)) return value
+
+  const path = value.replace(FILE_URI_SCHEME, '')
+  try {
+    return decodeURIComponent(path)
+  } catch {
+    return path
+  }
+}
+
 export function execute(
   arguments_: string[],
   onLog?: FFmpegLogCallback,
   onStatistics?: FFmpegStatisticsCallback,
   onSessionCreated?: FFmpegSessionCreatedCallback
 ): Promise<FFmpegSessionResult> {
-  return MunimFfmpeg.execute(arguments_, onLog, onStatistics, onSessionCreated)
+  return MunimFfmpeg.execute(
+    arguments_.map(normalizePath),
+    onLog,
+    onStatistics,
+    onSessionCreated
+  )
 }
 
 export function probe(
@@ -32,11 +59,15 @@ export function probe(
   onLog?: FFmpegLogCallback,
   onSessionCreated?: FFmpegSessionCreatedCallback
 ): Promise<FFmpegSessionResult> {
-  return MunimFfmpeg.probe(arguments_, onLog, onSessionCreated)
+  return MunimFfmpeg.probe(
+    arguments_.map(normalizePath),
+    onLog,
+    onSessionCreated
+  )
 }
 
 export function getMediaInformation(path: string): Promise<unknown> {
-  return MunimFfmpeg.getMediaInformation(path).then((value) =>
+  return MunimFfmpeg.getMediaInformation(normalizePath(path)).then((value) =>
     JSON.parse(value)
   )
 }
@@ -53,4 +84,64 @@ export function getFFmpegVersion(): string {
   return MunimFfmpeg.ffmpegVersion
 }
 
+// The bundled FFmpeg builds differ per platform: Android ships libx264/libx265,
+// iOS ships the VideoToolbox hardware encoders instead. Asking the binary what
+// it supports is more reliable than hard-coding a per-platform table.
+const codecCache = new Map<string, Promise<string[]>>()
+
+function listCodecs(flag: '-encoders' | '-decoders'): Promise<string[]> {
+  const cached = codecCache.get(flag)
+  if (cached) return cached
+
+  const request = execute(['-hide_banner', flag])
+    .then((result) => {
+      if (!result.success) {
+        throw new Error(result.failStackTrace ?? result.output)
+      }
+
+      // Each entry is printed as `<capability flags> <name> <description>`
+      // below a line of dashes.
+      const body = result.output.split(/^\s*-+\s*$/m).pop() ?? ''
+      return body
+        .split('\n')
+        .map((line) => line.trim().split(/\s+/))
+        .filter(
+          (columns) => columns.length >= 2 && /^[A-Z.]{6}$/.test(columns[0]!)
+        )
+        .map((columns) => columns[1]!)
+    })
+    .catch((error) => {
+      codecCache.delete(flag)
+      throw error
+    })
+
+  codecCache.set(flag, request)
+  return request
+}
+
+/** Encoder names the bundled FFmpeg build can write, e.g. `libx264`. */
+export function listEncoders(): Promise<string[]> {
+  return listCodecs('-encoders')
+}
+
+/** Decoder names the bundled FFmpeg build can read, e.g. `h264`. */
+export function listDecoders(): Promise<string[]> {
+  return listCodecs('-decoders')
+}
+
+/**
+ * Returns the first available encoder from `candidates`, so one command can
+ * run on both platforms:
+ *
+ * ```ts
+ * const encoder = await pickEncoder(['libx264', 'h264_videotoolbox'])
+ * ```
+ */
+export async function pickEncoder(
+  candidates: string[]
+): Promise<string | undefined> {
+  const encoders = new Set(await listEncoders())
+  return candidates.find((candidate) => encoders.has(candidate))
+}
+
 export default MunimFfmpeg