Fork of https://github.com/arthenica/ffmpeg-kit

Go to file

Taner Sener 1abae81589 rename android library folder name		2021-01-26 22:14:59 +00:00
.github	add github templates and actions	2021-01-09 16:20:22 +00:00
android	rename android library folder name	2021-01-26 22:14:59 +00:00
apple	create fontconfig configuration under the fontconfig folder and allow registration of multiple font directories	2021-01-24 23:42:51 +00:00
docs/assets	add ffmpeg implementation	2020-10-25 14:40:54 +00:00
scripts	rename android library folder name	2021-01-26 22:14:59 +00:00
src	update external library scripts	2021-01-09 16:03:59 +00:00
tools	rename android library folder name	2021-01-26 22:14:59 +00:00
.gitignore	add ffmpeg implementation	2020-10-25 14:40:54 +00:00
android.sh	rename android library folder name	2021-01-26 22:14:59 +00:00
apple.sh	add apple.sh script	2021-01-10 00:04:01 +00:00
ios.sh	add apple.sh script	2021-01-10 00:04:01 +00:00
LICENSE.GPLv3	add ffmpeg implementation	2020-10-25 14:40:54 +00:00
LICENSE.LGPLv3	add ffmpeg implementation	2020-10-25 14:40:54 +00:00
macos.sh	add apple.sh script	2021-01-10 00:04:01 +00:00
README.md	update external library scripts	2021-01-09 16:03:59 +00:00
tvos.sh	add apple.sh script	2021-01-10 00:04:01 +00:00

README.md

FFmpegKit

FFmpeg kit for applications. Supports Android, iOS, tvOS.

1. Features

Includes both FFmpeg and FFprobe
Use binaries available at Github/JCenter/CocoaPods or build your own version with external libraries you need
Supports
- Android, iOS and tvOS
- FFmpeg v4.4-dev releases
- 29 external libraries
  
  chromaprint, fontconfig, freetype, fribidi, gmp, gnutls, kvazaar, lame, libaom, libass, libiconv, libilbc, libtheora, libvorbis, libvpx, libwebp, libxml2, opencore-amr, openh264, opus, sdl, shine, snappy, soxr, speex, tesseract, twolame, vo-amrwbenc, wavpack
- 5 external libraries with GPL license
  
  rubberband, vid.stab, x264, x265, xvidcore
- Concurrent execution
Exposes both FFmpeg library and FFmpegKit wrapper library capabilities
Includes cross-compile instructions for 48 open-source libraries

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

1.1 Android

Builds arm-v7a, arm-v7a-neon, arm64-v8a, x86 and x86_64 architectures
Supports zlib and MediaCodec system libraries
Camera access on supported devices
Builds shared native libraries (.so)
Creates Android archives with .aar extension
Supports API Level 16+

1.2 iOS

Builds armv7, armv7s, arm64, arm64e, i386, x86_64 and x86_64 (Mac Catalyst) architectures
Supports bzip2, iconv, libuuid, zlib system libraries and AudioToolbox, VideoToolbox, AVFoundation system frameworks
Objective-C API
Camera access
ARC enabled library
Built with -fembed-bitcode flag
Creates static frameworks, static xcframeworks and static universal (fat) libraries (.a)
Supports iOS SDK 9.3 or later

1.3 tvOS

Builds arm64 and x86_64 architectures
Supports bzip2, iconv, libuuid, zlib system libraries and AudioToolbox, VideoToolbox system frameworks
Objective-C API
ARC enabled library
Built with -fembed-bitcode flag
Creates static frameworks and static universal (fat) libraries (.a)
Supports tvOS SDK 9.2 or later

2. Using

Prebuilt binaries are available at Github, JCenter and CocoaPods.

2.1 Packages

There are eight different ffmpeg-kit packages. Below you can see which system libraries and external libraries are enabled in each of package.

Please remember that some parts of FFmpeg are licensed under the GPL and only GPL licensed ffmpeg-kit packages include them.

	^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
^{tvos system libraries}	^zlib ^AudioToolbox ^iconv ^VideoToolbox ^bzip2

AVFoundation is not available on tvOS, VideoToolbox is not available on tvOS LTS releases

2.2 Android

Add FFmpegKit dependency to your build.gradle in ffmpeg-kit-<package name> pattern.
```
dependencies {
    implementation 'com.arthenica:ffmpeg-kit-full:4.4'
}
```

Execute synchronous FFmpeg commands.

import com.arthenica.ffmpegkit.Config;
import com.arthenica.ffmpegkit.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 and the output below.", rc));
    Config.printLastCommandOutput(Log.INFO);
}

Execute asynchronous FFmpeg commands.

import com.arthenica.ffmpegkit.Config;
import com.arthenica.ffmpegkit.FFmpeg;

