search

tanersener / react-native-ffmpeg

FFmpeg for react-native. Not maintained anymore. Superseded by FFmpegKit.
GNU General Public License v3.0
400 stars 51 forks source link
android ffmpeg ios react-native

readme

React Native FFmpeg GitHub release npm

FFmpeg for React Native

Not maintained anymore, superseded by FFmpegKit. See ReactNativeFFmpeg to FFmpegKit Migration Guide.

1. Features

2. Installation

$ yarn add react-native-ffmpeg

2.1 Android

On React Native < 0.60, manually link the module by running the following command.

$ react-native link react-native-ffmpeg

2.2 iOS

2.2.1 Basic

On React Native >= 0.60,

On React Native < 0.60,

2.3 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 react-native-ffmpeg 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 react-native-ffmpeg package with libvpx inside.

react-native-ffmpeg provides eight packages that include different sets of external libraries. These packages are named according to the external libraries included in them. Below you can see which libraries are enabled in each package.

min min-gpl https https-gpl audio video full full-gpl
external libraries - vid.stab
x264
x265
xvidcore		 gmp
gnutls		 gmp
gnutls
vid.stab
x264
x265
xvidcore		 lame
libilbc
libvorbis
opencore-amr
opus
shine
soxr
speex
twolame
vo-amrwbenc
wavpack		 fontconfig
freetype
fribidi
kvazaar
libaom
libass
libiconv
libtheora
libvpx
libwebp
snappy		 fontconfig
freetype
fribidi
gmp
gnutls
kvazaar
lame
libaom
libass
libiconv
libilbc
libtheora
libvorbis
libvpx
libwebp
libxml2
opencore-amr
opus
shine
snappy
soxr
speex
twolame
vo-amrwbenc
wavpack		 fontconfig
freetype
fribidi
gmp
gnutls
kvazaar
lame
libaom
libass
libiconv
libilbc
libtheora
libvorbis
libvpx
libwebp
libxml2
opencore-amr
opus
shine
snappy
soxr
speex
twolame
vid.stab
vo-amrwbenc
wavpack
x264
x265
xvidcore
android system libraries zlib
MediaCodec
ios system libraries zlib
AudioToolbox
AVFoundation
iconv
VideoToolbox
bzip2

Installation of react-native-ffmpeg using instructions in 2.1 and 2.2 enables the default package, which is based on https package. It is possible to enable other installed packages using the following steps.

2.3.1 Android
2.3.2 iOS
2.3.3 Package Names

The following table shows all package names defined for react-native-ffmpeg.

Package Main Release LTS Release
min min min-lts
min-gpl min-gpl min-gpl-lts
https https https-lts
https-gpl https-gpl https-gpl-lts
audio audio audio-lts
video video video-lts
full full full-lts
full-gpl full-gpl full-gpl-lts

2.4 LTS Release

react-native-ffmpeg is published in two different variants: Main Release and LTS Release. Both releases share the same source code but is built with different settings. Below you can see the differences between the two.

In order to install the LTS variant, install the https-lts package using instructions in 2.3 or append -lts to the package name you are using.

Main Release LTS Release
Android API Level 24 16
Android Camera Access Yes -
Android Architectures arm-v7a-neon
arm64-v8a
x86
x86-64		 arm-v7a
arm-v7a-neon
arm64-v8a
x86
x86-64
Xcode Support 10.1 7.3.1
iOS SDK 11.0 9.3
iOS AVFoundation Yes -
iOS Architectures arm64
x86-64
x86-64-mac-catalyst		 armv7
arm64
i386
x86-64

3. Using

  1. Execute synchronous FFmpeg commands.

    • Use execute() method with a single command
    import { LogLevel, RNFFmpeg } from 'react-native-ffmpeg';

RNFFmpeg.execute('-i file1.mp4 -c:v mpeg4 file2.mp4').then(result => console.log(`FFmpeg process exited with rc=${result}.`));
    • Use executeWithArguments() method with an array of arguments 
    import { LogLevel, RNFFmpeg } from 'react-native-ffmpeg';

