munim-ffmpeg 0.1.1 → 0.3.0

package/NitroMunimFfmpeg.podspec

@@ -18,24 +18,30 @@ Pod::Spec.new do |s|
     "ios/**/*.{swift}",
     # Autolinking/Registration (Objective-C++)
     "ios/**/*.{m,mm}",
+    # C core that drives FFmpeg's in-process command-line tools
+    "ios/*.h",
     # Implementation (C++ objects)
     "cpp/**/*.{hpp,cpp}",
   ]
 
+  # FFmpeg 9 and the in-process fftools core. Downloaded by
+  # scripts/fetch-binaries.mjs on install, or built by scripts/ffmpeg/build-all.sh.
+  s.vendored_frameworks = "ios/MunimFFmpeg.xcframework"
+  s.pod_target_xcconfig = {
+    "HEADER_SEARCH_PATHS" => "\"$(PODS_TARGET_SRCROOT)/ios\"",
+  }
+  s.frameworks = "AudioToolbox", "VideoToolbox", "CoreMedia", "AVFoundation", "CoreVideo", "Security"
+  s.libraries = "bz2", "z", "iconv", "c++"
+
+  # Must be public so CocoaPods puts it in the module umbrella, which is how the
+  # Swift implementation sees the C core.
+  s.public_header_files = "ios/munim_ffmpeg_core.h"
+
   load 'nitrogen/generated/ios/NitroMunimFfmpeg+autolinking.rb'
   add_nitrogen_files(s)
 
   s.dependency 'React-jsi'
   s.dependency 'React-callinvoker'
