add platform specific documentation

pull/7/head v4.4.LTS
Taner Sener 4 years ago
parent 0f64d49419
commit 9a2792a376
  1. 19
      README.md
  2. 184
      android/README.md
  3. 223
      apple/README.md

@ -1,4 +1,4 @@
# FFmpegKit ![GitHub release](https://img.shields.io/badge/release-v4.4-blue.svg) ![Maven Central](https://img.shields.io/maven-central/v/com.arthenica/ffmpeg-kit-min) ![CocoaPods](https://img.shields.io/cocoapods/v/ffmpeg-kit-min) [![Build Status](https://travis-ci.org/tanersener/ffmpeg-kit.svg?branch=master)](https://travis-ci.org/tanersener/ffmpeg-kit) # FFmpegKit ![GitHub release](https://img.shields.io/badge/release-v4.4-blue.svg) ![Maven Central](https://img.shields.io/maven-central/v/com.arthenica/ffmpeg-kit-min) ![CocoaPods](https://img.shields.io/cocoapods/v/ffmpeg-kit-ios-min) [![Build Status](https://travis-ci.org/tanersener/ffmpeg-kit.svg?branch=master)](https://travis-ci.org/tanersener/ffmpeg-kit)
FFmpeg Kit for applications. FFmpeg Kit for applications.
@ -24,13 +24,22 @@ FFmpeg Kit for applications.
- Licensed under `LGPL 3.0`, or `GPL v3.0` if GPL licensed libraries are enabled - Licensed under `LGPL 3.0`, or `GPL v3.0` if GPL licensed libraries are enabled
#### 1.1 Android
See [Android](https://github.com/tanersener/ffmpeg-kit/tree/development/android).
#### 1.2 iOS, macOS, tvOS
See [Apple](https://github.com/tanersener/ffmpeg-kit/tree/development/apple).
### 2. Build Scripts ### 2. Build Scripts
Use `android.sh`, `ios.sh`, `macos.sh` and `tvos.sh` to build `FFmpegKit` for each platform. Use `android.sh`, `ios.sh`, `macos.sh` and `tvos.sh` to build `FFmpegKit` for each platform.
All four scripts support additional options to enable external libraries or disable platform architectures. All four scripts support additional options to enable external libraries or disable platform architectures.
Refer to `Android` page for `Android` devices and `Apple` page for `iOS`, `macOS`, `tvOS` devices to see the Refer to [Android](https://github.com/tanersener/ffmpeg-kit/tree/development/android) page for `Android` devices and
prerequisites for each platform. [Apple](https://github.com/tanersener/ffmpeg-kit/tree/development/apple) page for `iOS`, `macOS`, `tvOS` devices to see
the prerequisites for each platform.
### 3. FFmpegKit Library ### 3. FFmpegKit Library
@ -40,6 +49,10 @@ provides additional features on top of `FFmpeg` to enable platform specific reso
`Android` library has a `Java` API and `Apple` libraries (`iOS`, `macOS`, `tvOS`) have an `Objective-C` API, `Android` library has a `Java` API and `Apple` libraries (`iOS`, `macOS`, `tvOS`) have an `Objective-C` API,
which are identical. which are identical.
See [Android](https://github.com/tanersener/ffmpeg-kit/tree/development/android) page to learn how the `Java` API
can be used on `Android` devices and [Apple](https://github.com/tanersener/ffmpeg-kit/tree/development/apple) page to
learn more about `Objective-C` API for `iOS`, `macOS`, `tvOS` devices.
### 4. Binary Packages ### 4. Binary Packages
There are eight different `ffmpeg-kit` packages distributed on There are eight different `ffmpeg-kit` packages distributed on

@ -0,0 +1,184 @@
# FFmpegKit for Android
### 1. Features
- Supports
- `API Level 16+`
- `arm-v7a`, `arm-v7a-neon`, `arm64-v8a`, `x86` and `x86_64` architectures
- `zlib` and `MediaCodec` system libraries
- Can handle Storage Access Framework (SAF) uris
- Camera access on [supported devices](https://developer.android.com/ndk/guides/stable_apis#camera)
- Builds shared native libraries (.so)
- Creates Android archive with .aar extension
### 2. Building
Run `android.sh` at project root directory to build `ffmpeg-kit` and `ffmpeg` shared libraries.
#### 2.1 Prerequisites
`android.sh` requires the following packages and tools.
1. Install Android tools listed below.
- **Android SDK Build Tools**
- **Android NDK r21e** or later with LLDB and CMake
2. 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 git wget autopoint meson ninja
```
3. Set `ANDROID_SDK_ROOT` and `ANDROID_NDK_ROOT` environment variables.
```
export ANDROID_SDK_ROOT=<Android SDK Path>
export ANDROID_NDK_ROOT=<Android NDK Path>
```
4. `android.sh` needs network connectivity and internet access to `github.com` in order to download the source code
of all libraries except `ffmpeg-kit`.
#### 2.2 Options
Use `--enable-<library name>` flags to support additional external or system libraries and
`--disable-<architecture name>` to disable architectures you don't want to build.
```
./android.sh --enable-fontconfig --disable-arm-v7a-neon
```
Run `--help` to see all available build options.
#### 2.3 LTS Binaries
Use `--lts` option to build lts binaries for each architecture.
#### 2.4 Build Output
All libraries created by `android.sh` can be found under the `prebuilt` directory.
- `Android` archive (.aar file) for `Main` builds is located under the `bundle-android-aar` folder.
- `Android` archive (.aar file) for `LTS` builds is located under the `bundle-android-aar-lts` folder.
### 3. Using
#### 3.1 Android API
1. Declare `mavenCentral` repository and add `FFmpegKit` dependency to your `build.gradle` in
`ffmpeg-kit-<package name>` pattern. Use one of the `FFmpegKit` package names given in the
project [README](https://github.com/tanersener/ffmpeg-kit).
```
repositories {
mavenCentral()
}
dependencies {
implementation 'com.arthenica:ffmpeg-kit-full:4.4.LTS'
}
```
2. Execute synchronous FFmpeg commands.
```
import com.arthenica.ffmpegkit.FFmpegKit;
import com.arthenica.ffmpegkit.ReturnCode;
FFmpegSession session = FFmpegKit.execute("-i file1.mp4 -c:v mpeg4 file2.mp4");
if (ReturnCode.isSuccess(session.getReturnCode())) {
// SUCCESS
} else if (ReturnCode.isCancel(session.getReturnCode())) {
// CANCEL
} else {
// FAILURE
Log.d(TAG, String.format("Command failed with state %s and rc %s.%s", session.getState(), session.getReturnCode(), session.getFailStackTrace()));
}
```
3. Execute asynchronous FFmpeg commands by providing session specific execute/log/session callbacks.
```
FFmpegKit.executeAsync("-i file1.mp4 -c:v mpeg4 file2.mp4", new ExecuteCallback() {
@Override
public void apply(Session session) {
SessionState state = session.getState();
ReturnCode returnCode = session.getReturnCode();
// CALLED WHEN SESSION IS EXECUTED
Log.d(TAG, String.format("FFmpeg process exited with state %s and rc %s.%s", state, returnCode, session.getFailStackTrace()));
}
}, new LogCallback() {
@Override
public void apply(com.arthenica.ffmpegkit.Log log) {
// CALLED WHEN SESSION PRINTS LOGS
}
}, new StatisticsCallback() {
@Override
public void apply(Statistics statistics) {
// CALLED WHEN SESSION GENERATES STATISTICS
}
});
```
4. Execute synchronous FFprobe commands.
```
FFprobeSession session = FFprobeKit.execute(ffprobeCommand);
if (!ReturnCode.isSuccess(session.getReturnCode())) {
Log.d(TAG, "Command failed. Please check output for the details.");
}
```
5. Get session output.
```
Session session = FFmpegKit.execute("-i file1.mp4 -c:v mpeg4 file2.mp4");
Log.d(TAG, session.getOutput());
```
6. Stop ongoing FFmpeg operations.
- Stop all executions
```
FFmpegKit.cancel();
```
- Stop a specific session
```
FFmpegKit.cancel(sessionId);
```
7. Get media information for a file.
```
MediaInformationSession mediaInformation = FFprobeKit.getMediaInformation("<file path or uri>");
mediaInformation.getMediaInformation();
```
8. List previous FFmpeg sessions.
```
List<FFmpegSession> ffmpegSessions = FFmpegKit.listSessions();
for (int i = 0; i < ffmpegSessions.size(); i++) {
FFmpegSession session = ffmpegSessions.get(i);
Log.d(TAG, String.format("Session %d = id:%d, startTime:%s, duration:%s, state:%s, returnCode:%s.",
i,
session.getSessionId(),
session.getStartTime(),
session.getDuration(),
session.getState(),
session.getReturnCode()));
}
```
### 4. Test Application
You can see how `FFmpegKit` is used inside an application by running test applications developed under the
[FFmpegKit Test](https://github.com/tanersener/ffmpeg-kit-test) project.

@ -0,0 +1,223 @@
# FFmpegKit for iOS, macOS and tvOS
### 1. Features
#### 1.1 iOS
- Builds `armv7`, `armv7s`, `arm64`, `arm64-simulator`, `arm64e`, `i386`, `x86_64`, `x86_64-mac-catalyst` and
`arm64-mac-catalyst` architectures
- Supports `bzip2`, `iconv`, `libuuid`, `zlib` system libraries and `AudioToolbox`, `AVFoundation`, `VideoToolbox` 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.2 macOS
- Builds `arm64` and `x86_64` architectures
- Supports `bzip2`, `iconv`, `libuuid`, `zlib` system libraries and `AudioToolbox`, `AVFoundation`, `CoreImage`,
`OpenCL`, `OpenGL`, `VideoToolbox` 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 `macOS SDK 10.11` or later
#### 1.3 tvOS
- Builds `arm64`, `arm64-simulator` 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`, static `xcframeworks` and static `universal (fat)` libraries (.a)
- Supports `tvOS SDK 9.2` or later
### 2. Building
Run `ios.sh`/`macos.sh`/`tvos.sh` at project root directory to build `ffmpeg-kit` and `ffmpeg` shared libraries for a
platform.
Optionally, use `apple.sh` to combine bundles created by these three scripts in a single bundle.
#### 2.1 Prerequisites
`ios.sh`/`macos.sh`/`tvos.sh` requires the following packages and tools.
1. Use your package manager (brew, etc.) to install the following packages.
```
autoconf automake libtool pkg-config curl cmake gcc gperf texinfo yasm nasm bison autogen git wget autopoint meson ninja
```
2. `ios.sh`/`macos.sh`/`tvos.sh` needs network connectivity and internet access to `github.com` in order to download
the source code of all libraries except `ffmpeg-kit`.
3. Install the tools necessary listed below in `2.1.x`.
##### 2.1.1 iOS
- **Xcode 7.3.1** or later
- **iOS SDK 9.3** or later
- **Command Line Tools**
##### 2.1.2 macOS
- **Xcode 7.3.1** or later
- **macOS SDK 10.11** or later
- **Command Line Tools**
##### 2.1.3 tvOS
- **Xcode 7.3.1** or later
- **tvOS SDK 9.2** or later
- **Command Line Tools**
#### 2.2 Options
Use `--enable-<library name>` flags to support additional external or system libraries and
`--disable-<architecture name>` to disable architectures you don't want to build.
```
./ios.sh --enable-fontconfig --disable-armv7
./macos.sh --enable-freetype --enable-macos-avfoundation --disable-arm64
./tv.sh --enable-dav1d --enable-libvpx --disable-arm64-simulator
```
Run `--help` to see all available build options.
#### 2.3 LTS Binaries
Use `--lts` option to build lts binaries for each architecture.
#### 2.4 Build Output
All libraries created can be found under the `prebuilt` directory.
- `iOS` `xcframeworks` for `Main` builds are located under the `bundle-apple-xcframework-ios` folder.
- `macOS` `xcframeworks` for `Main` builds are located under the `bundle-apple-xcframework-macos` folder.
- `tvOS` `xcframeworks` for `Main` builds are located under the `bundle-apple-xcframework-tvos` folder.
- `iOS` `frameworks` for `Main` builds are located under the `bundle-apple-framework-ios` folder.
- `iOS` `frameworks` for `LTS` builds are located under the `bundle-apple-framework-ios-lts` folder.
- `iOS` `universal (fat) libraries (.a)` for `LTS` builds are located under the `bundle-apple-universal-ios-lts` folder.
- `macOS` `frameworks` for `Main` builds are located under the `bundle-apple-framework-macos` folder.
- `macOS` `frameworks` for `LTS` builds are located under the `bundle-apple-framework-macos-lts` folder.
- `macOS` `universal (fat) libraries (.a)` for `LTS` builds are located under the `bundle-apple-universal-macos-lts` folder.
- `tvOS` `frameworks` for `Main` builds are located under the `bundle-apple-framework-tvos` folder.
- `tvOS` `frameworks` for `LTS` builds are located under the `bundle-apple-framework-tvos-lts` folder.
- `tvOS` `universal (fat) libraries (.a)` for `LTS` builds are located under the `bundle-apple-universal-tvos-lts` folder.
### 3. Using
#### 3.1 Objective API
1. add `FFmpegKit` dependency to your `Podfile` in `ffmpeg-kit-<platform>-<package name>` pattern. Use one of the
`FFmpegKit` package names given in the project [README](https://github.com/tanersener/ffmpeg-kit).
- iOS
```
pod 'ffmpeg-kit-ios-full', '~> 4.4.LTS'
```
- macOS
```
pod 'ffmpeg-kit-macos-full', '~> 4.4.LTS'
```
- tvOS
```
pod 'ffmpeg-kit-tvos-full', '~> 4.4.LTS'
```
2. Execute synchronous FFmpeg commands.
```
#include <ffmpegkit/FFmpegKit.h>
FFmpegSession* session = [FFmpegKit execute:@"-i file1.mp4 -c:v mpeg4 file2.mp4"];
ReturnCode* returnCode = [session getReturnCode];
if ([ReturnCode isSuccess:returnCode]) {
// SUCCESS
} else if ([ReturnCode isCancel:returnCode]) {
// CANCEL
} else {
// FAILURE
NSLog(@"Command failed with state %@ and rc %@.%@", [FFmpegKitConfig sessionStateToString:[session getState]], returnCode, [session getFailStackTrace]);
}
```
3. Execute asynchronous FFmpeg commands by providing session specific execute/log/session callbacks.
```
id<Session> session = [FFmpegKit executeAsync:@"-i file1.mp4 -c:v mpeg4 file2.mp4" withExecuteCallback:^(id<Session> session){
SessionState state = [session getState];
ReturnCode *returnCode = [session getReturnCode];
// CALLED WHEN SESSION IS EXECUTED
NSLog(@"FFmpeg process exited with state %@ and rc %@.%@", [FFmpegKitConfig sessionStateToString:state], returnCode, [session getFailStackTrace]);
} withLogCallback:^(Log *log) {
// CALLED WHEN SESSION PRINTS LOGS
} withStatisticsCallback:^(Statistics *statistics) {
// CALLED WHEN SESSION GENERATES STATISTICS
}];
```
4. Execute synchronous FFprobe commands.
```
FFprobeSession *session = [FFprobeKit execute:ffprobeCommand];
if ([ReturnCode isSuccess:[session getReturnCode]]) {
NSLog(@"Command failed. Please check output for the details.");
}
```
5. Get session output.
```
FFmpegSession session = FFmpegKit.execute("-i file1.mp4 -c:v mpeg4 file2.mp4");
NSLog([session getOutput]);
```
6. Stop ongoing FFmpeg operations.
- Stop all executions
```
[FFmpegKit cancel];
```
- Stop a specific session
```
[FFmpegKit cancel:sessionId];
```
7. Get media information for a file.
```
MediaInformationSession *mediaInformation = [FFprobeKit getMediaInformation:"<file path or uri>"];
MediaInformation *mediaInformation =[mediaInformation getMediaInformation];
```
8. List previous FFmpeg sessions.
```
NSArray* ffmpegSessions = [FFmpegKit listSessions];
for (int i = 0; i < [ffmpegSessions count]; i++) {
FFmpegSession* session = [ffmpegSessions objectAtIndex:i];
NSLog(@"Session %d = id: %ld, startTime: %@, duration: %ld, state:%@, returnCode:%@.\n",
i,
[session getSessionId],
[session getStartTime],
[session getDuration],
[FFmpegKitConfig sessionStateToString:[session getState]],
[session getReturnCode]);
}
```
### 4. Test Application
You can see how `FFmpegKit` is used inside an application by running test applications developed under the
[FFmpegKit Test](https://github.com/tanersener/ffmpeg-kit-test) project.
Loading…
Cancel
Save