munim-ffmpeg 0.4.1 → 0.5.0

package/NitroMunimFfmpeg.podspec

@@ -30,7 +30,8 @@ Pod::Spec.new do |s|
   s.pod_target_xcconfig = {
     "HEADER_SEARCH_PATHS" => "\"$(PODS_TARGET_SRCROOT)/ios\"",
   }
-  s.frameworks = "AudioToolbox", "VideoToolbox", "CoreMedia", "AVFoundation", "CoreVideo", "Security"
+  # CoreText and CoreGraphics are libass's font provider on iOS.
+  s.frameworks = "AudioToolbox", "VideoToolbox", "CoreMedia", "AVFoundation", "CoreVideo", "Security", "CoreText", "CoreGraphics"
   s.libraries = "bz2", "z", "iconv", "c++"
 
   # Must be public so CocoaPods puts it in the module umbrella, which is how the

package/README.md

@@ -112,7 +112,8 @@
 - 📱 **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
+- 🧪 **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
 - 🎯 **TypeScript:** Complete public callback and result types
 - 🗂️ **16 KB Android pages:** Built with the alignment Google Play requires
 
@@ -129,7 +130,8 @@
 | Cancel one FFmpeg session    | ✅              | ✅              | Pass the positive safe-integer ID received by `execute`'s `onSessionCreated`. The native dependency does not expose FFprobe cancellation.               |
 | Cancel all FFmpeg sessions   | ✅              | ✅              | Use `cancelAll()` or call `cancel()` without an ID.                                                                                                     |
 | Expo Go                      | ❌              | ❌              | A native development build is required.                                                                                                                 |
-| Capability discovery         | ✅              | ✅              | `listEncoders()`, `listDecoders()`, and `pickEncoder()` report what the bundled build supports.                                                          |
+| 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.                                         |
 
@@ -145,9 +147,10 @@ Every release runs the example's 25-check device suite. For 0.4.x:
 | 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 `armeabi-v7a`, `x86_64` | Built and statically checked, not executed |
+| Android emulator, `x86_64` | Same: `libopenh264` passes, MediaCodec does not |
+| Android `armeabi-v7a` | Built and statically checked, not executed |
 
-`x86_64` cannot be run on an Apple Silicon machine: the Android emulator refuses non-native system images, and no x86_64 hardware was available. Both remaining ABIs were verified to be correct ELF binaries with the right architecture, the expected JNI exports, only system libraries unresolved, and the same FFmpeg 9.0.1 and codec set as arm64.
+`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.
 
 ### Android emulators cannot encode video
 
@@ -176,13 +179,13 @@ Both platforms run **FFmpeg 9.0.1**, built from [ffmpeg.org](https://www.ffmpeg.
 | 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), **openh264** (software H.264), plus everything FFmpeg builds natively.
+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.
 
 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`.
+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:
 
@@ -462,6 +465,31 @@ Returns the decoder names the bundled FFmpeg build can read.
 function listDecoders(): Promise<string[]>
 ```
 
+### `listMuxers()` / `listDemuxers()`
+
+Return the container formats the bundled FFmpeg build can write and read, e.g. `mp4`, `matroska`, `webm`. Cached after the first call.
+
+```typescript
+function listMuxers(): Promise<string[]>
+function listDemuxers(): Promise<string[]>
+```
+
+### `listFilters()`
+
+Returns the filter names the bundled FFmpeg build provides, e.g. `subtitles`, `ass`, `drawtext`, `scale`.
+
+```typescript
+function listFilters(): Promise<string[]>
+```
+
+### `listProtocols()`
+
+Returns the protocol names the bundled FFmpeg build provides, e.g. `file`, `https`, `concat`.
+
+```typescript
+function listProtocols(): 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.
@@ -579,6 +607,58 @@ const result = await execute([
 ])
 ```
 
+### 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.
+
+```typescript
+import { execute, normalizePath } from 'munim-ffmpeg'
+
+// ASS/SSA keeps its embedded styling: fonts, colours, outlines,
+// shadows, positioning, karaoke — everything the format supports.
+await execute([
+  '-y',
+  '-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',
+  outputPath,
+])
+```
+
+To ship your own fonts instead of relying on the device's, put them in a directory and add `:fontsdir=/path/to/fonts` to the filter. Note that filter arguments are colon-separated, so a path containing `:` must be escaped — app sandbox paths on both platforms are safe as-is.
+
+### Work with MKV and multiple tracks
+
+Matroska muxing and demuxing is compiled in, along with FFmpeg's standard `-map` stream selection and `-c copy` remuxing:
+
+```typescript
+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',
+  outputMkvPath,
+])
+
+// Extract the second audio track without re-encoding.
+await execute([
+  '-y', '-i', outputMkvPath, '-map', '0:a:1', '-c', 'copy', trackPath,
+])
+```
+
 ### Cancel a long-running command
 
 ```typescript
