67a2e1ad7c
Improve documentation |
||
---|---|---|
.. | ||
android | ||
ios | ||
src | ||
.editorconfig | ||
.gitattributes | ||
.gitignore | ||
babel.config.js | ||
ffmpeg-kit-react-native.podspec | ||
package.json | ||
README.md |
FFmpegKit for React Native
1. Features
-
Includes both
FFmpeg
andFFprobe
-
Supports
-
Both
Android
andiOS
-
FFmpeg
v4.5-dev
releases -
arm-v7a
,arm-v7a-neon
,arm64-v8a
,x86
andx86_64
architectures on Android -
Android API Level 16
or later -
armv7
,armv7s
,arm64
,arm64-simulator
,i386
,x86_64
,x86_64-mac-catalyst
andarm64-mac-catalyst
architectures on iOS -
iOS SDK 9.3
or later -
Can process Storage Access Framework (SAF) Uris on Android
-
24 external libraries
dav1d
,fontconfig
,freetype
,fribidi
,gmp
,gnutls
,kvazaar
,lame
,libass
,libiconv
,libilbc
,libtheora
,libvorbis
,libvpx
,libwebp
,libxml2
,opencore-amr
,opus
,shine
,snappy
,soxr
,speex
,twolame
,vo-amrwbenc
-
4 external libraries with GPL license
vid.stab
,x264
,x265
,xvidcore
-
zlib
andMediaCodec
Android system libraries -
bzip2
,iconv
,libuuid
,zlib
system libraries andAudioToolbox
,VideoToolbox
,AVFoundation
system frameworks on iOS
-
-
Includes Typescript definitions
-
Licensed under LGPL 3.0, can be customized to support GPL v3.0
2. Installation
yarn add ffmpeg-kit-react-native
2.1 Packages
ffmpeg
includes built-in encoders for some popular formats. However, there are certain external libraries that needs
to be enabled in order to encode specific formats/codecs. For example, to encode an mp3
file you need lame
or
shine
library enabled. You have to install a ffmpeg-kit-react-native
package that has at least one of them inside.
To encode an h264
video, you need to install a package with x264
inside. To encode vp8
or vp9
videos, you need
a ffmpeg-kit-react-native
package with libvpx
inside.
ffmpeg-kit
provides eight packages that include different sets of external libraries. These packages are
named according to the external libraries included in them. Refer to
Packages section of the project README to see the names
of those packages and external libraries included in each of them.
2.1.1 Package Names
The following table shows all package names and their respective API levels, iOS deployment targets defined in
ffmpeg-kit-react-native
.
Package | Main Release | LTS Release | ||||
---|---|---|---|---|---|---|
Name | Android API Level |
iOS Minimum Deployment Target |
Name | Android API Level |
iOS Minimum Deployment Target |
|
min | min | 24 | 12.1 | min-lts | 16 | 9.3 |
min-gpl | min-gpl | 24 | 12.1 | min-gpl-lts | 16 | 9.3 |
https | (*) https | 24 | 12.1 | https-lts | 16 | 9.3 |
https-gpl | https-gpl | 24 | 12.1 | https-gpl-lts | 16 | 9.3 |
audio | audio | 24 | 12.1 | audio-lts | 16 | 9.3 |
video | video | 24 | 12.1 | video-lts | 16 | 9.3 |
full | full | 24 | 12.1 | full-lts | 16 | 9.3 |
full-gpl | full-gpl | 24 | 12.1 | full-gpl-lts | 16 | 9.3 |
(*) - Main https
package is the default package
2.2 Enabling Packages
Installing ffmpeg-kit-react-native
enables the https
package by default. It is possible to enable other
packages using the instructions below.
2.2.1 Enabling a Package on Android
-
Edit
android/build.gradle
file and add the package name inext.ffmpegKitPackage
variable.ext { ffmpegKitPackage = "<package name>" }
2.2.2 Enabling a Package on iOS
-
Edit
ios/Podfile
file and add the package name assubspec
. After that runpod install
again.pod 'ffmpeg-kit-react-native', :subspecs => ['<package name>'], :podspec => '../node_modules/ffmpeg-kit-react-native/ffmpeg-kit-react-native.podspec'
-
Note that if you have
use_native_modules!
in yourPodfile
, specifying asubspec
may cause the following error. You can fix it by definingffmpeg-kit-react-native
dependency beforeuse_native_modules!
in yourPodfile
.[!] There are multiple dependencies with different sources for `ffmpeg-kit-react-native` in `Podfile`: - ffmpeg-kit-react-native (from `../node_modules/ffmpeg-kit-react-native`) - ffmpeg-kit-react-native/video (from `../node_modules/ffmpeg-kit-react-native/ffmpeg-kit-react-native.podspec`)
2.3 Enabling LTS Releases
In order to install the LTS
variant, install the https-lts
package using instructions in 2.2
or append -lts
to
the package name you are using.
2.4 LTS Releases
ffmpeg-kit-react-native
is published in two different variants: Main Release
and LTS Release
. Both releases
share the same source code but is built with different settings (Architectures, API Level, iOS Min SDK, etc.). Refer to
LTS Releases section of the project README to see how they
compare to each other.
3. Using
-
Execute FFmpeg commands.
import { FFmpegKit } from 'ffmpeg-kit-react-native'; FFmpegKit.executeAsync('-i file1.mp4 -c:v mpeg4 file2.mp4', async (session) => { const returnCode = await session.getReturnCode(); if (ReturnCode.isSuccess(returnCode)) { // SUCCESS } else if (ReturnCode.isCancel(returnCode)) { // CANCEL } else { // ERROR } });
-
Each
execute
call creates a new session. Access every detail about your execution from the session created.FFmpegKit.executeAsync('-i file1.mp4 -c:v mpeg4 file2.mp4').then(async (session) => { // Unique session id created for this execution const sessionId = session.getSessionId(); // Command arguments as a single string const command = session.getCommand(); // Command arguments const commandArguments = session.getArguments(); // State of the execution. Shows whether it is still running or completed const state = await session.getState(); // Return code for completed sessions. Will be undefined if session is still running or FFmpegKit fails to run it const returnCode = await session.getReturnCode() const startTime = session.getStartTime(); const endTime = await session.getEndTime(); const duration = await session.getDuration(); // Console output generated for this execution const output = await session.getOutput(); // The stack trace if FFmpegKit fails to run a command const failStackTrace = await session.getFailStackTrace() // The list of logs generated for this execution const logs = await session.getLogs(); // The list of statistics generated for this execution (only available on FFmpegSession) const statistics = await session.getStatistics(); });
-
Execute
FFmpeg
commands by providing session specificexecute
/log
/session
callbacks.FFmpegKit.executeAsync('-i file1.mp4 -c:v mpeg4 file2.mp4', session => { // CALLED WHEN SESSION IS EXECUTED }, log => { // CALLED WHEN SESSION PRINTS LOGS }, statistics => { // CALLED WHEN SESSION GENERATES STATISTICS });
-
Execute
FFprobe
commands.FFprobeKit.executeAsync(ffprobeCommand, session => { // CALLED WHEN SESSION IS EXECUTED });
-
Get media information for a file/url.
FFprobeKit.getMediaInformationAsync('<file path or url>', async (session) => { const information = await session.getMediaInformation(); });
-
Stop ongoing FFmpeg operations.
- Stop all sessions
FFmpegKit.cancel();
- Stop a specific session
FFmpegKit.cancel(sessionId);
- (Android) Convert Storage Access Framework (SAF) Uris into paths that can be read or written by
FFmpegKit
andFFprobeKit
.
-
Reading a file:
FFmpegKitConfig.selectDocumentForRead('*/*').then(uri => { FFmpegKitConfig.getSafParameterForRead(uri).then(safUrl => { FFmpegKit.executeAsync(`-i ${safUrl} -c:v mpeg4 file2.mp4`); }); });
-
Writing to a file:
FFmpegKitConfig.selectDocumentForWrite('video.mp4', 'video/*').then(uri => { FFmpegKitConfig.getSafParameterForWrite(uri).then(safUrl => { FFmpegKit.executeAsync(`-i file1.mp4 -c:v mpeg4 ${safUrl}`); }); });
-
Get previous
FFmpeg
andFFprobe
sessions from the session history.FFmpegKit.listSessions().then(sessionList => { sessionList.forEach(async session => { const sessionId = session.getSessionId(); }); }); FFprobeKit.listSessions().then(sessionList => { sessionList.forEach(async session => { const sessionId = session.getSessionId(); }); });
-
Enable global callbacks.
-
Execute Callback, called when an async execution is ended
FFmpegKitConfig.enableExecuteCallback(session => { const sessionId = session.getSessionId(); });
-
Log Callback, called when a session generates logs
FFmpegKitConfig.enableLogCallback(log => { const message = log.getMessage(); });
-
Statistics Callback, called when a session generates statistics
FFmpegKitConfig.enableStatisticsCallback(statistics => { const size = statistics.getSize(); });
-
Register system fonts and custom font directories.
FFmpegKitConfig.setFontDirectoryList(["/system/fonts", "/System/Library/Fonts", "<folder with fonts>"]);
4. Test Application
You can see how FFmpegKit
is used inside an application by running react-native
test applications developed under
the FFmpegKit Test project.
5. Tips
See Tips wiki page.
6. License
See License wiki page.
7. Patents
See Patents wiki page.