add platform specific documentation
This commit is contained in:
Taner Sener
parent
0f64d49419
commit
9a2792a376
19
README.md
19
README.md
|
|
@ -1,4 +1,4 @@
|
|||
# FFmpegKit    [](https://travis-ci.org/tanersener/ffmpeg-kit)
|
||||
# FFmpegKit    [](https://travis-ci.org/tanersener/ffmpeg-kit)
|
||||
|
||||
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
|
||||
|
||||
#### 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
|
||||
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.
|
||||
|
||||
Refer to `Android` page for `Android` devices and `Apple` page for `iOS`, `macOS`, `tvOS` devices to see the
|
||||
prerequisites for each platform.
|
||||
Refer to [Android](https://github.com/tanersener/ffmpeg-kit/tree/development/android) page for `Android` devices and
|
||||
[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
|
||||
|
||||
|
|
@ -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,
|
||||
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
|
||||
|
||||
There are eight different `ffmpeg-kit` packages distributed on
|
||||
|
|
|
|||
184
android/README.md
Normal file
184
android/README.md
Normal file
|
|
@ -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.
|
||||
223
apple/README.md
Normal file
223
apple/README.md
Normal file
|
|
@ -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…
Reference in New Issue
Block a user