parent
0f64d49419
commit
9a2792a376
@ -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…
Reference in new issue