MobileFFmpeg

FFmpeg for Android and IOS

1. Features

Use prebuilt binaries available under Github/JCenter/CocoaPods or build your own version with external libraries you need
Supports
- Both Android and IOS
- FFmpeg v3.4.x and v4.0.x releases
- 24 external libraries
  
  chromaprint, fontconfig, freetype, fribidi, gmp, gnutls, kvazaar, lame, libaom, libass, libiconv, libilbc, libtheora, libvorbis, libvpx, libwebp, libxml2, opencore-amr, opus, shine, snappy, soxr, speex, wavpack
- 4 external libraries with GPL license
  
  vid.stab, x264, x265, xvidcore
Exposes FFmpeg capabilities both directly from FFmpeg libraries and through MobileFFmpeg wrapper library
Creates shared libraries (.so for Android, .dylib for IOS)
Includes cross-compile instructions for 38 open-source libraries

chromaprint, expat, ffmpeg, fontconfig, freetype, fribidi, giflib, gmp, gnutls, kvazaar, lame, libaom, libass, libiconv, libilbc, libjpeg, libjpeg-turbo, libogg, libpng, libtheora, libuuid, libvorbis, libvpx, libwebp, libxml2, nettle, opencore-amr, opus, shine, snappy, soxr, speex, tiff, vid.stab, wavpack, x264, x265, xvidcore
Licensed under LGPL 3.0, can be customized to support GPL v3.0

1.1 Android

Supports arm-v7a, arm-v7a-neon, arm64-v8a, x86 and x86_64 architectures
Creates Android archive with .aar extension

1.2 IOS

Supports armv7, armv7s, arm64, i386 and x86_64 architectures
ARC enabled library
Built with -fembed-bitcode flag
Creates IOS dynamic universal (fat) library
Creates IOS dynamic framework for IOS 8 or later

2. Using

Prebuilt libraries are available under Github, JCenter and CocoaPods

There are eight different prebuilt packages. Below you can see which external libraries are enabled in each of them.

min	min-gpl	https	https-gpl	audio	video	full	full-gpl
-	vid.stab³ x264¹ x265³ xvidcore¹	gnutls	gnutls vid.stab³ x264¹ x265³ xvidcore¹	chromaprint³ lame libilbc¹ libvorbis opencore-amr opus¹ shine soxr² speex wavpack	fontconfig freetype fribidi kvazaar libaom² libass libiconv libtheora libvpx snappy¹	chromaprint³ fontconfig freetype fribidi gmp gnutls kvazaar lame libaom² libass libiconv libilbc¹ libtheora libvorbis libvpx libwebp libxml2 opencore-amr opus¹ shine snappy¹ soxr² speex wavpack	chromaprint³ fontconfig freetype fribidi gmp gnutls kvazaar lame libaom² libass libiconv libilbc¹ libtheora libvorbis libvpx libwebp libxml2 opencore-amr opus¹ shine snappy¹ soxr² speex vid.stab³ wavpack x264¹ x265³ xvidcore¹

¹ - Supported since v1.1

² - Supported since v2.0

³ - Supported since v2.1

2.1 Android

Add MobileFFmpeg dependency from jcenter()