long executionId = FFmpeg.executeAsync("-i file1.mp4 -c:v mpeg4 file2.mp4", new ExecuteCallback() {

    @Override
    public void apply(final long executionId, final int returnCode) {
        if (returnCode == RETURN_CODE_SUCCESS) {
            Log.i(Config.TAG, "Async command execution completed successfully.");
        } else if (returnCode == RETURN_CODE_CANCEL) {
            Log.i(Config.TAG, "Async command execution cancelled by user.");
        } else {
            Log.i(Config.TAG, String.format("Async command execution failed with returnCode=%d.", returnCode));
        }
    }
});

Execute FFprobe commands.

import com.arthenica.ffmpegkit.Config;
import com.arthenica.ffmpegkit.FFprobe;

int rc = FFprobe.execute("-i file1.mp4");

if (rc == RETURN_CODE_SUCCESS) {
    Log.i(Config.TAG, "Command execution completed successfully.");
} else {
    Log.i(Config.TAG, String.format("Command execution failed with rc=%d and the output below.", rc));
    Config.printLastCommandOutput(Log.INFO);
}

Check execution output later.

int rc = Config.getLastReturnCode();

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 and the output below.", rc));
    Config.printLastCommandOutput(Log.INFO);
}

Stop ongoing FFmpeg operations.
- Stop all executions
```
FFmpeg.cancel();
```
- Stop a specific execution
```
FFmpeg.cancel(executionId);
```

Get media information for a file.

MediaInformation info = FFprobe.getMediaInformation("<file path or uri>");

Record video using Android camera.

FFmpeg.execute("-f android_camera -i 0:0 -r 30 -pixel_format bgr0 -t 00:00:05 <record file path>");

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()));
    }
});

Ignore the handling of a signal.
```
Config.ignoreSignal(Signal.SIGXCPU);
```

List ongoing executions.

final List<FFmpegExecution> ffmpegExecutions = FFmpeg.listExecutions();
for (int i = 0; i < ffmpegExecutions.size(); i++) {
    FFmpegExecution execution = ffmpegExecutions.get(i);
    Log.d(TAG, String.format("Execution %d = id:%d, startTime:%s, command:%s.", i, execution.getExecutionId(), execution.getStartTime(), execution.getCommand()));
}

Set default log level.

Config.setLogLevel(Level.AV_LOG_FATAL);

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

2.3 iOS / tvOS

Add FFmpegKit dependency to your Podfile in ffmpeg-kit-<package name> pattern.
- iOS
```
pod 'ffmpeg-kit-full', '~> 4.4'
```
- tvOS
```
pod 'ffmpeg-kit-tvos-full', '~> 4.4'
```

Execute synchronous FFmpeg commands.

#import <ffmpegkit/FFmpegKitConfig.h>
#import <ffmpegkit/FFmpegKit.h>

int rc = [FFmpegKit 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 and output=%@.\n", rc, [FFmpegKitConfig getLastCommandOutput]);
}

Execute asynchronous FFmpeg commands.

#import <ffmpegkit/FFmpegKitConfig.h>
#import <ffmpegkit/FFmpegKit.h>

long executionId = [FFmpegKit executeAsync:@"-i file1.mp4 -c:v mpeg4 file2.mp4" withCallback:self];

- (void)executeCallback:(long)executionId :(int)returnCode {
    if (rc == RETURN_CODE_SUCCESS) {
        NSLog(@"Async command execution completed successfully.\n");
    } else if (rc == RETURN_CODE_CANCEL) {
        NSLog(@"Async command execution cancelled by user.\n");
    } else {
        NSLog(@"Async command execution failed with rc=%d.\n", rc);
    }
}

Execute FFprobe commands.

#import <ffmpegkit/FFmpegKitConfig.h>
#import <ffmpegkit/FFprobeKit.h>

int rc = [FFprobeKit execute: @"-i file1.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 and output=%@.\n", rc, [FFmpegKitConfig getLastCommandOutput]);
}

Check execution output later.

int rc = [FFmpegKitConfig getLastReturnCode];
NSString *output = [FFmpegKitConfig getLastCommandOutput];

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 and output=%@.\n", rc, output);
}

Stop ongoing FFmpeg operations.
- Stop all executions
```
[FFmpegKit cancel];
```
- Stop a specific execution
```
[FFmpegKit cancel:executionId];
```

Get media information for a file.

MediaInformation *mediaInformation = [FFprobeKit getMediaInformation:@"<file path or uri>"];

Record video and audio using iOS camera. This operation is not supported on tvOS since AVFoundation is not available on tvOS.

[FFmpegKit execute: @"-f avfoundation -r 30 -video_size 1280x720 -pixel_format bgr0 -i 0:0 -vcodec h264_videotoolbox -vsync 2 -f h264 -t 00:00:05 %@", recordFilePath];

Enable log callback.

[FFmpegKitConfig setLogDelegate:self];

- (void)logCallback:(long)executionId :(int)level :(NSString*)message {
    dispatch_async(dispatch_get_main_queue(), ^{
        NSLog(@"%@", message);
    });
}

Enable statistics callback.

[FFmpegKitConfig setStatisticsDelegate:self];

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

Ignore the handling of a signal.

[FFmpegKitConfig ignoreSignal:SIGXCPU];

