From 9a2792a3762b922ee6e80595a246808ddf3c7816 Mon Sep 17 00:00:00 2001 From: Taner Sener Date: Wed, 3 Mar 2021 08:11:19 +0000 Subject: [PATCH] add platform specific documentation --- README.md | 19 +++- android/README.md | 184 ++++++++++++++++++++++++++++++++++++++ apple/README.md | 223 ++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 423 insertions(+), 3 deletions(-) create mode 100644 android/README.md create mode 100644 apple/README.md diff --git a/README.md b/README.md index d2aec276..25279ee2 100644 --- a/README.md +++ b/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. @@ -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 diff --git a/android/README.md b/android/README.md new file mode 100644 index 00000000..7579590f --- /dev/null +++ b/android/README.md @@ -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= + export ANDROID_NDK_ROOT= + ``` + +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-` flags to support additional external or system libraries and +`--disable-` 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-` 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(""); + mediaInformation.getMediaInformation(); + ``` + +8. List previous FFmpeg sessions. + + ``` + List 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. diff --git a/apple/README.md b/apple/README.md new file mode 100644 index 00000000..bd938bbb --- /dev/null +++ b/apple/README.md @@ -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-` flags to support additional external or system libraries and +`--disable-` 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--` 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 + + 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 = [FFmpegKit executeAsync:@"-i file1.mp4 -c:v mpeg4 file2.mp4" withExecuteCallback:^(id 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:""]; + 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.