munim-ffmpeg 0.1.1 → 0.3.0

package/ios/munim_ffmpeg_core.h

@@ -0,0 +1,58 @@
+/*
+ * Platform-neutral core for running FFmpeg 9's own command-line tools inside an
+ * app process. The Android JNI bridge and the iOS Swift layer both sit on top
+ * of this.
+ */
+#ifndef MUNIM_FFMPEG_CORE_H
+#define MUNIM_FFMPEG_CORE_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef void (*munim_log_callback)(void *context, const char *message);
+
+typedef void (*munim_statistics_callback)(void *context, double time_ms,
+                                          double size_bytes,
+                                          double bitrate_kbits, double speed,
+                                          double video_frame_number, double fps,
+                                          double quality);
+
+/** 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. */
+void munim_ffmpeg_set_callbacks(munim_log_callback on_log,
+                                munim_statistics_callback on_statistics,
+                                void *context);
+
+/**
+ * Runs `ffmpeg` with the given arguments; `argv[0]` is supplied internally.
+ *
+ * `stdout_path` receives anything the tool prints rather than logs, such as the
+ * `-encoders` and `-protocols` reports. Pass NULL to discard it.
+ *
+ * fftools keeps its parsed command in file-scope globals, so calls are
+ * serialised: a second execution waits for the first to finish.
+ */
+int munim_ffmpeg_execute(int argc, const char *const *argv,
+                         const char *stdout_path);
+
+/** Runs `ffprobe`, writing its report to `output_path` via `-o`. */
+int munim_ffmpeg_probe(int argc, const char *const *argv,
+                       const char *output_path);
+
+/**
+ * Requests cancellation of the running execution, and of any execution already
+ * queued behind it.
+ */
+void munim_ffmpeg_cancel(void);
+
+/** Return code reported when a run was cancelled. */
+#define MUNIM_FFMPEG_CANCELLED 255
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* MUNIM_FFMPEG_CORE_H */

package/lib/index.d.ts

@@ -1,10 +1,33 @@
 import type { FFmpegLogCallback, FFmpegSessionResult, FFmpegSessionCreatedCallback, FFmpegStatisticsCallback, MunimFfmpeg as MunimFfmpegSpec } from './specs/MunimFfmpeg.nitro';
 declare const MunimFfmpeg: MunimFfmpegSpec;
 export type { FFmpegLogCallback, FFmpegSessionResult, FFmpegSessionCreatedCallback, FFmpegStatisticsCallback, MunimFfmpegSpec, };
+/**
+ * Converts a `file://` URI into the plain path FFmpeg expects.
+ *
+ * `expo-file-system` and `react-native-fs` hand back percent-encoded URIs, but
+ * FFmpeg's file protocol treats what follows `file://` literally: a path with a
+ * space silently becomes a file named `my%20clip.mp4`. Anything that is not a
+ * `file://` URI is returned untouched, so pipes, `content://`, and remote URLs
+ * still work.
+ */
+export declare function normalizePath(value: string): string;
 export declare function execute(arguments_: string[], onLog?: FFmpegLogCallback, onStatistics?: FFmpegStatisticsCallback, onSessionCreated?: FFmpegSessionCreatedCallback): Promise<FFmpegSessionResult>;
 export declare function probe(arguments_: string[], onLog?: FFmpegLogCallback, onSessionCreated?: FFmpegSessionCreatedCallback): Promise<FFmpegSessionResult>;
 export declare function getMediaInformation(path: string): Promise<unknown>;
 export declare function cancel(sessionId?: number): void;
 export declare function cancelAll(): void;
 export declare function getFFmpegVersion(): string;
+/** Encoder names the bundled FFmpeg build can write, e.g. `libx264`. */
+export declare function listEncoders(): Promise<string[]>;
+/** Decoder names the bundled FFmpeg build can read, e.g. `h264`. */
+export declare function listDecoders(): Promise<string[]>;
+/**
+ * Returns the first available encoder from `candidates`, so one command can
+ * run on both platforms:
+ *
+ * ```ts
+ * const encoder = await pickEncoder(['libx264', 'h264_videotoolbox'])
+ * ```
+ */
+export declare function pickEncoder(candidates: string[]): Promise<string | undefined>;
 export default MunimFfmpeg;

package/lib/index.js

@@ -1,13 +1,34 @@
 import { NitroModules } from 'react-native-nitro-modules';
 const MunimFfmpeg = NitroModules.createHybridObject('MunimFfmpeg');