@@ -631,7 +711,7 @@ 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), and mbedTLS (Apache-2.0) on Android.
+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.
 
 > **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.
 

package/android/build.gradle

@@ -23,11 +23,12 @@ apply plugin: 'org.jetbrains.kotlin.android'
 apply from: '../nitrogen/generated/android/NitroMunimFfmpeg+autolinking.gradle'
 apply from: "./fix-prefab.gradle"
 
-// Deliberately not applying the "com.facebook.react" plugin: Nitro generates
-// its own bindings, and the React plugin also emits React Native's own
-// TurboModule specs into this library. Those then collide with the app's copies
-// and every consumer's release build fails with "Type
-// com.facebook.fbreact.specs.* is defined multiple times".
+// Deliberately not applying the "com.facebook.react" plugin. Nitro generates its
+// own bindings, so React Native's codegen has nothing to do here — and applying
+// the plugin *without* a matching `react { libraryName = ... }` block makes it
+// emit React Native's entire TurboModule spec set into this AAR. Those collide
+// with the app's own copies and release builds fail with
+// "Type com.facebook.fbreact.specs.* is defined multiple times".
 
 def getExtOrDefault(name) {
   return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties["NitroMunimFfmpeg_" + name]

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

@@ -1,7 +1,9 @@
 package com.margelo.nitro.munimffmpeg
 
+import android.system.Os
 import androidx.annotation.Keep
 import com.facebook.proguard.annotations.DoNotStrip
+import java.io.File
 
 /**
  * Thin wrapper over FFmpeg 9's own command-line tools, compiled to run inside
@@ -15,9 +17,43 @@ import com.facebook.proguard.annotations.DoNotStrip
 @DoNotStrip
 object FFmpegNative {
   init {
+    configureFontconfig()
     System.loadLibrary("munimffmpeg9")
   }
 
+  /**
+   * 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
+   * cache and exported before FFmpeg first runs. Without it, `subtitles=` and
+   * `drawtext` render nothing. Apps that manage their own fontconfig setup can
+   * set FONTCONFIG_FILE first; it is never overwritten.
+   */
+  private fun configureFontconfig() {
+    runCatching {
+      if (!System.getenv("FONTCONFIG_FILE").isNullOrEmpty()) return
+
+      val root = File(System.getProperty("java.io.tmpdir"), "munim-ffmpeg-fontconfig")
+      val cache = File(root, "cache")
+      cache.mkdirs()
+
+      val configuration = File(root, "fonts.conf")
+      configuration.writeText(
+        """
+        <?xml version="1.0"?>
+        <!DOCTYPE fontconfig SYSTEM "fonts.dtd">
+        <fontconfig>
+          <dir>/system/fonts</dir>
+          <dir>/system/font</dir>
+          <dir>/product/fonts</dir>
+          <cachedir>${cache.absolutePath}</cachedir>
+        </fontconfig>
+        """.trimIndent()
+      )
+
+      Os.setenv("FONTCONFIG_FILE", configuration.absolutePath, true)
+    }
+  }
+
   /** Return code the tools report when a run was cancelled. */
   const val CANCELLED = 255
 

package/lib/index.d.ts

@@ -21,6 +21,14 @@ export declare function getFFmpegVersion(): string;
 export declare function listEncoders(): Promise<string[]>;
 /** Decoder names the bundled FFmpeg build can read, e.g. `h264`. */
 export declare function listDecoders(): Promise<string[]>;
+/** Container formats the bundled FFmpeg build can write, e.g. `matroska`. */
+export declare function listMuxers(): Promise<string[]>;
+/** Container formats the bundled FFmpeg build can read, e.g. `matroska`. */
+export declare function listDemuxers(): Promise<string[]>;
+/** Filter names the bundled FFmpeg build provides, e.g. `subtitles`. */
+export declare function listFilters(): Promise<string[]>;
+/** Protocol names the bundled FFmpeg build provides, e.g. `https`. */
+export declare function listProtocols(): Promise<string[]>;
 /**
  * Returns the first available encoder from `candidates`, so one command can
  * run on both platforms:

package/lib/index.js

@@ -76,6 +76,80 @@ export function listEncoders() {
 export function listDecoders() {
     return listCodecs('-decoders');
 }
+// Muxers, demuxers and filters print with different flag columns than codecs,
+// and protocols use indented sections instead of a table, so each report gets
+// its own parser. All of them are cached like the codec lists.
+const reportCache = new Map();
+function listReport(flag, parse) {
+    const cached = reportCache.get(flag);
+    if (cached)
+        return cached;
+    const request = execute(['-hide_banner', flag])
+        .then((result) => {
+        if (!result.success) {
+            throw new Error(result.failStackTrace ?? result.output);
+        }
+        return parse(result.output);
+    })
+        .catch((error) => {
+        reportCache.delete(flag);
+        throw error;
+    });
+    reportCache.set(flag, request);
+    return request;
+}
+// `-muxers`/`-demuxers` entries look like ` E  mp4  MP4 (MPEG-4 Part 14)`
+// below a `--` separator line.
+function parseFormats(output) {
+    const body = output.split(/^\s*-+\s*$/m).pop() ?? '';
+    return body
+        .split('\n')
+        .map((line) => line.trim().split(/\s+/))
+        .filter((columns) => columns.length >= 2 && /^[DE.]{1,2}$/.test(columns[0]))
+        .flatMap((columns) => columns[1].split(','));
+}
+// `-filters` entries look like ` TS scale  V->V  Scale the input video.`
+// The flag column has held two or three characters across FFmpeg releases.
+function parseFilters(output) {
+    return output
+        .split('\n')
+        .map((line) => line.trim().split(/\s+/))
+        .filter((columns) => columns.length >= 3 &&
+        /^[TSC.]{2,3}$/.test(columns[0]) &&
+        /->/.test(columns[2]))
+        .map((columns) => columns[1]);
+}
+// `-protocols` prints `Input:` and `Output:` sections of indented names.
+function parseProtocols(output) {
+    const names = new Set();
+    let inSection = false;
+    for (const line of output.split('\n')) {
+        if (/^(Input|Output):/.test(line.trim())) {
+            inSection = true;
+            continue;
+        }
+        const name = line.trim();
+        if (inSection && /^[a-z0-9_]+$/.test(name))
+            names.add(name);
+    }
+    return [...names];
+}
+/** Container formats the bundled FFmpeg build can write, e.g. `matroska`. */
+export function listMuxers() {
+    return listReport('-muxers', parseFormats);
+}
+/** Container formats the bundled FFmpeg build can read, e.g. `matroska`. */
+export function listDemuxers() {
+    return listReport('-demuxers', parseFormats);
+}
+/** Filter names the bundled FFmpeg build provides, e.g. `subtitles`. */
+export function listFilters() {
+    return listReport('-filters', parseFilters);
+}
+/** Protocol names the bundled FFmpeg build provides, e.g. `https`. */
+export function listProtocols() {
+    return listReport('-protocols', parseProtocols);
+}
 /**
  * Returns the first available encoder from `candidates`, so one command can
  * run on both platforms:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "munim-ffmpeg",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Fast FFmpeg and FFprobe for Expo and React Native, powered by Nitro Modules",
   "main": "lib/index",
   "module": "lib/index",
@@ -78,6 +78,11 @@
   "workspaces": [
     "example"
   ],
+  "overrides": {
+    "xcode": {
+      "uuid": "^11.1.1"
+    }
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/munimtechnologies/munim-ffmpeg.git"

package/scripts/binaries.json

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

package/src/index.ts

@@ -129,6 +129,97 @@ export function listDecoders(): Promise<string[]> {
   return listCodecs('-decoders')
 }
 
+// Muxers, demuxers and filters print with different flag columns than codecs,
+// and protocols use indented sections instead of a table, so each report gets
+// its own parser. All of them are cached like the codec lists.
+const reportCache = new Map<string, Promise<string[]>>()
+
+function listReport(
+  flag: string,
+  parse: (output: string) => string[]
+): Promise<string[]> {
+  const cached = reportCache.get(flag)
+  if (cached) return cached
+
+  const request = execute(['-hide_banner', flag])
+    .then((result) => {
+      if (!result.success) {
+        throw new Error(result.failStackTrace ?? result.output)
+      }
+      return parse(result.output)
+    })
+    .catch((error) => {
+      reportCache.delete(flag)
+      throw error
+    })
+
+  reportCache.set(flag, request)
+  return request
+}
+
+// `-muxers`/`-demuxers` entries look like ` E  mp4  MP4 (MPEG-4 Part 14)`
+// below a `--` separator line.
+function parseFormats(output: string): string[] {
+  const body = output.split(/^\s*-+\s*$/m).pop() ?? ''
+  return body
+    .split('\n')
+    .map((line) => line.trim().split(/\s+/))
+    .filter(
+      (columns) => columns.length >= 2 && /^[DE.]{1,2}$/.test(columns[0]!)
+    )
+    .flatMap((columns) => columns[1]!.split(','))
+}
+
+// `-filters` entries look like ` TS scale  V->V  Scale the input video.`
+// The flag column has held two or three characters across FFmpeg releases.
+function parseFilters(output: string): string[] {
+  return output
+    .split('\n')
+    .map((line) => line.trim().split(/\s+/))
+    .filter(
+      (columns) =>
+        columns.length >= 3 &&
+        /^[TSC.]{2,3}$/.test(columns[0]!) &&
+        /->/.test(columns[2]!)
+    )
+    .map((columns) => columns[1]!)
+}
+
+// `-protocols` prints `Input:` and `Output:` sections of indented names.
+function parseProtocols(output: string): string[] {
+  const names = new Set<string>()
+  let inSection = false
+  for (const line of output.split('\n')) {
+    if (/^(Input|Output):/.test(line.trim())) {
+      inSection = true
+      continue
+    }
+    const name = line.trim()
+    if (inSection && /^[a-z0-9_]+$/.test(name)) names.add(name)
+  }
+  return [...names]
+}
+
+/** Container formats the bundled FFmpeg build can write, e.g. `matroska`. */
+export function listMuxers(): Promise<string[]> {
+  return listReport('-muxers', parseFormats)
+}
+
+/** Container formats the bundled FFmpeg build can read, e.g. `matroska`. */
+export function listDemuxers(): Promise<string[]> {
+  return listReport('-demuxers', parseFormats)
+}
+
+/** Filter names the bundled FFmpeg build provides, e.g. `subtitles`. */
+export function listFilters(): Promise<string[]> {
+  return listReport('-filters', parseFilters)
+}
+
+/** Protocol names the bundled FFmpeg build provides, e.g. `https`. */
+export function listProtocols(): Promise<string[]> {
+  return listReport('-protocols', parseProtocols)
+}
+
 /**
  * Returns the first available encoder from `candidates`, so one command can
  * run on both platforms: