munim-ffmpeg 0.5.0 → 0.6.0

package/README.md

@@ -114,26 +114,31 @@
 - 🚀 **Expo compatible:** Autolinking, config plugin, and an Expo development example
 - 🧪 **Capability discovery:** Ask the bundled build which encoders, decoders, muxers, demuxers, filters, and protocols it actually has
 - 💬 **Subtitle burn-in:** libass renders ASS/SSA and SRT subtitles — styling, positioning, outlines, shadows, and proper Arabic/Urdu shaping via HarfBuzz and FriBidi
+- 📎 **Soft subtitle embedding:** Mux SRT/ASS tracks into MKV or MP4 so players can toggle them without re-encoding the video
+- 🖼️ **AVIF and AV1:** libaom encodes AV1 video and AVIF stills, dav1d decodes them
+- 📦 **One native library per platform:** a single `libmunimffmpeg.so` per Android ABI and one static library in the iOS xcframework, so nothing else has to be linked, loaded, or packaged
 - 🎯 **TypeScript:** Complete public callback and result types
 - 🗂️ **16 KB Android pages:** Built with the alignment Google Play requires
 
 ## 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()`, `listMuxers()`, `listDemuxers()`, `listFilters()`, `listProtocols()`, and `pickEncoder()` report what the bundled build supports. |
-| Subtitle burn-in             | ✅              | ✅              | libass with system fonts: Core Text on iOS, fontconfig over `/system/fonts` on Android.                                                                  |
-| 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.                                         |
+| 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()`, `listMuxers()`, `listDemuxers()`, `listFilters()`, `listProtocols()`, and `pickEncoder()` report what the bundled build supports.   |
+| Subtitle burn-in             | ✅           | ✅         | libass with system fonts: Core Text on iOS, fontconfig over `/system/fonts` on Android.                                                                                 |
+| H.264 encoding               | VideoToolbox | MediaCodec | Hardware on both, `libopenh264` as the software fallback; use `pickEncoder(['h264_videotoolbox', 'h264_mediacodec', 'libopenh264'])` instead of hard-coding an encoder. |
+| Remote HTTP(S) inputs        | ✅           | ✅         | iOS links SecureTransport, Android links mbedTLS. Remote server behaviour still varies; prefer local files for predictable app workflows.                               |
+| Soft subtitle embedding      | ✅           | ✅         | Mux SRT/ASS as toggleable tracks (MKV: `srt`/`ass`, MP4: `mov_text`).                                                                                                   |
+| AVIF / AV1 encoding          | ✅           | ✅         | `libaom-av1` encodes (add `-still-picture 1 -f avif` for images); `libdav1d` decodes.                                                                                   |
 
 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.
 
@@ -141,14 +146,14 @@ Codec availability is determined by the native FFmpeg builds described in [Bundl
 
 Every release runs the example's 25-check device suite. For 0.4.x:
 
-| Target | Result |
-| --- | --- |
-| iPad Air (M3), iOS 26 | 25/25 |
-| iOS Simulator, arm64 | 25/25 |
-| Galaxy A14 5G, arm64-v8a | 25/25 |
-| Android emulator, arm64 | Software encoding passes; hardware encoding does not — see below |
-| Android emulator, `x86_64` | Same: `libopenh264` passes, MediaCodec does not |
-| Android `armeabi-v7a` | Built and statically checked, not executed |
+| Target                     | Result                                                           |
+| -------------------------- | ---------------------------------------------------------------- |
+| iPad Air (M3), iOS 26      | 25/25                                                            |
+| iOS Simulator, arm64       | 25/25                                                            |
+| Galaxy A14 5G, arm64-v8a   | 25/25                                                            |
+| Android emulator, arm64    | Software encoding passes; hardware encoding does not — see below |
+| Android emulator, `x86_64` | Same: `libopenh264` passes, MediaCodec does not                  |
+| Android `armeabi-v7a`      | Built and statically checked, not executed                       |
 
 `x86_64` was verified on an Intel Windows machine, since the Android emulator refuses non-native system images on Apple Silicon: FFmpeg 9.0.1, 185 encoders, and the software H.264 encode passes. `armeabi-v7a` has no hardware to hand, so it was checked statically instead — correct ELF architecture, the expected JNI exports, only system libraries unresolved, and the same FFmpeg and codec set as arm64.
 
@@ -158,11 +163,20 @@ An Android emulator has no working MediaCodec **encoder**. `h264_mediacodec` and
 
 This is an emulator limitation, not a package one, but it is worth knowing before debugging: **test video encoding on a physical device**.
 
-`pickEncoder` cannot detect it, because MediaCodec *is* present in an emulator — it just does not work. When you need encoding to succeed regardless of environment, ask for the software encoder by name:
+`pickEncoder` cannot detect it, because MediaCodec _is_ present in an emulator — it just does not work. When you need encoding to succeed regardless of environment, ask for the software encoder by name:
 
 ```typescript
 // Deterministic anywhere: emulators, CI, older devices.
