munim-ffmpeg 0.6.0 → 0.7.1

package/README.md

@@ -94,7 +94,7 @@
 ### FFmpeg execution
 
 - 🎬 **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
+- 🆕 **FFmpeg 9.0.2:** 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
@@ -126,7 +126,7 @@
 | ---------------------------- | ------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | 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.                                                                                                                    |
+| Parsed media information     | ✅           | ✅         | `getMediaInformation()` returns typed, 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.                                                                                                           |
@@ -183,11 +183,11 @@ await execute([
 
 ## 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.
+Both platforms run **FFmpeg 9.0.2**, 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                           |
+| FFmpeg          | 9.0.2                                                   | 9.0.2                           |
 | Architectures   | arm64 device, arm64 + x86_64 simulator                  | arm64-v8a, armeabi-v7a, x86_64  |
 | Hardware codecs | VideoToolbox, AudioToolbox                              | MediaCodec                      |
 | TLS             | SecureTransport                                         | mbedTLS                         |
@@ -436,10 +436,24 @@ function probe(
 Runs FFprobe for the format, streams, and chapters at a local media path, then parses its JSON response.
 
 ```typescript
-function getMediaInformation(path: string): Promise<unknown>
+function getMediaInformation(path: string): Promise<MediaInformation>
 ```
 
-Applications should validate or narrow the returned JSON shape before using fields from it.
+`MediaInformation` types the `format`, `streams`, and `chapters` sections of FFprobe's report. Every field is optional because FFprobe only prints what the container exposes, and numeric values such as `duration` and `bit_rate` arrive as strings, exactly as FFprobe prints them. Unknown keys are preserved under an index signature.
+
+```typescript
+const info = await getMediaInformation(inputPath)
+const video = info.streams?.find((stream) => stream.codec_type === 'video')
+console.log(video?.width, video?.height, info.format?.duration)
+```
+
+### `getMediaDuration(information)`
+
+Reads the duration in seconds from a `MediaInformation` report, falling back to the first stream that reports one. Returns `undefined` when FFprobe did not report a duration (live inputs, some raw streams).
+
+```typescript
+function getMediaDuration(information: MediaInformation): number | undefined
+```
 
 ### `cancel(sessionId?)`
 
@@ -868,7 +882,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), 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.
+The bundled FFmpeg 9.0.2 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.
 

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

@@ -4,6 +4,9 @@ import androidx.annotation.Keep
 import com.facebook.proguard.annotations.DoNotStrip
 import com.margelo.nitro.core.Promise
 import java.io.File
+import java.util.concurrent.Executors
+import java.util.concurrent.ThreadFactory
+import java.util.concurrent.atomic.AtomicInteger
 import java.util.concurrent.atomic.AtomicLong
 
 @Keep
@@ -16,6 +19,25 @@ class HybridMunimFfmpeg : HybridMunimFfmpegSpec() {
 
   private fun nextSession() = sessions.incrementAndGet().toDouble()
 
+  /**
+   * Runs [block] on a dedicated FFmpeg thread and settles a [Promise] with its
+   * outcome. Nitro's `Promise.async` shares Kotlin's default coroutine pool,
+   * which only has one thread per CPU core: a multi-minute transcode plus a
+   * few queued sessions would park the whole pool and starve every other
+   * coroutine in the app. FFmpeg work therefore gets its own unbounded pool.
+   */
+  private fun <T> runOnFfmpegThread(block: () -> T): Promise<T> {
+    val promise = Promise<T>()
+    executor.execute {
+      try {
+        promise.resolve(block())
+      } catch (error: Throwable) {
+        promise.reject(error)
+      }
+    }
+    return promise
+  }
+
   private fun result(
     sessionId: Double,
     returnCode: Int,
@@ -52,7 +74,7 @@ class HybridMunimFfmpeg : HybridMunimFfmpegSpec() {
     val sessionId = nextSession()
     onSessionCreated?.invoke(sessionId)
 
-    return Promise.async {
+    return runOnFfmpegThread {
       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.
@@ -79,7 +101,7 @@ class HybridMunimFfmpeg : HybridMunimFfmpegSpec() {
     val sessionId = nextSession()
     onSessionCreated?.invoke(sessionId)
 
-    return Promise.async {
+    return runOnFfmpegThread {
       val startedAt = System.currentTimeMillis()
       val (returnCode, report) = runProbe(arguments_, onLog)
       result(sessionId, returnCode, report, System.currentTimeMillis() - startedAt)
@@ -87,7 +109,7 @@ class HybridMunimFfmpeg : HybridMunimFfmpegSpec() {
   }
 
   override fun getMediaInformation(path: String): Promise<String> {
-    return Promise.async {
+    return runOnFfmpegThread {
       val (returnCode, report) = runProbe(
         arrayOf(
           "-v",
@@ -155,4 +177,17 @@ class HybridMunimFfmpeg : HybridMunimFfmpegSpec() {
   override fun cancelAll() {
     FFmpegNative.nativeCancel()
   }
+
+  private companion object {
+    private val threadCounter = AtomicInteger(0)
+
+    /** Unbounded so a queued session never blocks anything but itself. */
+    private val executor = Executors.newCachedThreadPool(
+      ThreadFactory { runnable ->
+        Thread(runnable, "munim-ffmpeg-${threadCounter.incrementAndGet()}").apply {
+          isDaemon = true
+        }
+      },
+    )
+  }
 }

package/lib/index.d.ts

@@ -13,7 +13,89 @@ export type { FFmpegLogCallback, FFmpegSessionResult, FFmpegSessionCreatedCallba
 export declare function normalizePath(value: string): string;
 export declare function execute(arguments_: string[], onLog?: FFmpegLogCallback, onStatistics?: FFmpegStatisticsCallback, onSessionCreated?: FFmpegSessionCreatedCallback): Promise<FFmpegSessionResult>;
 export declare function probe(arguments_: string[], onLog?: FFmpegLogCallback, onSessionCreated?: FFmpegSessionCreatedCallback): Promise<FFmpegSessionResult>;
-export declare function getMediaInformation(path: string): Promise<unknown>;
+/**
+ * Shape of the FFprobe report returned by {@link getMediaInformation}.
+ *
+ * FFprobe's JSON output varies by container and codec, so every field is
+ * optional and unknown keys are preserved. Numeric values such as durations
+ * and bit rates arrive as strings, exactly as FFprobe prints them.
+ */
+export interface MediaStream {
+    index: number;
+    codec_type?: 'video' | 'audio' | 'subtitle' | 'data' | 'attachment' | string;
+    codec_name?: string;
+    codec_long_name?: string;
+    profile?: string;
+    codec_tag_string?: string;
+    codec_tag?: string;
+    width?: number;
+    height?: number;
+    coded_width?: number;
+    coded_height?: number;
+    pix_fmt?: string;
+    color_range?: string;
+    color_space?: string;
+    color_transfer?: string;
+    color_primaries?: string;
+    field_order?: string;
+    level?: number;
+    has_b_frames?: number;
+    sample_aspect_ratio?: string;
+    display_aspect_ratio?: string;
+    r_frame_rate?: string;
+    avg_frame_rate?: string;
+    time_base?: string;
+    start_pts?: number;
+    start_time?: string;
+    duration_ts?: number;
+    duration?: string;
+    bit_rate?: string;
+    max_bit_rate?: string;
+    bits_per_raw_sample?: string;
+    nb_frames?: string;
+    sample_fmt?: string;
+    sample_rate?: string;
+    channels?: number;
+    channel_layout?: string;
+    bits_per_sample?: number;
+    disposition?: Record<string, number>;
+    tags?: Record<string, string>;
+    side_data_list?: Array<Record<string, unknown>>;
+    [key: string]: unknown;
+}
+export interface MediaFormat {
+    filename?: string;
+    nb_streams?: number;
+    nb_programs?: number;
+    format_name?: string;
+    format_long_name?: string;
+    start_time?: string;
+    duration?: string;
+    size?: string;
+    bit_rate?: string;
+    probe_score?: number;
+    tags?: Record<string, string>;
+    [key: string]: unknown;
+}
+export interface MediaChapter {
+    id: number;
+    time_base?: string;
+    start?: number;
+    start_time?: string;
+    end?: number;
+    end_time?: string;
+    tags?: Record<string, string>;
+    [key: string]: unknown;
+}
+export interface MediaInformation {
+    format?: MediaFormat;
+    streams?: MediaStream[];
+    chapters?: MediaChapter[];
+    [key: string]: unknown;
+}
+export declare function getMediaInformation(path: string): Promise<MediaInformation>;
+/** Duration in seconds from a {@link MediaInformation} report, if FFprobe reported one. */
+export declare function getMediaDuration(information: MediaInformation): number | undefined;
 export declare function cancel(sessionId?: number): void;
 export declare function cancelAll(): void;
 export declare function getFFmpegVersion(): string;

package/lib/index.js

@@ -30,6 +30,16 @@ export function probe(arguments_, onLog, onSessionCreated) {
 export function getMediaInformation(path) {
     return MunimFfmpeg.getMediaInformation(normalizePath(path)).then((value) => JSON.parse(value));
 }
+/** Duration in seconds from a {@link MediaInformation} report, if FFprobe reported one. */
+export function getMediaDuration(information) {
+    const raw = information.format?.duration ??
+        information.streams?.find((stream) => stream.duration !== undefined)
+            ?.duration;
+    if (raw === undefined)
+        return undefined;
+    const seconds = Number(raw);
+    return Number.isFinite(seconds) ? seconds : undefined;
+}
 export function cancel(sessionId) {
     MunimFfmpeg.cancel(sessionId);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "munim-ffmpeg",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Fast FFmpeg and FFprobe for Expo and React Native, powered by Nitro Modules",
   "main": "lib/index",
   "module": "lib/index",
@@ -45,7 +45,7 @@
     "specs": "npm run codegen",
     "build": "npm run typecheck && tsc",
     "prepack": "npm run build",
-    "check": "npm run codegen && npm run typecheck && npm run typecheck:example && npm run build && npm pack --dry-run",
+    "check": "npm run codegen && npm run typecheck && npm run build && npm run typecheck:example && npm pack --dry-run",
     "example:start": "npm --workspace example run start",
     "example:ios": "npm --workspace example run ios",
     "example:android": "npm --workspace example run android",
@@ -118,8 +118,8 @@
     "nitrogen": "0.36.5",
     "prettier": "^3.8.3",
     "react": "19.2.3",
-    "react-native": "0.86.2",
-    "react-native-nitro-modules": "^0.36.5",
+    "react-native": "0.86.3",
+    "react-native-nitro-modules": "0.36.5",
     "semantic-release": "^25.0.9",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.46.0"

package/scripts/binaries.json

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

package/src/index.ts

@@ -66,12 +66,109 @@ export function probe(
   )
 }
 
-export function getMediaInformation(path: string): Promise<unknown> {
-  return MunimFfmpeg.getMediaInformation(normalizePath(path)).then((value) =>
-    JSON.parse(value)
+/**
+ * Shape of the FFprobe report returned by {@link getMediaInformation}.
+ *
+ * FFprobe's JSON output varies by container and codec, so every field is
+ * optional and unknown keys are preserved. Numeric values such as durations
+ * and bit rates arrive as strings, exactly as FFprobe prints them.
+ */
+export interface MediaStream {
+  index: number
+  codec_type?: 'video' | 'audio' | 'subtitle' | 'data' | 'attachment' | string
+  codec_name?: string
+  codec_long_name?: string
+  profile?: string
+  codec_tag_string?: string
+  codec_tag?: string
+  width?: number
+  height?: number
+  coded_width?: number
+  coded_height?: number
+  pix_fmt?: string
+  color_range?: string
+  color_space?: string
+  color_transfer?: string
+  color_primaries?: string
+  field_order?: string
+  level?: number
+  has_b_frames?: number
+  sample_aspect_ratio?: string
+  display_aspect_ratio?: string
+  r_frame_rate?: string
+  avg_frame_rate?: string
+  time_base?: string
+  start_pts?: number
+  start_time?: string
+  duration_ts?: number
+  duration?: string
+  bit_rate?: string
+  max_bit_rate?: string
+  bits_per_raw_sample?: string
+  nb_frames?: string
+  sample_fmt?: string
+  sample_rate?: string
+  channels?: number
+  channel_layout?: string
+  bits_per_sample?: number
+  disposition?: Record<string, number>
+  tags?: Record<string, string>
+  side_data_list?: Array<Record<string, unknown>>
+  [key: string]: unknown
+}
+
+export interface MediaFormat {
+  filename?: string
+  nb_streams?: number
+  nb_programs?: number
+  format_name?: string
+  format_long_name?: string
+  start_time?: string
+  duration?: string
+  size?: string
+  bit_rate?: string
+  probe_score?: number
+  tags?: Record<string, string>
+  [key: string]: unknown
+}
+
+export interface MediaChapter {
+  id: number
+  time_base?: string
+  start?: number
+  start_time?: string
+  end?: number
+  end_time?: string
+  tags?: Record<string, string>
+  [key: string]: unknown
+}
+
+export interface MediaInformation {
+  format?: MediaFormat
+  streams?: MediaStream[]
+  chapters?: MediaChapter[]
+  [key: string]: unknown
+}
+
+export function getMediaInformation(path: string): Promise<MediaInformation> {
+  return MunimFfmpeg.getMediaInformation(normalizePath(path)).then(
+    (value) => JSON.parse(value) as MediaInformation
   )
 }
 
+/** Duration in seconds from a {@link MediaInformation} report, if FFprobe reported one. */
+export function getMediaDuration(
+  information: MediaInformation
+): number | undefined {
+  const raw =
+    information.format?.duration ??
+    information.streams?.find((stream) => stream.duration !== undefined)
+      ?.duration
+  if (raw === undefined) return undefined
+  const seconds = Number(raw)
+  return Number.isFinite(seconds) ? seconds : undefined
+}
+
 export function cancel(sessionId?: number): void {
   MunimFfmpeg.cancel(sessionId)
 }