-  s.dependency 'ffmpeg-kit-ios-https-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.
-  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"',
-    :execution_position => :before_compile,
-  }
 
   install_modules_dependencies(s)
 end

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, Swift, Kotlin, and Nitro bridge are Apache-2.0. The bundled FFmpeg is **LGPLv3** on both platforms — it deliberately excludes x264, x265, and xvid, so your app does not inherit GPL obligations. See [Licensing](#licensing).
 
 ## 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)
@@ -91,7 +92,8 @@
 
 ### FFmpeg execution
 
-- 🎬 **Argument-array commands:** Avoid platform-specific shell parsing and quoting
+- 🎬 **Argument-array commands:** FFmpeg's own CLI code paths, without shell parsing or quoting
+- 🆕 **FFmpeg 9.0.1:** The current upstream release, identical on both platforms
 - ⚡ **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
@@ -109,8 +111,9 @@
 - 📱 **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
+- 🗂️ **16 KB Android pages:** Built with the alignment Google Play requires
 
 ## Platform support matrix
 
@@ -125,9 +128,54 @@
 | 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
+
+Both platforms run **FFmpeg 9.0.1**, built from [ffmpeg.org](https://www.ffmpeg.org/) by the scripts in [`scripts/ffmpeg/`](./scripts/ffmpeg). There is no FFmpegKit here: that project was retired in 2025 and pinned to FFmpeg 6.0.
+
+| | iOS | Android |
+| --- | --- | --- |
+| FFmpeg | 9.0.1 | 9.0.1 |
+| Architectures | arm64 device, arm64 + x86_64 simulator | arm64-v8a, armeabi-v7a, x86_64 |
+| Hardware codecs | VideoToolbox, AudioToolbox | MediaCodec |
+| TLS | SecureTransport | mbedTLS |
+| Minimum | iOS 15.1 | API 24, 16 KB pages |
+
+Linked libraries, identical on both: **LAME** (MP3), **Opus**, **libvpx** (VP8/VP9), **dav1d** (AV1 decoding), plus everything FFmpeg builds natively.
+
+FFmpeg's own `ffmpeg` and `ffprobe` tools are compiled to run inside your app process, so the argument arrays you pass are handled by the real command-line code paths rather than a reimplementation.
+
+### Encoders
+
+Verified by running the example's device suite: iOS reports 186 encoders, Android 184. Everything FFmpeg builds natively (`aac`, `alac`, `flac`, `mpeg4`, `mjpeg`, `png`, `gif`, `pcm_*`, …) is on both, as are `libmp3lame`, `libopus`, `libvpx`, and `libvpx-vp9`.
+
+H.264 and HEVC come from the platform's hardware encoder, which is faster and smaller than bundling x264 — and keeps the package LGPL:
+
+| Encoder | iOS | Android |
+| --- | --- | --- |
+| `h264_videotoolbox`, `hevc_videotoolbox`, `prores_videotoolbox` | ✅ | ❌ |
+| `h264_mediacodec`, `hevc_mediacodec`, `vp8_mediacodec`, `vp9_mediacodec` | ❌ | ✅ |
+| `aac_at`, `alac_at` (AudioToolbox) | ✅ | ❌ |
+
+Resolve the name at runtime instead of branching on `Platform.OS`:
+
+```typescript
+import { execute, pickEncoder } from 'munim-ffmpeg'
+
+const h264 = await pickEncoder(['h264_videotoolbox', 'h264_mediacodec'])
+if (!h264) throw new Error('No H.264 encoder in this build')
+
+await execute(['-y', '-i', inputPath, '-c:v', h264, outputPath])
+```
+
+Two things to know about hardware encoders: they want NV12 input on Android (`-pix_fmt nv12`) and planar YUV on iOS, and they reject very small frames — 176×144 is the smallest size that works everywhere.
+
+Decoding is uniform: H.264, HEVC, VP8/VP9, AV1, MPEG-4, MP3, AAC, Vorbis, Opus, FLAC and the usual containers, on both platforms. Both link TLS, so `https://` inputs work.
 
 ## 📦 Installation
 
@@ -147,7 +195,7 @@ pod install
 cd ..
 ```
 
-FFmpegKit and React Native both provide `libc++_shared.so`. Resolve that duplicate in the Android application module:
+FFmpeg and React Native both provide `libc++_shared.so`. Resolve that duplicate in the Android application module:
 
 ```groovy
 android {
@@ -175,7 +223,7 @@ The package includes an Expo config plugin. If your project manages its plugin l
 }
 ```
 
-The plugin also configures Android to select one shared C++ runtime when React Native and FFmpegKit contribute the same `libc++_shared.so` path.
+The plugin also configures Android to select one shared C++ runtime when React Native and FFmpeg contribute the same `libc++_shared.so` path.
 
 Create a native development build after installation:
 
@@ -190,6 +238,25 @@ You can also create an [EAS development build](https://docs.expo.dev/develop/dev
 
 > **Important:** `munim-ffmpeg` cannot run in Expo Go because Expo Go does not include this package's native libraries.
 
+### Native binaries
+
+The FFmpeg libraries are around 200 MB across all six architectures, which does not belong in an npm tarball, so they are downloaded from the matching GitHub release when the package installs and verified against the checksum in `scripts/binaries.json`.
+
+If your environment blocks install scripts (`npm install --ignore-scripts`), fetch them explicitly:
+
+```bash
+npx munim-ffmpeg-fetch-binaries
+```
+
+Behind a proxy or an air-gapped mirror, point the fetcher somewhere else:
+
+```bash
+MUNIM_FFMPEG_BINARIES_URL=https://internal.example.com/munim-ffmpeg-binaries.tar.gz \
+  npx munim-ffmpeg-fetch-binaries
+```
+
+Or build them yourself — see [`scripts/ffmpeg/README.md`](./scripts/ffmpeg/README.md).
+
 ### Requirements
 
 - React Native with the New Architecture enabled
@@ -205,7 +272,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 +410,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 +463,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 +498,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,25 +591,17 @@ if (result.success) {
 }
 ```
 
-## Native dependencies and licensing
-
-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:
+## Licensing
 
-| 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 JavaScript, TypeScript, Swift, Kotlin, C core, and generated Nitro bridge in this repository are Apache-2.0.
 
-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.
+The bundled FFmpeg 9.0.1 is **LGPLv3**, on both platforms. It is configured without `--enable-gpl`, so no x264, x265, xvid, or vid.stab: H.264 and HEVC encoding come from VideoToolbox and MediaCodec instead. The external libraries it does link are LAME (LGPL), Opus (BSD), libvpx (BSD), dav1d (BSD), and mbedTLS (Apache-2.0) on Android.
 
-FFmpeg's effective license depends on the enabled libraries, codecs, and build configuration. Before distributing an application:
+In practice that means your application does **not** inherit GPL obligations. LGPL still applies: the FFmpeg libraries are linked and their license and notices must be conveyed with your app, and users must be able to relink against a modified FFmpeg. The exact configuration used is recorded in [`scripts/ffmpeg/build-ios.sh`](./scripts/ffmpeg/build-ios.sh) and [`build-android.sh`](./scripts/ffmpeg/build-android.sh), and the binaries can be reproduced from them.
 
-1. Review the license and notices shipped by each native dependency.
-2. Identify the codecs and linked libraries used by your product.
-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.
+If you need x264 or x265, add `--enable-gpl --enable-libx264 --enable-libx265` to those scripts and rebuild — but then your application does inherit GPLv3.
 
-See [FFmpeg legal guidance](https://ffmpeg.org/legal.html). This section is an engineering reminder, not legal advice.
+See [FFmpeg legal guidance](https://ffmpeg.org/legal.html). This section is an engineering summary, not legal advice.
 
 ## 🔍 Troubleshooting
 
@@ -496,7 +623,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 +631,30 @@ 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. If the linker cannot find `MunimFFmpeg.xcframework`, the native binaries were not downloaded — run `npx munim-ffmpeg-fetch-binaries`.
 
 ### 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).
+
+If `System.loadLibrary` cannot find `munimffmpeg9`, the native binaries were not downloaded — run `npx munim-ffmpeg-fetch-binaries`.
+
 ## 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 +662,27 @@ 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.
+
+### Rebuilding FFmpeg
+
+```bash
+npm run binaries:build     # every architecture, ~40 minutes
+npm run binaries:package   # bundles them and records the checksum
+```
+
+See [`scripts/ffmpeg/README.md`](./scripts/ffmpeg/README.md) for what the build does and the platform quirks it works around.
+
+### 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. It also uploads `dist-binaries/munim-ffmpeg-binaries.tar.gz` to the GitHub release, which is where `postinstall` fetches it from — so run `npm run binaries:package` first.
 
 ## 👏 Contributing
 

package/android/build.gradle

@@ -139,6 +139,6 @@ dependencies {
   // Add a dependency on NitroModules
   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"
+  // FFmpeg 9 and the in-process fftools core ship as prebuilt .so files in
+  // src/main/jniLibs; see scripts/ffmpeg/ for the build.
 }

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

@@ -0,0 +1,86 @@
+package com.margelo.nitro.munimffmpeg
+
+import androidx.annotation.Keep
+import com.facebook.proguard.annotations.DoNotStrip
+
+/**
+ * Thin wrapper over FFmpeg 9's own command-line tools, compiled to run inside
+ * the app process.
+ *
+ * fftools keeps its parsed command in file-scope globals, so exactly one
+ * execution runs at a time; the native core serialises callers and cancels
+ * anything still queued when [nativeCancel] is called.
+ */
+@Keep
+@DoNotStrip
+object FFmpegNative {
+  init {
+    System.loadLibrary("munimffmpeg9")
+  }
+
+  /** Return code the tools report when a run was cancelled. */
+  const val CANCELLED = 255
+
+  external fun nativeVersion(): String
+
+  external fun nativeExecute(arguments: Array<String>, stdoutPath: String): Int
+
+  external fun nativeExecuteProbe(arguments: Array<String>, outputPath: String): Int
+
+  external fun nativeCancel()
+
+  data class Statistics(
+    val timeMs: Double,
+    val sizeBytes: Double,
+    val bitrateKbits: Double,
+    val speed: Double,
+    val videoFrameNumber: Double,
+    val fps: Double,
+    val quality: Double,
+  )
+
+  @Volatile
+  private var logSink: ((String) -> Unit)? = null
+
+  @Volatile
+  private var statisticsSink: ((Statistics) -> Unit)? = null
+
+  fun <T> withCallbacks(
+    onLog: ((String) -> Unit)?,
+    onStatistics: ((Statistics) -> Unit)?,
+    body: () -> T,
+  ): T {
+    logSink = onLog
+    statisticsSink = onStatistics
+    try {
+      return body()
+    } finally {
+      logSink = null
+      statisticsSink = null
+    }
+  }
+
+  @JvmStatic
+  @Keep
+  @DoNotStrip
+  fun onLog(message: String) {
+    logSink?.invoke(message)
+  }
+
+  @JvmStatic
+  @Keep
+  @DoNotStrip
+  fun onStatistics(
+    timeMs: Double,
+    sizeBytes: Double,
+    bitrateKbits: Double,
+    speed: Double,
+    videoFrameNumber: Double,
+    fps: Double,
+    quality: Double,
+  ) {
+    statisticsSink?.invoke(
+      Statistics(timeMs, sizeBytes, bitrateKbits, speed, videoFrameNumber, fps, quality)
+    )
+  }
+}