-await execute(['-y', '-i', input, '-c:v', 'libopenh264', '-pix_fmt', 'yuv420p', output])
+await execute([
+  '-y',
+  '-i',
+  input,
+  '-c:v',
+  'libopenh264',
+  '-pix_fmt',
+  'yuv420p',
+  output,
+])
 ```
 
 `libopenh264`, `mpeg4` and `libvpx-vp9` are all software encoders and work everywhere.
@@ -171,30 +185,34 @@ await execute(['-y', '-i', input, '-c:v', 'libopenh264', '-pix_fmt', 'yuv420p',
 
 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 |
+|                 | 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             |
+| Ships as        | `MunimFFmpeg.xcframework`, one static library per slice | one `libmunimffmpeg.so` per ABI |
 
-Linked libraries, identical on both: **LAME** (MP3), **Opus**, **libvpx** (VP8/VP9), **dav1d** (AV1 decoding), **openh264** (software H.264), **libass** with **FreeType**, **HarfBuzz**, and **FriBidi** (subtitle rendering and text shaping), plus everything FFmpeg builds natively. Android additionally links **fontconfig** and **expat** so libass can discover the system fonts; iOS uses Core Text for the same job.
+Linked libraries, identical on both: **LAME** (MP3), **Opus**, **libvpx** (VP8/VP9), **dav1d** (AV1 decoding), **libaom** (AV1 and AVIF encoding), **openh264** (software H.264), **libass** with **FreeType**, **HarfBuzz**, and **FriBidi** (subtitle rendering and text shaping), plus everything FFmpeg builds natively. Android additionally links **fontconfig** and **expat** so libass can discover the system fonts; iOS uses Core Text for the same job.
 
 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.
 
+Everything above is linked statically into a single library per platform: FFmpeg, both tools, the core, and every external library. On Android that is one `libmunimffmpeg.so` per ABI whose only dependencies are the system libraries and the `libc++_shared.so` React Native already bundles; on iOS it is one static library per slice inside `MunimFFmpeg.xcframework`. Only the JNI entry points are exported on Android, so the bundled FFmpeg cannot collide with another copy an app might carry.
+
 ### Encoders
 
 Verified by running the example's device suite: iOS reports 187 encoders, Android 185. 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 uses less power than a software encoder. `libopenh264` is there as a software H.264 fallback for anywhere hardware encoding is unavailable — an emulator, for instance:
 
-| Encoder | iOS | Android |
-| --- | --- | --- |
-| `h264_videotoolbox`, `hevc_videotoolbox`, `prores_videotoolbox` | ✅ | ❌ |
-| `h264_mediacodec`, `hevc_mediacodec`, `vp8_mediacodec`, `vp9_mediacodec` | ❌ | ✅ |
-| `aac_at`, `alac_at` (AudioToolbox) | ✅ | ❌ |
-| `libopenh264` (H.264, software) | ✅ | ✅ |
+| Encoder                                                                  | iOS | Android |
+| ------------------------------------------------------------------------ | --- | ------- |
+| `h264_videotoolbox`, `hevc_videotoolbox`, `prores_videotoolbox`          | ✅  | ❌      |
+| `h264_mediacodec`, `hevc_mediacodec`, `vp8_mediacodec`, `vp9_mediacodec` | ❌  | ✅      |
+| `aac_at`, `alac_at` (AudioToolbox)                                       | ✅  | ❌      |
+| `libopenh264` (H.264, software)                                          | ✅  | ✅      |
+| `libaom-av1` (AV1, software; AVIF stills)                                | ✅  | ✅      |
 
 Resolve the name at runtime instead of branching on `Platform.OS`:
 
@@ -214,7 +232,7 @@ 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.
+Decoding is uniform: H.264, HEVC, VP8/VP9, AV1 (via dav1d, including AVIF images), MPEG-4, MP3, AAC, Vorbis, Opus, FLAC and the usual containers, on both platforms. Both link TLS, so `https://` inputs work.
 
 ## 📦 Installation
 