List ongoing executions.

NSArray* ffmpegExecutions = [FFmpegKit listExecutions];
for (int i = 0; i < [ffmpegExecutions count]; i++) {
    FFmpegExecution* execution = [ffmpegExecutions objectAtIndex:i];
    NSLog(@"Execution %d = id: %ld, startTime: %@, command: %@.\n", i, [execution getExecutionId], [execution getStartTime], [execution getCommand]);
}

Set default log level.

[FFmpegKitConfig setLogLevel:AV_LOG_FATAL];

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

2.4 Manual Installation

2.4.1 Android

You can import FFmpegKit aar packages in Android Studio using the File -> New -> New Module -> Import .JAR/.AAR Package menu.

2.4.2 iOS / tvOS

iOS and tvOS frameworks can be installed manually using the Importing Frameworks guide. If you want to use universal binaries please refer to Using Universal Binaries guide.

2.5 Test Application

You can see how FFmpegKit is used inside an application by running test applications provided. There is an Android test application under the android/test-app folder, an iOS test application under the ios/test-app folder and a tvOS test application under the tvos/test-app folder.

All applications are identical and supports command execution, video encoding, accessing https, encoding audio, burning subtitles, video stabilisation, pipe operations and concurrent command execution.

3. Versions

dev part in FFmpeg version number indicates that FFmpeg source is pulled from the FFmpeg master branch. Exact version number is obtained using git describe --tags.

FFmpegKit Version	FFmpeg Version	Release Date
4.4	4.4-dev-416	Jul 25, 2020
4.4.LTS	4.4-dev-416	Jul 24, 2020

4. LTS Releases

FFmpegKit binaries are published in two release variants: Main Release and LTS Release.

Main releases include complete functionality of the library and support the latest SDK/API features.
LTS releases are customized to support a wider range of devices. They are built using older API/SDK versions, so some features are not available on them.

This table shows the differences between two variants.

	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	12.1	9.3
iOS AVFoundation	Yes	-
iOS Architectures	arm64 x86-64 x86-64-mac-catalyst	armv7 arm64 i386 x86-64
tvOS SDK	10.2	9.2
tvOS Architectures	arm64 x86-64	arm64 x86-64

5. Building

Build scripts from master and development branches are tested periodically. See the latest status from the table below.

branch	status
master
development

5.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 autogen patch git

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

Android builds require these additional packages.
- Android SDK 4.1 Jelly Bean (API Level 16) or later
- Android NDK r21 or later with LLDB and CMake
iOS builds need these extra packages and tools.
- Xcode 7.3.1 or later
- iOS SDK 9.3 or later
- Command Line Tools
tvOS builds need these extra packages and tools.
- Xcode 7.3.1 or later
- tvOS SDK 9.2 or later
- Command Line Tools

5.2 Build Scripts

Use android.sh, ios.sh and tvos.sh to build FFmpegKit for each platform.

All three scripts support additional options and can be customized to enable/disable specific external libraries and/or architectures. Please refer to wiki pages of android.sh, ios.sh and tvos.sh to see all available build options.

5.2.1 Android

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

5.2.2 iOS

./ios.sh

5.2.3 tvOS

./tvos.sh

5.2.4 Building LTS Binaries

Use --lts option to build lts binaries for each platform.

5.3 Build Output

All libraries created by the top level build scripts (android.sh, ios.sh and tvos.sh) can be found under the prebuilt directory.

Android archive (.aar file) is located under the android-aar folder
iOS frameworks are located under the ios-framework folder
iOS xcframeworks are located under the ios-xcframework folder
iOS universal binaries are located under the ios-universal folder
tvOS frameworks are located under the tvos-framework folder
tvOS universal binaries are located under the tvos-universal folder

5.4 GPL Support

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

5.5 External Libraries

build directory includes build scripts of all external libraries. Two scripts exist for each external library, one for Android and one for iOS / tvOS. Each of these two scripts contains options/flags used to cross-compile the library on the specified platform.

CPU optimizations (ASM) are enabled for most of the external libraries. Details and exceptions can be found under the ASM Support wiki page.

6. Documentation

A more detailed documentation is available at Wiki.

8. License

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

The source code of all external libraries included is in compliance with their individual licenses.

openh264 source code included in this repository is licensed under the 2-clause BSD License but this license does not cover the MPEG LA licensing fees. If you build ffmpeg-kit with openh264 and distribute that library, then you are subject to pay MPEG LA licensing fees. Refer to OpenH264 FAQ page for the details. Please note that ffmpeg-kit does not publish a binary with openh264 inside.

strip-frameworks.sh script included and distributed (until v4.x) is published under the Apache License version 2.0.

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

Please visit License page for the details.

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

openh264 clearly states that it uses patented algorithms. Therefore, if you build ffmpeg-kit with openh264 and distribute that library, then you are subject to pay MPEG LA licensing fees. Refer to OpenH264 FAQ page for the details.

10. Contributing

Feel free to submit issues or pull requests.

Please note that master 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.