RNFFmpeg.executeWithArguments(["-i", "file1.mp4", "-c:v", "mpeg4", "file2.mp4"]).then(result => console.log(`FFmpeg process exited with rc=${result}.`));

  2. Execute asynchronous FFmpeg commands.

    import { LogLevel, RNFFmpeg } from 'react-native-ffmpeg';

RNFFmpeg.executeAsync('-i file1.mp4 -c:v mpeg4 file2.mp4', completedExecution => {
    if (completedExecution.returnCode === 0) {
       console.log("FFmpeg process completed successfully");
    } else {
       console.log(`FFmpeg process failed with rc=${completedExecution.returnCode}.`);
    }
}).then(executionId => console.log(`Async FFmpeg process started with executionId ${executionId}.`));

  3. Execute FFprobe commands.

    • Use execute() method with a single command
    import { LogLevel, RNFFprobe } from 'react-native-ffmpeg';

RNFFprobe.execute('-i file1.mp4').then(result => console.log(`FFprobe process exited with rc=${result}.`));
    • Use executeWithArguments() method with an array of arguments 
    import { LogLevel, RNFFprobe } from 'react-native-ffmpeg';

RNFFprobe.executeWithArguments(["-i", "file1.mp4"]).then(result => console.log(`FFmpeg process exited with rc=${result}.`));

  4. Check execution output. Zero represents successful execution, non-zero values represent failure.

    RNFFmpegConfig.getLastReturnCode().then(returnCode => {
    console.log(`Last return code: ${returnCode}`);
});