@@ -279,7 +297,7 @@ You can also create an [EAS development build](https://docs.expo.dev/develop/dev
 
 ### 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`.
+The FFmpeg libraries are well over 100 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:
 
@@ -567,11 +585,16 @@ if (!result.success) {
 ```typescript
 import { execute, pickEncoder } from 'munim-ffmpeg'
 
-const encoder = await pickEncoder(['libx264', 'h264_videotoolbox'])
+const encoder = await pickEncoder([
+  'h264_videotoolbox',
+  'h264_mediacodec',
+  'libopenh264',
+])
 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']
+// MediaCodec wants NV12 input; the others take planar YUV.
+const pixelFormat = encoder === 'h264_mediacodec' ? 'nv12' : 'yuv420p'
+const quality = ['-b:v', '2M', '-pix_fmt', pixelFormat]
 
 const result = await execute([
   '-y',
@@ -607,6 +630,39 @@ const result = await execute([
 ])
 ```
 
+### Write an AVIF still
+
+AVIF is AV1 in an image container. `libaom-av1` encodes it; `-still-picture 1` switches the encoder into single-image mode and `-f avif` picks the container. Decoding an AVIF back — or any AV1 video — goes through dav1d automatically.
+
+```typescript
+await execute([
+  '-y',
+  '-ss',
+  '1.5',
+  '-i',
+  inputPath,
+  '-frames:v',
+  '1',
+  '-vf',
+  'scale=-2:720',
+  '-c:v',
+  'libaom-av1',
+  '-still-picture',
+  '1',
+  '-cpu-used',
+  '6', // 0 (slowest, best) … 8 (fastest)
+  '-crf',
+  '28', // quality; lower is larger
+  '-pix_fmt',
+  'yuv420p',
+  '-f',
+  'avif',
+  outputPath, // ends in .avif
+])
+```
+
+React Native's `<Image>` displays AVIF natively on iOS 16+ and Android 12+.
+
 ### Burn subtitles into a video
 
 The bundled builds include libass with FreeType, HarfBuzz, and FriBidi, so ASS/SSA styling and complex scripts (Arabic, Urdu, and other RTL or shaped text) render correctly. System fonts are found automatically — through Core Text on iOS and through fontconfig scanning `/system/fonts` on Android.
@@ -618,18 +674,24 @@ import { execute, normalizePath } from 'munim-ffmpeg'
 // shadows, positioning, karaoke — everything the format supports.
 await execute([
   '-y',
-  '-i', inputPath,
-  '-vf', `ass=filename=${normalizePath(subtitlePath)}`,
-  '-c:a', 'copy',
+  '-i',
+  inputPath,
+  '-vf',
+  `ass=filename=${normalizePath(subtitlePath)}`,
+  '-c:a',
+  'copy',
   outputPath,
 ])
 
 // SRT can be styled at burn time with force_style.
 await execute([
   '-y',
-  '-i', inputPath,
-  '-vf', `subtitles=filename=${normalizePath(srtPath)}:force_style='Fontsize=28,PrimaryColour=&H00FFFF00,Outline=2'`,
-  '-c:a', 'copy',
+  '-i',
+  inputPath,
+  '-vf',
+  `subtitles=filename=${normalizePath(srtPath)}:force_style='Fontsize=28,PrimaryColour=&H00FFFF00,Outline=2'`,
+  '-c:a',
+  'copy',
   outputPath,
 ])
 ```
@@ -646,19 +708,114 @@ import { execute } from 'munim-ffmpeg'
 // Bundle one video, two audio languages, and a subtitle track into MKV.
 await execute([
   '-y',
-  '-i', videoPath, '-i', urduAudioPath, '-i', subtitlePath,
-  '-map', '0:v:0', '-map', '0:a:0', '-map', '1:a:0', '-map', '2:s:0',
-  '-c:v', 'copy', '-c:a', 'aac', '-c:s', 'srt',
-  '-metadata:s:a:1', 'language=urd',
+  '-i',
+  videoPath,
+  '-i',
+  urduAudioPath,
+  '-i',
+  subtitlePath,
+  '-map',
+  '0:v:0',
+  '-map',
+  '0:a:0',
+  '-map',
+  '1:a:0',
+  '-map',
+  '2:s:0',
+  '-c:v',
+  'copy',
+  '-c:a',
+  'aac',
+  '-c:s',
+  'srt',
+  '-metadata:s:a:1',
+  'language=urd',
   outputMkvPath,
 ])
 
 // Extract the second audio track without re-encoding.
 await execute([
-  '-y', '-i', outputMkvPath, '-map', '0:a:1', '-c', 'copy', trackPath,
+  '-y',
+  '-i',
+  outputMkvPath,
+  '-map',
+  '0:a:1',
+  '-c',
+  'copy',
+  trackPath,
+])
+```
+
+### Embed soft subtitles
+
+The other subtitle workflow: instead of burning text into the frames, mux the subtitle file in as its own stream, so players can toggle it and the video is never re-encoded. Each container wants its own subtitle codec — MKV takes `srt` and `ass` (ASS keeps its styling), MP4 takes `mov_text`, WebM takes `webvtt`.
+
+```typescript
+import { execute } from 'munim-ffmpeg'
+
+// MKV with English SRT and styled Urdu ASS tracks, video and audio untouched.
+await execute([
+  '-y',
+  '-i',
+  videoPath,
+  '-i',
+  englishSrtPath,
+  '-i',
+  urduAssPath,
+  '-map',
+  '0:v:0',
+  '-map',
+  '0:a:0',
+  '-map',
+  '1:0',
+  '-map',
+  '2:0',
+  '-c:v',
+  'copy',
+  '-c:a',
+  'copy',
+  '-c:s:0',
+  'srt',
+  '-c:s:1',
+  'ass',
+  '-metadata:s:s:0',
+  'language=eng',
+  '-metadata:s:s:0',
+  'title=English',
+  '-metadata:s:s:1',
+  'language=urd',
+  '-metadata:s:s:1',
+  'title=Urdu',
+  outputMkvPath,
+])
+
+// MP4 needs mov_text instead.
+await execute([
+  '-y',
+  '-i',
+  videoPath,
+  '-i',
+  subtitlePath,
+  '-map',
+  '0:v:0',
+  '-map',
+  '0:a:0',
+  '-map',
+  '1:0',
+  '-c:v',
+  'copy',
+  '-c:a',
+  'copy',
+  '-c:s',
+  'mov_text',
+  '-metadata:s:s:0',
+  'language=eng',
+  outputMp4Path,
 ])
 ```
 
+Existing subtitle streams survive remuxing with `-map 0 -c copy`, and a soft track can later be burned in with `-vf subtitles=filename=input.mkv:si=0` (the `si` option picks the subtitle stream index).
+
 ### Cancel a long-running command
 
 ```typescript
@@ -711,9 +868,9 @@ if (result.success) {
 
 The JavaScript, TypeScript, Swift, Kotlin, C core, and generated Nitro bridge in this repository are Apache-2.0.
 
-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. The external libraries it links are LAME (LGPL), Opus (BSD), libvpx (BSD), dav1d (BSD), openh264 (BSD 2-clause), libass (ISC), FreeType (FTL, BSD-style with credit), HarfBuzz (MIT-style), FriBidi (LGPL), and, on Android only, mbedTLS (Apache-2.0), fontconfig (MIT-style), and expat (MIT). None of them change the LGPL story.
+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. The external libraries it links are LAME (LGPL), Opus (BSD), libvpx (BSD), dav1d (BSD), libaom (BSD 2-clause with the Alliance for Open Media patent licence), openh264 (BSD 2-clause), libass (ISC), FreeType (FTL, BSD-style with credit), HarfBuzz (MIT-style), FriBidi (LGPL), and, on Android only, mbedTLS (Apache-2.0), fontconfig (MIT-style), and expat (MIT). None of them change the LGPL story.
 
-> **A note on H.264 patents.** Hardware encoders are covered by the licences device manufacturers already pay for. Software H.264 encoding through `libopenh264` is not: Cisco's royalty coverage applies to *their* prebuilt binary, and this package builds openh264 from source. If you ship software H.264 encoding at scale, check where you stand with AVC licensing. Hardware encoders avoid the question entirely, which is why `pickEncoder` should list them first.
+> **A note on H.264 patents.** Hardware encoders are covered by the licences device manufacturers already pay for. Software H.264 encoding through `libopenh264` is not: Cisco's royalty coverage applies to _their_ prebuilt binary, and this package builds openh264 from source. If you ship software H.264 encoding at scale, check where you stand with AVC licensing. Hardware encoders avoid the question entirely, which is why `pickEncoder` should list them first.
 
 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.
 
@@ -741,7 +898,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, 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).
+Native FFmpeg variants do not bundle every codec, filter, or third-party library, and the iOS and Android builds are not identical. Call `listEncoders()`, `listDecoders()`, `listMuxers()`, `listDemuxers()`, `listFilters()`, or `listProtocols()` to see what the running build actually has, and prefer `pickEncoder()` over a hard-coded name. There is no `libx264` in these LGPL builds — H.264 comes from the platform's hardware encoder or `libopenh264` — see [Bundled FFmpeg builds](#bundled-ffmpeg-builds).
 
 ### The Promise resolved but the command failed
 
@@ -772,7 +929,10 @@ Nitrogen output under `nitrogen/generated` is committed. Change the `.nitro.ts`
 
 ### Example app
 
-`example/` is an Expo app that runs a 25-check device suite: H.264 and HEVC encoding, VP9/Opus in WebM, MP3, AAC, scaling and multi-step filter graphs, software H.264 via openh264, 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`.
+`example/` is an Expo SDK 57 app — a development build, since Expo Go cannot load native modules — with two screens:
+
+- **Playground** picks a video with `expo-document-picker` (or generates one from JavaScript fixtures), inspects it, transcodes it through the device's hardware H.264 encoder via `pickEncoder`, writes an AVIF still, embeds soft subtitles into an MKV, burns them in with libass, and shows progress from the statistics callback with a cancel button wired to `onSessionCreated`. Each action is a plain argument array, so [`example/Playground.tsx`](./example/Playground.tsx) doubles as a recipe book.
+- **Device suite** runs the 30+ checks used to verify every release: H.264 and HEVC encoding, VP9/Opus in WebM, MP3, AAC, AVIF, scaling and multi-step filter graphs, software H.264 via openh264, subtitle burn-in and embedding, muxing, demuxing, trimming, concatenation, thumbnails, audio resampling, awkward file paths, concurrent sessions, single and global cancellation, protocol support, and both failure paths. It runs on launch, renders each result, writes `munim-ffmpeg-suite.json` to the app's document directory, and logs it as `MUNIM_FFMPEG_SUITE_RESULT`.
 
 ```bash
 npm run example:ios
@@ -780,7 +940,7 @@ npm run example:ios
 npm run example:android
 ```
 
-FFmpeg encoding is slow in a simulator or emulator; run the suite on a physical device.
+FFmpeg encoding is slow in a simulator or emulator, and emulators have no working hardware encoder; run it on a physical device. [`example/README.md`](./example/README.md) has the details.
 
 ### Rebuilding FFmpeg
 
@@ -793,14 +953,16 @@ See [`scripts/ffmpeg/README.md`](./scripts/ffmpeg/README.md) for what the build
 
 ### Releasing
 
-Releases run locally from a clean `main`; this repository does not use GitHub Actions.
+Releases run locally from a clean `main`:
 
 ```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. 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.
+`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` and `build-info.txt` to the GitHub release, which is where `postinstall` fetches the binaries from — so run `npm run binaries:package` first.
+
+Two GitHub Actions workflows back this up: `CI` checks the JavaScript surface on every push and pull request, and `Build binaries` compiles every iOS and Android slice in parallel, on demand or when a pull request touches `scripts/ffmpeg/`, and can attach the result to a release. See [`scripts/ffmpeg/README.md`](./scripts/ffmpeg/README.md#building-in-github-actions).
 
 ## 👏 Contributing
 

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

@@ -5,6 +5,55 @@ import androidx.annotation.Keep
 import com.facebook.proguard.annotations.DoNotStrip
 import java.io.File
 
+/**
+ * Per-run callback target. The JNI bridge holds a global reference to this
+ * object for the duration of its execution and the native core only routes
+ * callbacks to whichever session actually holds the execution lock, so
+ * concurrently submitted sessions never see each other's logs.
+ */
+@Keep
+@DoNotStrip
+class FFmpegSession(
+  private val logSink: ((String) -> Unit)?,
+  private val statisticsSink: ((
+    timeMs: Double,
+    sizeBytes: Double,
+    bitrateKbits: Double,
+    speed: Double,
+    videoFrameNumber: Double,
+    fps: Double,
+    quality: Double,
+  ) -> Unit)?,
+) {
+  private val buffer = StringBuilder()
+
+  val output: String
+    get() = synchronized(buffer) { buffer.toString() }
+
+  // FFmpeg logs from several of its own threads at once, so the buffer needs
+  // the lock even though each session belongs to a single execution.
+  @Keep
+  @DoNotStrip
+  fun onLog(message: String) {
+    synchronized(buffer) { buffer.append(message) }
+    logSink?.invoke(message)
+  }
+
+  @Keep
+  @DoNotStrip
+  fun onStatistics(
+    timeMs: Double,
+    sizeBytes: Double,
+    bitrateKbits: Double,
+    speed: Double,
+    videoFrameNumber: Double,
+    fps: Double,
+    quality: Double,
+  ) {
+    statisticsSink?.invoke(timeMs, sizeBytes, bitrateKbits, speed, videoFrameNumber, fps, quality)
+  }
+}
+
 /**
  * Thin wrapper over FFmpeg 9's own command-line tools, compiled to run inside
  * the app process.
@@ -18,9 +67,28 @@ import java.io.File
 object FFmpegNative {
   init {
     configureFontconfig()
-    System.loadLibrary("munimffmpeg9")
+    System.loadLibrary("munimffmpeg")
   }
 
+  /** 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,
+    session: FFmpegSession,
+  ): Int
+
+  external fun nativeExecuteProbe(
+    arguments: Array<String>,
+    outputPath: String,
+    session: FFmpegSession,
+  ): Int
+
+  external fun nativeCancel()
+
   /**
    * libass discovers fonts through fontconfig, and Android has no fonts.conf,
    * so one pointing at the system font directories is written to the app's
@@ -53,70 +121,4 @@ object FFmpegNative {
       Os.setenv("FONTCONFIG_FILE", configuration.absolutePath, true)
     }
   }
-
-  /** 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)
-    )
-  }
 }

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

@@ -53,37 +53,21 @@ class HybridMunimFfmpeg : HybridMunimFfmpegSpec() {
     onSessionCreated?.invoke(sessionId)
 
     return Promise.async {
-      val output = StringBuilder()
       val startedAt = System.currentTimeMillis()
       // ffmpeg prints reports such as -encoders and -protocols to stdout rather
       // than through its logger, so it is captured to a file and appended.
       val stdout = File.createTempFile("munim-ffmpeg", ".txt")
 
-      val returnCode = FFmpegNative.withCallbacks(
-        onLog = { message ->
-          output.append(message)
-          onLog?.invoke(message)
-        },
-        onStatistics = { statistics ->
-          onStatistics?.invoke(
-            statistics.timeMs,
-            statistics.sizeBytes,
-            statistics.bitrateKbits,
-            statistics.speed,
-            statistics.videoFrameNumber,
-            statistics.fps,
-            statistics.quality,
-          )
-        },
-      ) {
-        FFmpegNative.nativeExecute(arguments_, stdout.absolutePath)
-      }
+      val session = FFmpegSession(
+        logSink = { message -> onLog?.invoke(message) },
+        statisticsSink = onStatistics,
+      )
+      val returnCode = FFmpegNative.nativeExecute(arguments_, stdout.absolutePath, session)
 
       val printed = runCatching { stdout.readText() }.getOrDefault("")
       stdout.delete()
-      output.append(printed)
 
-      result(sessionId, returnCode, output.toString(), System.currentTimeMillis() - startedAt)
+      result(sessionId, returnCode, session.output + printed, System.currentTimeMillis() - startedAt)
     }
   }
 
@@ -138,19 +122,15 @@ class HybridMunimFfmpeg : HybridMunimFfmpegSpec() {
   ): Pair<Int, String> {
     val destination = File.createTempFile("munim-ffprobe", ".txt")
     try {
-      val logs = StringBuilder()
-      val returnCode = FFmpegNative.withCallbacks(
-        onLog = { message ->
-          logs.append(message)
-          onLog?.invoke(message)
-        },
-        onStatistics = null,
-      ) {
-        FFmpegNative.nativeExecuteProbe(arguments, destination.absolutePath)
-      }
+      val session = FFmpegSession(
+        logSink = { message -> onLog?.invoke(message) },
+        statisticsSink = null,
+      )
+      val returnCode =
+        FFmpegNative.nativeExecuteProbe(arguments, destination.absolutePath, session)
 
       val report = destination.readText()
-      return returnCode to report.ifEmpty { logs.toString() }
+      return returnCode to report.ifEmpty { session.output }
     } finally {
       destination.delete()
     }

package/ios/HybridMunimFfmpeg.swift

@@ -1,21 +1,39 @@
 import Foundation
 import NitroModules
 
-/// Callbacks for the execution currently holding the core's lock. The core
-/// serialises executions, so a single slot is enough.
-private final class ActiveSession {
-  var onLog: ((String) -> Void)?
-  var onStatistics: ((Double, Double, Double, Double, Double, Double, Double) -> Void)?
-  var output = ""
-
-  func reset() {
-    onLog = nil
-    onStatistics = nil
-    output = ""
+/// Per-run callback target, handed to the core as the context pointer. The
+/// core only routes callbacks to whichever session actually holds its
+/// execution lock, so concurrently submitted sessions never see each other's
+/// logs.
+private final class Session {
+  let onLog: ((String) -> Void)?
+  let onStatistics: ((Double, Double, Double, Double, Double, Double, Double) -> Void)?
+  private var buffer = ""
+  // FFmpeg logs from several of its own threads at once, so the buffer needs
+  // the lock even though each session belongs to a single execution.
+  private let lock = NSLock()
+
+  init(
+    onLog: ((String) -> Void)?,
+    onStatistics: ((Double, Double, Double, Double, Double, Double, Double) -> Void)? = nil
+  ) {
+    self.onLog = onLog
+    self.onStatistics = onStatistics
+  }
+
+  func append(_ text: String) {
+    lock.lock()
+    buffer += text
+    lock.unlock()
+  }
+
+  var output: String {
+    lock.lock()
+    defer { lock.unlock() }
+    return buffer
   }
 }
 
-private let active = ActiveSession()
 // Concurrent on purpose: the C core serialises executions behind its own lock,
 // and a request that is waiting there can still be cancelled. A serial queue
 // would hold the second call outside the core, where cancelAll() cannot see it.
@@ -25,16 +43,17 @@ private let executionQueue = DispatchQueue(
   attributes: .concurrent
 )
 
-private func installCallbacks() {
-  munim_ffmpeg_set_callbacks({ _, message in
-    guard let message else { return }
-    let text = String(cString: message)
-    active.output += text
-    active.onLog?(text)
-  }, { _, timeMs, sizeBytes, bitrate, speed, frame, fps, quality in
-    active.onStatistics?(timeMs, sizeBytes, bitrate, speed, frame, fps, quality)
-  }, nil)
-}
+private let installCallbacks: Void = munim_ffmpeg_set_callbacks({ context, message in
+  guard let context, let message else { return }
+  let session = Unmanaged<Session>.fromOpaque(context).takeUnretainedValue()
+  let text = String(cString: message)
+  session.append(text)
+  session.onLog?(text)
+}, { context, timeMs, sizeBytes, bitrate, speed, frame, fps, quality in
+  guard let context else { return }
+  let session = Unmanaged<Session>.fromOpaque(context).takeUnretainedValue()
+  session.onStatistics?(timeMs, sizeBytes, bitrate, speed, frame, fps, quality)
+}, nil)
 
 final class HybridMunimFfmpeg: HybridMunimFfmpegSpec {
   private var sessionCounter: Double = 0
@@ -88,26 +107,28 @@ final class HybridMunimFfmpeg: HybridMunimFfmpegSpec {
       // its logger, so it is captured to a file and appended to the output.
       let printedPath = Self.temporaryFile()
 
-      installCallbacks()
-      active.reset()
-      active.onLog = onLog
-      active.onStatistics = onStatistics
+      _ = installCallbacks
+      let session = Session(onLog: onLog, onStatistics: onStatistics)
 
-      let returnCode = withArrayOfCStrings(arguments_) { argv in
-        munim_ffmpeg_execute(Int32(arguments_.count), argv, printedPath)
+      let returnCode = withExtendedLifetime(session) {
+        withArrayOfCStrings(arguments_) { argv in
+          munim_ffmpeg_execute_ctx(
+            Int32(arguments_.count),
+            argv,
+            printedPath,
+            Unmanaged.passUnretained(session).toOpaque()
+          )
+        }
       }
 
       let printed = (try? String(contentsOfFile: printedPath, encoding: .utf8)) ?? ""
       try? FileManager.default.removeItem(atPath: printedPath)
 
-      let output = active.output + printed
-      active.reset()
-
       promise.resolve(
         withResult: self.result(
           sessionId: sessionId,
           returnCode: returnCode,
-          output: output,
+          output: session.output + printed,
           startedAt: startedAt
         )
       )
@@ -178,21 +199,24 @@ final class HybridMunimFfmpeg: HybridMunimFfmpegSpec {
   ) -> (Int32, String) {
     let destination = temporaryFile()
 
-    installCallbacks()
-    active.reset()
-    active.onLog = onLog
+    _ = installCallbacks
+    let session = Session(onLog: onLog)
 
-    let returnCode = withArrayOfCStrings(arguments) { argv in
-      munim_ffmpeg_probe(Int32(arguments.count), argv, destination)
+    let returnCode = withExtendedLifetime(session) {
+      withArrayOfCStrings(arguments) { argv in
+        munim_ffmpeg_probe_ctx(
+          Int32(arguments.count),
+          argv,
+          destination,
+          Unmanaged.passUnretained(session).toOpaque()
+        )
+      }
     }
 
     let report = (try? String(contentsOfFile: destination, encoding: .utf8)) ?? ""
     try? FileManager.default.removeItem(atPath: destination)
 
-    let logs = active.output
-    active.reset()
-
-    return (returnCode, report.isEmpty ? logs : report)
+    return (returnCode, report.isEmpty ? session.output : report)
   }
 
   func cancel(sessionId: Double?) throws {

package/ios/munim_ffmpeg_core.h

@@ -21,7 +21,12 @@ typedef void (*munim_statistics_callback)(void *context, double time_ms,
 /** Version string of the linked FFmpeg, e.g. "9.0.1". */
 const char *munim_ffmpeg_version(void);
 
-/** Callbacks apply to whichever execution is currently running. */
+/**
+ * Installs the callback functions. `context` is the default value handed to
+ * them; an execution started through one of the `_ctx` variants overrides it
+ * for exactly as long as that execution holds the core's lock, which is how
+ * callers waiting concurrently keep their callbacks apart.
+ */
 void munim_ffmpeg_set_callbacks(munim_log_callback on_log,
                                 munim_statistics_callback on_statistics,
                                 void *context);
@@ -38,10 +43,18 @@ void munim_ffmpeg_set_callbacks(munim_log_callback on_log,
 int munim_ffmpeg_execute(int argc, const char *const *argv,
                          const char *stdout_path);
 
+/** Like munim_ffmpeg_execute, with a per-run callback context. */
+int munim_ffmpeg_execute_ctx(int argc, const char *const *argv,
+                             const char *stdout_path, void *session);
+
 /** Runs `ffprobe`, writing its report to `output_path` via `-o`. */
 int munim_ffmpeg_probe(int argc, const char *const *argv,
                        const char *output_path);
 
+/** Like munim_ffmpeg_probe, with a per-run callback context. */
+int munim_ffmpeg_probe_ctx(int argc, const char *const *argv,
+                           const char *output_path, void *session);
+
 /**
  * Requests cancellation of the running execution, and of any execution already
  * queued behind it.

package/lib/index.js

@@ -39,9 +39,9 @@ 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.
+// The bundled FFmpeg builds differ per platform: Android ships the MediaCodec
+// hardware encoders, iOS ships VideoToolbox. 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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "munim-ffmpeg",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Fast FFmpeg and FFprobe for Expo and React Native, powered by Nitro Modules",
   "main": "lib/index",
   "module": "lib/index",

package/scripts/binaries.json

@@ -1,5 +1,5 @@
 {
   "archive": "munim-ffmpeg-binaries.tar.gz",
-  "sha256": "05bb0a21348ae3958ca8b06fe6e31bfe2048277f6c6a4720271ce53a8973b653",
+  "sha256": "992527af6fd69672cd863501371a835cad6983c45be5525b45a8462848fe7ecc",
   "ffmpeg": "9.0.1"
 }

package/scripts/fetch-binaries.mjs

@@ -2,8 +2,8 @@
 /*
  * Downloads the prebuilt FFmpeg binaries for this version of munim-ffmpeg.
  *
- * They are not published to npm: the bundle is ~200 MB of static libraries and
- * shared objects, which does not belong in a registry tarball. It ships as a
+ * They are not published to npm: the bundle is well over 100 MB of static
+ * libraries and shared objects, which does not belong in a registry tarball. It ships as a
  * GitHub release asset instead, pinned by the checksum in scripts/binaries.json
  * so a build cannot silently pick up different bytes.
  *
@@ -27,7 +27,7 @@ const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
 const REPOSITORY = 'munimtechnologies/munim-ffmpeg'
 const MARKERS = [
   'ios/MunimFFmpeg.xcframework',
-  'android/src/main/jniLibs/arm64-v8a/libmunimffmpeg9.so',
+  'android/src/main/jniLibs/arm64-v8a/libmunimffmpeg.so',
 ]
 
 async function exists(target) {
@@ -90,6 +90,14 @@ async function main() {
     )
   }
 
+  // A previous version may have left different files behind (older releases
+  // shipped several .so files per ABI), so the targets start empty.
+  for (const target of [
+    'ios/MunimFFmpeg.xcframework',
+    'android/src/main/jniLibs',
+  ]) {
+    await rm(path.join(root, target), { force: true, recursive: true })
+  }
   await run('tar', ['xzf', archive, '-C', root])
   await rm(cache, { force: true, recursive: true })
 

package/src/index.ts

@@ -84,9 +84,9 @@ 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.
+// The bundled FFmpeg builds differ per platform: Android ships the MediaCodec
+// hardware encoders, iOS ships VideoToolbox. 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[]> {