dependencies {`
    implementation 'com.arthenica:mobile-ffmpeg-full:2.1.1'
}

Execute commands.

import com.arthenica.mobileffmpeg.FFmpeg;

int rc = FFmpeg.execute("-i file1.mp4 -c:v mpeg4 file2.mp4");

if (rc == RETURN_CODE_SUCCESS) {
    Log.i(Config.TAG, "Command execution completed successfully.");
} else if (rc == RETURN_CODE_CANCEL) {
    Log.i(Config.TAG, "Command execution cancelled by user.");
} else {
    Log.i(Config.TAG, String.format("Command execution failed with rc=%d.", rc));
}

Stop an ongoing operation.
```
FFmpeg.cancel();
```

Enable log callback.

Config.enableLogCallback(new LogCallback() {
    public void apply(LogMessage message) {
        Log.d(Config.TAG, message.getText());
    }
});

Enable statistics callback.

Config.enableStatisticsCallback(new StatisticsCallback() {
    public void apply(Statistics newStatistics) {
        Log.d(Config.TAG, String.format("frame: %d, time: %d", newStatistics.getVideoFrameNumber(), newStatistics.getTime()));
    }
});

Set log level.

Config.setLogLevel(Level.AV_LOG_FATAL);

Config.setFontDirectory(this, "<folder with fonts>", Collections.EMPTY_MAP);

2.2 IOS

Add MobileFFmpeg pod to your Podfile
```
pod 'mobile-ffmpeg-full', '~> 2.1.1'
```

Create and execute commands.

#import <mobileffmpeg/MobileFFmpeg.h>

int rc = [MobileFFmpeg execute: @"-i file1.mp4 -c:v mpeg4 file2.mp4"];

if (rc == RETURN_CODE_SUCCESS) {
    NSLog(@"Command execution completed successfully.\n");
} else if (rc == RETURN_CODE_CANCEL) {
    NSLog(@"Command execution cancelled by user.\n");
} else {
    NSLog(@"Command execution failed with rc=%d.\n", rc);
}

Stop an ongoing operation.
```
[MobileFFmpeg cancel];
```

Enable log callback.

- (void)logCallback: (int)level :(NSString*)message {
    dispatch_async(dispatch_get_main_queue(), ^{
        NSLog(@"%@", message);
    });
}
...
[MobileFFmpegConfig setLogDelegate:self];

Enable statistics callback.

- (void)statisticsCallback:(Statistics *)newStatistics {
    dispatch_async(dispatch_get_main_queue(), ^{
        NSLog(@"frame: %d, time: %d\n", newStatistics.getVideoFrameNumber, newStatistics.getTime);
    });
}
...
[MobileFFmpegConfig setStatisticsDelegate:self];

Set log level.

[MobileFFmpegConfig setLogLevel:AV_LOG_FATAL];

[MobileFFmpegConfig setFontDirectory:@"<folder with fonts>" with:nil];

2.3 Test Application

You can see how MobileFFmpeg is used inside an application by running test applications provided. There is an Android test application under the android/test-app folder and an IOS test application under the ios/test-app folder. Both applications are identical and supports command execution, video encoding, accessing https, encoding audio, burning subtitles and video stabilization.

3. Versions

MobileFFmpeg v1.x is the previous stable, includes FFmpeg v3.4.4
MobileFFmpeg v2.x is the current stable, includes FFmpeg v4.0.2

4. Building

4.1 Prerequisites

Use your package manager (apt, yum, dnf, brew, etc.) to install the following packages.
```
autoconf automake libtool pkg-config curl cmake gcc gperf texinfo yasm nasm bison
```

Some of these packages are not mandatory for the default build. Please visit Android Prerequisites and IOS Prerequisites for the details.

Android builds require these additional packages.
- Android SDK 5.0 Lollipop (API Level 21) or later
- Android NDK r16b or later with LLDB and CMake
- gradle 4.4 or later
IOS builds need these extra packages and tools.
- IOS SDK 7.0.x or later
- Xcode 8.x or later
- Command Line Tools

4.2 Build Scripts

Use android.sh and ios.sh to build MobileFFmpeg for each platform. After a successful build, compiled FFmpeg and MobileFFmpeg libraries can be found under prebuilt directory.

Both android.sh and ios.sh can be customized to override default settings, android.sh and ios.sh wiki pages include all available build options.

4.2.1 Android

export ANDROID_NDK_ROOT=<Android NDK Path>
./android.sh

4.2.2 IOS

./ios.sh

4.3 GPL Support

It is possible to enable GPL licensed libraries x264, xvidcore since v1.1 and vid.stab, x265 since v2.1 from the top level build scripts. Their source code is not included in the repository and downloaded when enabled.

4.4 External Libraries

build directory includes build scripts for external libraries. There are two scripts for each library, one for Android and one for IOS. They include all options/flags used to cross-compile the libraries. ASM is enabled by most of them, exceptions are listed under the ASM Support page.

5. Documentation

A more detailed documentation is available at Wiki.

6. License

This project is licensed under the LGPL v3.0. However, if source code is built using optional --enable-gpl flag or prebuilt binaries with -gpl postfix are used then MobileFFmpeg is subject to the GPL v3.0 license.

Source code of FFmpeg and external libraries is included in compliance with their individual licenses.

strip-frameworks.sh script included and distributed is published under the Apache License version 2.0.

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

Please visit License page for the details.

7. Contributing

If you have any recommendations or ideas to improve it, please feel free to submit issues or pull requests. Any help is appreciated.

IanField90/mobile-ffmpeg