munim-ffmpeg 0.1.1 → 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

@@ -61,19 +61,20 @@
 
 **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 Android artifact is GPL-enabled and includes x264/x265; distributing it can trigger GPLv3 obligations. The native dependencies and FFmpeg retain their own licenses. Review [Native dependencies and licensing](#native-dependencies-and-licensing) before distributing an app.
+> **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)
-- [Native dependencies and licensing](#native-dependencies-and-licensing)
+- [Licensing](#licensing)
 - [🔍 Troubleshooting](#-troubleshooting)
 - [Development](#development)
 - [👏 Contributing](#-contributing)
@@ -109,6 +110,7 @@
 - 📱 **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
 
@@ -125,9 +127,61 @@
 | 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.                                                                                                                 |
-| Remote HTTP(S) inputs        | Build-dependent | Build-dependent | The bundled variants include HTTPS support, but remote server behavior and protocol support can vary. Prefer local files for predictable app workflows. |
+| 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 listed below. Do not assume every FFmpeg codec or external library is bundled.
+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
 
@@ -205,7 +259,7 @@ No camera, microphone, photo-library, or storage permission is added automatical
 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 are the most predictable inputs and outputs.
+- `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.
@@ -343,6 +397,44 @@ Returns the version reported by the bundled native FFmpeg library.
 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
@@ -358,6 +450,8 @@ type FFmpegSessionResult = {
 }
 ```
 
+`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
@@ -391,6 +485,34 @@ if (!result.success) {
 }
 ```
 
+### 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)
+```
+
 ### Generate a thumbnail
 
 ```typescript
@@ -456,23 +578,25 @@ if (result.success) {
 }
 ```
 
-## Native dependencies and licensing
+## 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:
 
-The JavaScript, TypeScript, Swift, Kotlin, and generated Nitro bridge code in this repository are Apache-2.0 licensed. Native FFmpeg binaries are supplied by separate compatibility packages:
+| 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) |
 
-| Platform | Native dependency                                   | Version |
-| -------- | --------------------------------------------------- | ------- |
-| iOS      | `ffmpeg-kit-ios-https-alt`                          | 6.0     |
-| Android  | `io.github.jamaismagic.ffmpeg:ffmpeg-kit-main-16kb` | 6.1.4   |
+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.
 
-The bundled Android 6.1.4 artifact is GPL-enabled and includes x264 and x265. Distributing an Android application with this dependency can trigger GPLv3 source, license, and redistribution obligations. Its published Maven metadata does not fully communicate that posture, so assess the binaries and their notices rather than relying only on the POM license field.
+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`.
 
-FFmpeg's effective license depends on the enabled libraries, codecs, and build configuration. Before distributing an application:
+Before distributing an application:
 
 1. Review the license and notices shipped by each native dependency.
-2. Identify the codecs and linked libraries used by your product.
+2. Identify the codecs and linked libraries your product actually uses.
 3. Follow the applicable LGPL, GPL, attribution, relinking, and source-offer requirements.
-4. Treat the current Android build as GPL-enabled, and reassess licensing again if you replace either native dependency.
+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.
 
@@ -496,7 +620,7 @@ Rebuild the native app after installing both `munim-ffmpeg` and `react-native-ni
 
 ### A codec or filter is missing
 
-Native FFmpeg variants do not bundle every codec, filter, or third-party library. Check `getFFmpegVersion()` and the session output, then choose a bundled codec or replace the native dependency with a build whose licensing and features fit your application.
+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
 
@@ -504,24 +628,46 @@ Inspect `result.success`, `result.cancelled`, `result.returnCode`, `result.outpu
 
 ### 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 used by Nitro's Swift/C++ bridge.
+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 codegen
-npm run typecheck
-npm run typecheck:example
-npm run build
-npm run pack:dry-run
+npm run check   # codegen, typecheck, example typecheck, build, pack dry-run
 ```
 
-Run the Expo example with:
+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
@@ -529,15 +675,18 @@ npm run example:ios
 npm run example:android
 ```
 
-Releases are validated and published manually; this repository does not use GitHub Actions:
+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
-cd packages/munim-ffmpeg
-npm publish --access public
+npm run release:local
 ```
 
-Nitrogen output under `packages/munim-ffmpeg/nitrogen/generated` is committed. Change the `.nitro.ts` specification and rerun codegen instead of editing generated files directly.
+`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
 

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/app.plugin.js

@@ -1,8 +1,28 @@
-const { withGradleProperties } = require('expo/config-plugins')
+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(
@@ -30,8 +50,44 @@ function withAndroidPackaging(config) {
   })
 }
 
+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 withAndroidPackaging(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.1",
+  "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",
@@ -61,6 +66,9 @@
     "transcoding",
     "munim-technologies"
   ],
+  "workspaces": [
+    "example"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/munimtechnologies/munim-ffmpeg.git"
@@ -83,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