Expo FFmpeg Kit

An Expo module wrapper for FFmpeg Kit that uses local AAR and iOS framework files instead of downloading them.

Features

• Execute FFmpeg commands
• Execute FFmpeg with arguments array
• Probe media files for information
• Cancel running sessions
• List all sessions
• Get FFmpeg version
• Set log level
• Full TypeScript support

Installation

Step 1: Install the module

npm install expo-ffmpeg-kit
# or
yarn add expo-ffmpeg-kit

Step 2: Add native libraries

Android

1. Download the FFmpeg Kit AAR file from:

   • Maven Central
   • GitHub Releases

2. Choose your variant (e.g., ffmpeg-kit-audio-6.0-2.aar for audio support only)

3. Place the AAR file in: node_modules/expo-ffmpeg-kit/android/libs/

4. Rename it to: ffmpeg-kit.aar

iOS

1. Download the FFmpeg Kit iOS xcframework bundle from:

   • GitHub Releases
   • Look for: ffmpeg-kit-audio-6.0-2-ios-xcframework.zip (or your preferred variant)

2. Extract and copy ALL .xcframework folders to: node_modules/expo-ffmpeg-kit/ios/Frameworks/

Required frameworks (all must be present):

• ffmpegkit.xcframework
• libavcodec.xcframework
• libavdevice.xcframework
• libavfilter.xcframework
• libavformat.xcframework
• libavutil.xcframework
• libswresample.xcframework
• libswscale.xcframework

3. Add frameworks to your main app target:

Option A: Automatic setup

npx expo-ffmpeg-kit setup-ios

Or using npm script:

npm run --prefix node_modules/expo-ffmpeg-kit setup-ios

Option B: Manual in Xcode

1. Open your iOS project in Xcode
2. Select your app target
3. Go to "Build Phases" → "Link Binary with Libraries"
4. Click "+" and "Add Other..." → "Add Files..."
5. Navigate to node_modules/expo-ffmpeg-kit/ios/Frameworks/
6. Add all 8 .xcframework files
7. Run cd ios && pod install

Step 3: Configure main app (Android only)

Option A: Automatic setup (recommended)

cd your-expo-project
npx expo-ffmpeg-kit setup-android

Option B: Manual setup Add the following to your main app's android/app/build.gradle file:

android {
    // ... existing configuration
}

repositories {
    // ... existing repositories
    flatDir {
        dirs "${rootProject.projectDir}/../node_modules/expo-ffmpeg-kit/android/libs"
    }
}

dependencies {
    // ... existing dependencies
    implementation(name: 'ffmpeg-kit', ext: 'aar')
}

Step 4: Rebuild your app

# For managed workflow
expo prebuild --clean
expo run:ios
expo run:android

# For bare workflow
cd ios && pod install

Usage

import * as ExpoFfmpegKit from 'expo-ffmpeg-kit';

// Execute FFmpeg command
const result = await ExpoFfmpegKit.execute('-i input.mp4 -c:v copy output.mp4');

// Execute with arguments array
const result = await ExpoFfmpegKit.executeWithArguments([
  '-i', 'input.mp4',
  '-c:v', 'copy',
  'output.mp4'
]);

// Probe media file
const probeData = await ExpoFfmpegKit.probe('input.mp4');
const info = JSON.parse(probeData);

// Cancel a session
await ExpoFfmpegKit.cancel(sessionId);

// Cancel all sessions
await ExpoFfmpegKit.cancelAll();

// List all sessions
const sessions = ExpoFfmpegKit.listSessions();

// Get FFmpeg version
const version = ExpoFfmpegKit.getFFmpegVersion();

// Set log level
ExpoFfmpegKit.setLogLevel(ExpoFfmpegKit.LogLevel.INFO);

API Reference

Functions

execute(command: string): Promise<FFmpegSession>

Execute an FFmpeg command string.

executeWithArguments(args: string[]): Promise<FFmpegSession>

Execute FFmpeg with an array of arguments.

probe(path: string): Promise<string>

Probe a media file and return JSON string with file information.

cancel(sessionId: number): Promise<void>

Cancel a specific FFmpeg session.

cancelAll(): Promise<void>

Cancel all running FFmpeg sessions.

listSessions(): FFmpegSession[]

List all FFmpeg sessions.

getFFmpegVersion(): string

Get the FFmpeg version string.

setLogLevel(level: number): void

Set the FFmpeg log level (0-8).

Constants

LogLevel

• QUIET: 0
• PANIC: 1
• FATAL: 2
• ERROR: 3
• WARNING: 4
• INFO: 5
• VERBOSE: 6
• DEBUG: 7
• TRACE: 8

ReturnCode

• SUCCESS: 0
• CANCEL: 255

SessionState

• CREATED: 'CREATED'
• RUNNING: 'RUNNING'
• FAILED: 'FAILED'
• COMPLETED: 'COMPLETED'

FFmpeg Kit Variants

Choose the appropriate variant based on your needs:

• min: Minimal build (~3 MB)
• min-gpl: Minimal build with GPL libraries
• audio: Audio libraries only (~20 MB)
• video: Video libraries (~30 MB)
• full: All libraries (~50 MB)
• full-gpl: All libraries with GPL

Example App

See the example directory for a complete React Native app demonstrating all features.

cd example
npm install
expo run:ios
# or
expo run:android

Troubleshooting

Android

• Ensure the AAR file name matches exactly what's specified in android/build.gradle
• Check that minSdkVersion is at least 21
• If you get build errors, try cleaning: cd android && ./gradlew clean

iOS

CocoaPods/Hermes Engine/Deployment Target Issues If you encounter Hermes engine, pod compatibility, or deployment target errors:

# Automatic fix (recommended)
npx expo-ffmpeg-kit fix-ios-build

# Manual fix
cd ios
rm -rf Pods
rm Podfile.lock
pod cache clean --all

# Ensure iOS deployment target is 15.0 or higher in Podfile:
# platform :ios, '15.0'

pod update hermes-engine --no-repo-update
pod install

Common Deployment Target Errors If you see errors like "required a higher minimum deployment target":

1. Check your ios/Podfile has: platform :ios, '15.0'
2. In Xcode, set deployment target to 15.0+ for both your app target and any pod targets
3. Some dependencies require iOS 15.0+ (including react-native-zip-archive)

iOS Build Issues ('bitset' file not found, module build errors) If you encounter C++ header or module build errors:

1. Try using CocoaPods dependency instead of local frameworks:

   cd node_modules/expo-ffmpeg-kit/ios
   mv ExpoFfmpegKit.podspec ExpoFfmpegKit.podspec.local
   mv ExpoFfmpegKit.podspec.cocoapods ExpoFfmpegKit.podspec
   cd ../../../ios
   pod install

2. Ensure C++ standard is set correctly in your main app's ios/Podfile:

   post_install do |installer|
     installer.pods_project.targets.each do |target|
       target.build_configurations.each do |config|
         config.build_settings['CLANG_CXX_LANGUAGE_STANDARD'] = 'c++20'
         config.build_settings['CLANG_CXX_LIBRARY'] = 'libc++'
       end
     end
   end

Other iOS Issues

• Ensure all required xcframeworks are present in the Frameworks directory
• Check that deployment target is at least iOS 15.0
• If linking fails after adding frameworks, clean and reinstall:

  cd ios
  pod deintegrate
  pod install

License

MIT

Credits

This module wraps FFmpeg Kit by Arthenica.