+const FILE_URI_SCHEME = /^file:\/\//;
+/**
+ * Converts a `file://` URI into the plain path FFmpeg expects.
+ *
+ * `expo-file-system` and `react-native-fs` hand back percent-encoded URIs, but
+ * FFmpeg's file protocol treats what follows `file://` literally: a path with a
+ * space silently becomes a file named `my%20clip.mp4`. Anything that is not a
+ * `file://` URI is returned untouched, so pipes, `content://`, and remote URLs
+ * still work.
+ */
+export function normalizePath(value) {
+    if (!FILE_URI_SCHEME.test(value))
+        return value;
+    const path = value.replace(FILE_URI_SCHEME, '');
+    try {
+        return decodeURIComponent(path);
+    }
+    catch {
+        return path;
+    }
+}
 export function execute(arguments_, onLog, onStatistics, onSessionCreated) {
-    return MunimFfmpeg.execute(arguments_, onLog, onStatistics, onSessionCreated);
+    return MunimFfmpeg.execute(arguments_.map(normalizePath), onLog, onStatistics, onSessionCreated);
 }
 export function probe(arguments_, onLog, onSessionCreated) {
-    return MunimFfmpeg.probe(arguments_, onLog, onSessionCreated);
+    return MunimFfmpeg.probe(arguments_.map(normalizePath), onLog, onSessionCreated);
 }
 export function getMediaInformation(path) {
-    return MunimFfmpeg.getMediaInformation(path).then((value) => JSON.parse(value));
+    return MunimFfmpeg.getMediaInformation(normalizePath(path)).then((value) => JSON.parse(value));
 }
 export function cancel(sessionId) {
     MunimFfmpeg.cancel(sessionId);
@@ -18,4 +39,53 @@ export function cancelAll() {
 export function getFFmpegVersion() {
     return MunimFfmpeg.ffmpegVersion;
 }
+// The bundled FFmpeg builds differ per platform: Android ships libx264/libx265,
+// iOS ships the VideoToolbox hardware encoders instead. Asking the binary what
+// it supports is more reliable than hard-coding a per-platform table.
+const codecCache = new Map();
+function listCodecs(flag) {
+    const cached = codecCache.get(flag);
+    if (cached)
+        return cached;
+    const request = execute(['-hide_banner', flag])
+        .then((result) => {
+        if (!result.success) {
+            throw new Error(result.failStackTrace ?? result.output);
+        }
+        // Each entry is printed as `<capability flags> <name> <description>`
+        // below a line of dashes.
+        const body = result.output.split(/^\s*-+\s*$/m).pop() ?? '';
+        return body
+            .split('\n')
+            .map((line) => line.trim().split(/\s+/))
+            .filter((columns) => columns.length >= 2 && /^[A-Z.]{6}$/.test(columns[0]))
+            .map((columns) => columns[1]);
+    })
+        .catch((error) => {
+        codecCache.delete(flag);
+        throw error;
+    });
+    codecCache.set(flag, request);
+    return request;
+}
+/** Encoder names the bundled FFmpeg build can write, e.g. `libx264`. */
+export function listEncoders() {
+    return listCodecs('-encoders');
+}
+/** Decoder names the bundled FFmpeg build can read, e.g. `h264`. */
+export function listDecoders() {
+    return listCodecs('-decoders');
+}
+/**
+ * Returns the first available encoder from `candidates`, so one command can
+ * run on both platforms:
+ *
+ * ```ts
+ * const encoder = await pickEncoder(['libx264', 'h264_videotoolbox'])
+ * ```
+ */
+export async function pickEncoder(candidates) {
+    const encoders = new Set(await listEncoders());
+    return candidates.find((candidate) => encoders.has(candidate));
+}
 export default MunimFfmpeg;

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "munim-ffmpeg",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Fast FFmpeg and FFprobe for Expo and React Native, powered by Nitro Modules",
   "main": "lib/index",
   "module": "lib/index",
   "types": "lib/index.d.ts",
+  "bin": {
+    "munim-ffmpeg-fetch-binaries": "scripts/fetch-binaries.mjs"
+  },
   "react-native": "src/index",
   "source": "src/index",
   "files": [
@@ -16,30 +19,41 @@
     "android/gradle.properties",
     "android/fix-prefab.gradle",
     "android/CMakeLists.txt",
-    "android/src",
+    "android/src/main/java",
     "cpp",
     "ios/**/*.h",
     "ios/**/*.m",
     "ios/**/*.mm",
     "ios/**/*.cpp",
     "ios/**/*.swift",
-    "scripts",
     "app.plugin.js",
     "nitro.json",
     "*.podspec",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "android/src/main/cpp",
+    "android/src/main/AndroidManifest.xml",
+    "scripts/fetch-binaries.mjs",
+    "scripts/binaries.json"
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "clean": "rm -rf android/build node_modules/**/android/build lib",
-    "lint": "eslint \"**/*.{js,ts,tsx}\" --fix",
-    "lint-ci": "eslint \"**/*.{js,ts,tsx}\" -f @jamesacarr/github-actions --max-warnings 0",
+    "typecheck:example": "tsc --noEmit -p example/tsconfig.json",
+    "clean": "rm -rf lib android/build example/ios example/android",
+    "lint": "eslint .",
+    "codegen": "nitrogen --logLevel=\"debug\"",
+    "specs": "npm run codegen",
     "build": "npm run typecheck && tsc",
     "prepack": "npm run build",
-    "typescript": "tsc",
-    "codegen": "nitrogen --logLevel=\"debug\"",
-    "specs": "npm run codegen"
+    "check": "npm run codegen && npm run typecheck && npm run typecheck:example && npm run build && npm pack --dry-run",
+    "example:start": "npm --workspace example run start",
+    "example:ios": "npm --workspace example run ios",
+    "example:android": "npm --workspace example run android",
+    "release:local": "node scripts/release-local.mjs",
+    "format": "prettier --write \"**/*.{ts,tsx,js,cjs,mjs,json,md}\"",
+    "postinstall": "node scripts/fetch-binaries.mjs",
+    "binaries:build": "scripts/ffmpeg/fetch-source.sh && scripts/ffmpeg/build-all.sh",
+    "binaries:package": "scripts/ffmpeg/package.sh"
   },
   "keywords": [
     "react-native",
@@ -61,6 +75,9 @@
     "transcoding",
     "munim-technologies"
   ],
+  "workspaces": [
+    "example"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/munimtechnologies/munim-ffmpeg.git"
@@ -83,49 +100,30 @@
     ]
   },
   "devDependencies": {
-    "@react-native/eslint-config": "0.85.3",
+    "@eslint/eslintrc": "^3.3.6",
+    "@eslint/js": "^9.39.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
     "@types/react": "^19.2.15",
+    "conventional-changelog-conventionalcommits": "^9.3.1",
     "eslint": "^9.39.4",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.5",
+    "globals": "^17.11.0",
     "nitrogen": "0.36.5",
     "prettier": "^3.8.3",
     "react": "19.2.3",
     "react-native": "0.86.2",
     "react-native-nitro-modules": "^0.36.5",
-    "typescript": "^6.0.3"
+    "semantic-release": "^25.0.9",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.46.0"
   },
   "peerDependencies": {
     "react": "*",
     "react-native": "*",
     "react-native-nitro-modules": ">=0.36.5 <1"
   },
-  "eslintConfig": {
-    "root": true,
-    "extends": [
-      "@react-native",
-      "prettier"
-    ],
-    "plugins": [
-      "prettier"
-    ],
-    "rules": {
-      "prettier/prettier": [
-        "warn",
-        {
-          "quoteProps": "consistent",
-          "singleQuote": true,
-          "tabWidth": 2,
-          "trailingComma": "es5",
-          "useTabs": false
-        }
-      ]
-    }
-  },
-  "eslintIgnore": [
-    "node_modules/",
-    "lib/"
-  ],
   "prettier": {
     "quoteProps": "consistent",
     "singleQuote": true,

package/scripts/binaries.json

@@ -0,0 +1,5 @@
+{
+  "archive": "munim-ffmpeg-binaries.tar.gz",
+  "sha256": "5d3a286633c584ffb2ef9dec091695f5ba8f8db88187058df7143ef258e15beb",
+  "ffmpeg": "9.0.1"
+}

package/scripts/fetch-binaries.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+/*
+ * 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
+ * GitHub release asset instead, pinned by the checksum in scripts/binaries.json
+ * so a build cannot silently pick up different bytes.
+ *
+ * Runs from postinstall, and can be re-run by hand:
+ *   npx munim-ffmpeg-fetch-binaries
+ */
+import { createHash } from 'node:crypto'
+import { createWriteStream } from 'node:fs'
+import { mkdir, readFile, rm, stat } from 'node:fs/promises'
+import { createRequire } from 'node:module'
+import path from 'node:path'
+import { pipeline } from 'node:stream/promises'
+import { fileURLToPath } from 'node:url'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+
+const run = promisify(execFile)
+const require = createRequire(import.meta.url)
+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',
+]
+
+async function exists(target) {
+  try {
+    await stat(target)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function alreadyInstalled() {
+  for (const marker of MARKERS) {
+    if (!(await exists(path.join(root, marker)))) return false
+  }
+  return true
+}
+
+async function download(url, destination) {
+  const response = await fetch(url, { redirect: 'follow' })
+  if (!response.ok) {
+    throw new Error(`${response.status} ${response.statusText} for ${url}`)
+  }
+  await pipeline(response.body, createWriteStream(destination))
+}
+
+async function checksum(file) {
+  const hash = createHash('sha256')
+  hash.update(await readFile(file))
+  return hash.digest('hex')
+}
+
+async function main() {
+  const manifest = require(path.join(root, 'scripts', 'binaries.json'))
+  const { version } = require(path.join(root, 'package.json'))
+
+  if (await alreadyInstalled()) {
+    console.log(
+      `munim-ffmpeg: FFmpeg ${manifest.ffmpeg} binaries already present`
+    )
+    return
+  }
+
+  const url =
+    process.env.MUNIM_FFMPEG_BINARIES_URL ??
+    `https://github.com/${REPOSITORY}/releases/download/v${version}/${manifest.archive}`
+
+  const cache = path.join(root, '.binaries-cache')
+  await mkdir(cache, { recursive: true })
+  const archive = path.join(cache, manifest.archive)
+
+  console.log(`munim-ffmpeg: downloading FFmpeg ${manifest.ffmpeg} binaries…`)
+  await download(url, archive)
+
+  const actual = await checksum(archive)
+  if (actual !== manifest.sha256) {
+    await rm(cache, { force: true, recursive: true })
+    throw new Error(
+      `checksum mismatch for ${manifest.archive}\n  expected ${manifest.sha256}\n  received ${actual}`
+    )
+  }
+
+  await run('tar', ['xzf', archive, '-C', root])
+  await rm(cache, { force: true, recursive: true })
+
+  if (!(await alreadyInstalled())) {
+    throw new Error('the archive did not contain the expected binaries')
+  }
+
+  console.log(`munim-ffmpeg: FFmpeg ${manifest.ffmpeg} binaries installed`)
+}
+
+main().catch((error) => {
+  console.error(`
+munim-ffmpeg: could not install the native FFmpeg binaries.
+
+  ${error.message}
+
+The package cannot build without them. Options:
+  • re-run:            npx munim-ffmpeg-fetch-binaries
+  • use a mirror:      MUNIM_FFMPEG_BINARIES_URL=<url> npx munim-ffmpeg-fetch-binaries
+  • build them:        see scripts/ffmpeg/README.md
+`)
+  process.exitCode = 1
+})

package/src/index.ts

@@ -18,13 +18,40 @@ export type {
   MunimFfmpegSpec,
 }
 
+const FILE_URI_SCHEME = /^file:\/\//
+
+/**
+ * Converts a `file://` URI into the plain path FFmpeg expects.
+ *
+ * `expo-file-system` and `react-native-fs` hand back percent-encoded URIs, but
+ * FFmpeg's file protocol treats what follows `file://` literally: a path with a
+ * space silently becomes a file named `my%20clip.mp4`. Anything that is not a
+ * `file://` URI is returned untouched, so pipes, `content://`, and remote URLs
+ * still work.
+ */
+export function normalizePath(value: string): string {
+  if (!FILE_URI_SCHEME.test(value)) return value
+
+  const path = value.replace(FILE_URI_SCHEME, '')
+  try {
+    return decodeURIComponent(path)
+  } catch {
+    return path
+  }
+}
+
 export function execute(
   arguments_: string[],
   onLog?: FFmpegLogCallback,
   onStatistics?: FFmpegStatisticsCallback,
   onSessionCreated?: FFmpegSessionCreatedCallback
 ): Promise<FFmpegSessionResult> {
-  return MunimFfmpeg.execute(arguments_, onLog, onStatistics, onSessionCreated)
+  return MunimFfmpeg.execute(
+    arguments_.map(normalizePath),
+    onLog,
+    onStatistics,
+    onSessionCreated
+  )
 }
 
 export function probe(
@@ -32,11 +59,15 @@ export function probe(
   onLog?: FFmpegLogCallback,
   onSessionCreated?: FFmpegSessionCreatedCallback
 ): Promise<FFmpegSessionResult> {
-  return MunimFfmpeg.probe(arguments_, onLog, onSessionCreated)
+  return MunimFfmpeg.probe(
+    arguments_.map(normalizePath),
+    onLog,
+    onSessionCreated
+  )
 }
 
 export function getMediaInformation(path: string): Promise<unknown> {
-  return MunimFfmpeg.getMediaInformation(path).then((value) =>
+  return MunimFfmpeg.getMediaInformation(normalizePath(path)).then((value) =>
     JSON.parse(value)
   )
 }
@@ -53,4 +84,64 @@ export function getFFmpegVersion(): string {
   return MunimFfmpeg.ffmpegVersion
 }
 
+// The bundled FFmpeg builds differ per platform: Android ships libx264/libx265,
+// iOS ships the VideoToolbox hardware encoders instead. Asking the binary what
+// it supports is more reliable than hard-coding a per-platform table.
+const codecCache = new Map<string, Promise<string[]>>()
+
+function listCodecs(flag: '-encoders' | '-decoders'): Promise<string[]> {
+  const cached = codecCache.get(flag)
+  if (cached) return cached
+
+  const request = execute(['-hide_banner', flag])
+    .then((result) => {
+      if (!result.success) {
+        throw new Error(result.failStackTrace ?? result.output)
+      }
+
+      // Each entry is printed as `<capability flags> <name> <description>`
+      // below a line of dashes.
+      const body = result.output.split(/^\s*-+\s*$/m).pop() ?? ''
+      return body
+        .split('\n')
+        .map((line) => line.trim().split(/\s+/))
+        .filter(
+          (columns) => columns.length >= 2 && /^[A-Z.]{6}$/.test(columns[0]!)
+        )
+        .map((columns) => columns[1]!)
+    })
+    .catch((error) => {
+      codecCache.delete(flag)
+      throw error
+    })
+
+  codecCache.set(flag, request)
+  return request
+}
+
+/** Encoder names the bundled FFmpeg build can write, e.g. `libx264`. */
+export function listEncoders(): Promise<string[]> {
+  return listCodecs('-encoders')
+}
+
+/** Decoder names the bundled FFmpeg build can read, e.g. `h264`. */
+export function listDecoders(): Promise<string[]> {
+  return listCodecs('-decoders')
+}
+
+/**
+ * Returns the first available encoder from `candidates`, so one command can
+ * run on both platforms:
+ *
+ * ```ts
+ * const encoder = await pickEncoder(['libx264', 'h264_videotoolbox'])
+ * ```
+ */
+export async function pickEncoder(
+  candidates: string[]
+): Promise<string | undefined> {
+  const encoders = new Set(await listEncoders())
+  return candidates.find((candidate) => encoders.has(candidate))
+}
+
 export default MunimFfmpeg

package/scripts/patch-ffmpegkit-level.rb

@@ -1,45 +0,0 @@
-# frozen_string_literal: true
-
-require 'fileutils'
-require 'tempfile'
-
-pods_root = ENV.fetch('PODS_ROOT')
-build_products = ENV.fetch('PODS_CONFIGURATION_BUILD_DIR')
-source_root = File.join(pods_root, 'ffmpeg-kit-ios-https-alt', 'ffmpegkit.xcframework')
-
-# Patch only the two vendored slices and CocoaPods' selected build product. Nitro's
-# Swift/C++ bridge imports the selected header after this before-compile phase.
-headers = [
-  File.join(source_root, 'ios-arm64', 'ffmpegkit.framework', 'Headers', 'Level.h'),
-  File.join(source_root, 'ios-arm64_x86_64-simulator', 'ffmpegkit.framework', 'Headers', 'Level.h'),
-  File.join(
-    build_products,
-    'XCFrameworkIntermediates',
-    'ffmpeg-kit-ios-https-alt',
-    'ffmpegkit.framework',
-    'Headers',
-    'Level.h'
-  ),
-].select { |path| File.file?(path) }
-
-abort('munim-ffmpeg: could not find the expected FFmpegKit Level.h') if headers.empty?
-
-unsigned_declaration = 'NS_ENUM(NSUInteger, Level)'
-signed_declaration = 'NS_ENUM(NSInteger, Level)'
-
-headers.each do |header|
-  contents = File.binread(header)
-  next if contents.include?(signed_declaration) && !contents.include?(unsigned_declaration)
-
-  occurrences = contents.scan(unsigned_declaration).length
-  abort("munim-ffmpeg: unexpected Level enum declaration in #{header}") unless occurrences == 1
-
-  patched = contents.sub(unsigned_declaration, signed_declaration)
-  Tempfile.create(['Level', '.h'], File.dirname(header)) do |temporary|
-    temporary.binmode
-    temporary.write(patched)
-    temporary.flush
-    FileUtils.chmod(File.stat(header).mode, temporary.path)
-    FileUtils.mv(temporary.path, header)
-  end
-end