RNFFmpegConfig.getLastCommandOutput().then(output => {
    console.log(`Last command output: ${output}`);
});

  5. Stop ongoing FFmpeg operations. Note that these two functions do not wait for termination to complete and return immediately.

    • Stop all executions 
      RNFFmpeg.cancel();
    • Stop a specific execution 
      RNFFmpeg.cancelExecution(executionId);

  6. Get media information for a file.

    • Print all fields 
      RNFFprobe.getMediaInformation('<file path or uri>').then(information => {
console.log('Result: ' + JSON.stringify(information));
});

    • Print selected fields

      RNFFprobe.getMediaInformation('<file path or uri>').then(information => {
if (information.getMediaProperties() !== undefined) {
    if (information.getMediaProperties().filename !== undefined) {
        console.log(`Path: ${information.getMediaProperties().filename}`);
    }
    if (information.getMediaProperties().format_name !== undefined) {
        console.log(`Format: ${information.getMediaProperties().format_name}`);
    }
    if (information.getMediaProperties().bit_rate !== undefined) {
        console.log(`Bitrate: ${information.getMediaProperties().bit_rate}`);
    }
    if (information.getMediaProperties().duration !== undefined) {
        console.log(`Duration: ${information.getMediaProperties().duration}`);
    }
    if (information.getMediaProperties().start_time !== undefined) {
        console.log(`Start time: ${information.getMediaProperties().start_time}`);
    }
    if (information.getMediaProperties().nb_streams !== undefined) {
        console.log(`Number of streams: ${information.getMediaProperties().nb_streams.toString()}`);
    }
    let tags = information.getMediaProperties().tags;
    if (tags !== undefined) {
        Object.keys(tags).forEach((key) => {
            console.log(`Tag: ${key}:${tags[key]}`);
        });
    }

    let streams = information.getStreams();
    if (streams !== undefined) {
        for (let i = 0; i < streams.length; ++i) {
           let stream = streams[i];
           console.log("---");
           if (stream.getAllProperties().index !== undefined) {
               console.log(`Stream index: ${stream.getAllProperties().index.toString()}`);
           }
           if (stream.getAllProperties().codec_type !== undefined) {
               console.log(`Stream type: ${stream.getAllProperties().codec_type}`);
           }
           if (stream.getAllProperties().codec_name !== undefined) {
               console.log(`Stream codec: ${stream.getAllProperties().codec_name}`);
           }
        }
    }
}
});

  7. Enable log callback and redirect all FFmpeg/FFprobe logs to a console/file/widget.

    logCallback = (log) => {
    this.appendLog(`${log.executionId}:${log.message}`);
};
...
RNFFmpegConfig.enableLogCallback(this.logCallback);

  8. Enable statistics callback and follow the progress of an ongoing FFmpeg operation.

    statisticsCallback = (statistics) => {
    console.log(`Statistics; executionId: ${statistics.executionId}, video frame number: ${statistics.videoFrameNumber}, video fps: ${statistics.videoFps}, video quality: ${statistics.videoQuality}, size: ${statistics.size}, time: ${statistics.time}, bitrate: ${statistics.bitrate}, speed: ${statistics.speed}`);
};
...
RNFFmpegConfig.enableStatisticsCallback(this.statisticsCallback);

  9. Poll statistics without implementing statistics callback.

    RNFFmpegConfig.getLastReceivedStatistics().then(statistics => console.log('Stats: ' + JSON.stringify(statistics)));

  10. List ongoing executions.

    RNFFmpeg.listExecutions().then(executionList => {
    executionList.forEach(execution => {
        console.log(`Execution id is ${execution.executionId}`);
        console.log(`Execution start time is ` + new Date(execution.startTime));
        console.log(`Execution command is ${execution.command}`);
    });
});

  11. Set log level.

    RNFFmpegConfig.setLogLevel(LogLevel.AV_LOG_WARNING);

  12. Register your own fonts by specifying a custom fonts directory, so they are available to use in FFmpeg filters. Please note that this function can not work on relative paths, you need to provide full file system path.

    • Without any font name mappings 
      RNFFmpegConfig.setFontDirectory('<folder with fonts>', null);
    • Apply custom font name mappings. This functionality is very useful if your font name includes ' ' (space) characters in it. 
      RNFFmpegConfig.setFontDirectory('<folder with fonts>', { my_easy_font_name: "my complex font name" });

  13. Use your own fontconfig configuration.

    RNFFmpegConfig.setFontconfigConfigurationPath('<fontconfig configuration directory>');

  14. Disable log functionality of the library. Logs will not be printed to console and log callback will be disabled.

    RNFFmpegConfig.disableLogs();

  15. Disable statistics functionality of the library. Statistics callback will be disabled but the last received statistics data will be still available.

    RNFFmpegConfig.disableStatistics();

  16. Create new FFmpeg pipe.

    RNFFmpegConfig.registerNewFFmpegPipe().then(pipe => {
    console.log("New ffmpeg pipe: " + pipe1);
});

    4. Test Application

    You can see how react-native-ffmpeg is used inside an application by running test application provided under the react-native-ffmpeg-test repository. It supports command execution, video encoding, accessing https, encoding audio, burning subtitles, video stabilisation, pipe operations and concurrent command execution.

5. Tips

Apply provided solutions if you encounter one of the following issues.

6. Updates

Refer to Changelog for updates.

7. License

This project is licensed under the LGPL v3.0. However, if installation is customized to use a package with -gpl postfix (min-gpl, https-gpl, full-gpl) then ReactNativeFFmpeg is subject to the GPL v3.0 license.

In test application; embedded fonts are licensed under the SIL Open Font License, other digital assets are published in the public domain.

8. Patents

It is not clearly explained in their documentation, but it is believed that FFmpeg, kvazaar, x264 and x265 include algorithms which are subject to software patents. If you live in a country where software algorithms are patentable then you'll probably need to pay royalty fees to patent holders. We are not lawyers though, so we recommend that you seek legal advice first. See FFmpeg Patent Mini-FAQ.

9. Contributing

Feel free to submit issues or pull requests.

Please note that master branch includes only the latest released source code. Changes planned for the next release are implemented under the development branch. Therefore, if you want to create a pull request, please open it against the development.

10. See Also