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

$3

``bash
npm install expo-ffmpeg-kit


or


yarn add expo-ffmpeg-kit
`

$3

#### 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
`bash
npx expo-ffmpeg-kit setup-ios
`
Or using npm script:
`bash
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

$3

Option A: Automatic setup (recommended)
`bash
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:

`gradle
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')
}
`

$3

`bash


For managed workflow

expo prebuild --clean
expo run:ios
expo run:android

For bare workflow

cd ios && pod install
`

Usage

`typescript
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

$3

#### execute(command: string): Promise
Execute an FFmpeg command string.

#### executeWithArguments(args: string[]): Promise
Execute FFmpeg with an array of arguments.

#### probe(path: string): Promise
Probe a media file and return JSON string with file information.

#### cancel(sessionId: number): Promise
Cancel a specific FFmpeg session.

#### cancelAll(): Promise
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).

$3

#### 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.

`bash
cd example
npm install
expo run:ios


or


expo run:android
`

Troubleshooting

$3

- 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

$3

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

`bash


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:
`bash
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:
`ruby
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:
`bash
cd ios
pod deintegrate
pod install
``

License

MIT

Credits

This module wraps FFmpeg Kit by Arthenica.