munim-ffmpeg

Fast FFmpeg and FFprobe for Expo and React Native, powered by Nitro Modules.

iOS

Android

GitHub

npm

Overview

munim-ffmpeg brings asynchronous FFmpeg and FFprobe execution to Expo development builds and bare React Native apps through Nitro Modules. Commands use argument arrays instead of shell strings, with live logs, encoding statistics, media-information JSON, immediate session IDs for targeted cancellation, and typed completion results on iOS and Android.

Installation

Terminal

npx expo install munim-ffmpeg react-native-nitro-modules

For bare React Native without Expo: npm install munim-ffmpeg react-native-nitro-modules

Usage

Transcode and inspect media

import { cancel, execute, getMediaInformation } from 'munim-ffmpeg'

let activeSessionId: number | undefined

const execution = execute(
  ['-i', inputUri, '-c:v', 'mpeg4', '-c:a', 'aac', outputUri],
  (message) => console.log(message),
  (timeMs, sizeBytes, bitrateKbits, speed) => {
    console.log({ timeMs, sizeBytes, bitrateKbits, speed })
  },
  (sessionId) => {
    activeSessionId = sessionId
  }
)

// Call from a cancel button while the command is running.
if (activeSessionId !== undefined) cancel(activeSessionId)

const result = await execution
const mediaInfo = await getMediaInformation(outputUri)

Requirements

Expo development build or bare React Native app with the New Architecture enabled, react-native-nitro-modules 0.36.5+, iOS 15.1+, and Android API 24+. Expo Go cannot load this native package.

Platform notes

iOS

Supports FFmpeg, FFprobe, logs, statistics, media information, session cancellation, and native version reporting on iOS 15.1+. CocoaPods installs the FFmpegKit-compatible HTTPS build.

Android

Supports the same API on Android API 24+ using a maintained FFmpegKit-compatible artifact with 16 KB memory-page support.

API

Methods

execute(arguments, onLog?, onStatistics?, onSessionCreated?)

Starts an asynchronous FFmpeg command. The optional session callback fires immediately; the Promise resolves when the command completes.

Returns: Promise<FFmpegSessionResult>

Parameter	Type	Description
arguments	string[]	FFmpeg options and paths without the ffmpeg executable name.
onLog?	(message: string) => void	Receives native FFmpeg log lines.
onStatistics?	FFmpegStatisticsCallback	Receives live encoding progress values.
onSessionCreated?	(sessionId: number) => void	Receives the ID needed to cancel this session while it runs.

probe(arguments, onLog?, onSessionCreated?)

Starts an asynchronous FFprobe command with optional log and immediate-session callbacks.

Returns: Promise<FFmpegSessionResult>

getMediaInformation(path)

Runs FFprobe with JSON output for the format, streams, and chapters at a local media path, then parses the response.

Returns: Promise<unknown>

cancel(sessionId?)

Cancels one running session when given an ID from onSessionCreated. With no ID, cancels all active sessions.

Returns: void

cancelAll()

Cancels all active native FFmpeg sessions.

Returns: void

getFFmpegVersion()

Returns the FFmpeg version bundled by the native compatibility package.

Returns: string

Types

FFmpegSessionResult

Completion data returned by execute() and probe().

Property	Type	Description
sessionId	number	Native session identifier.
returnCode	number	Native FFmpeg or FFprobe return code.
success	boolean	Whether the command completed successfully.
cancelled	boolean	Whether the session ended through cancellation.
state	string	Final native session state.
durationMs	number	Execution duration in milliseconds.
output	string	Combined command output and logs.
failStackTrace?	string	Native failure details when available.

Features

•FFmpeg execution - Run native FFmpeg commands asynchronously with argument arrays
•FFprobe execution - Inspect containers, streams, chapters, codecs, and metadata
•Media information - Receive parsed FFprobe JSON from a local media path
•Live logs - Stream native FFmpeg and FFprobe output to JavaScript
•Encoding statistics - Track time, output size, bitrate, speed, frame count, FPS, and quality
•Targeted cancellation - Capture a session ID immediately and cancel one running command
•Global cancellation - Stop all active FFmpeg sessions when a screen or workflow closes
•Typed completion results - Read return code, duration, state, output, and failure details
•Nitro Modules - Swift and Kotlin HybridObjects generated from one TypeScript specification
•Expo compatible - Includes autolinking, a config plugin, and a development-build example

For the latest API reference, usage examples, and troubleshooting, visit the GitHub repository and npm package page.