|
| 1 | +# FFmpegKit for Android |
| 2 | + |
| 3 | +### 1. Features |
| 4 | +- Supports |
| 5 | + - `API Level 16+` |
| 6 | + - `arm-v7a`, `arm-v7a-neon`, `arm64-v8a`, `x86` and `x86_64` architectures |
| 7 | + - `zlib` and `MediaCodec` system libraries |
| 8 | +- Can handle Storage Access Framework (SAF) uris |
| 9 | +- Camera access on [supported devices](https://developer.android.com/ndk/guides/stable_apis#camera) |
| 10 | +- Builds shared native libraries (.so) |
| 11 | +- Creates Android archive with .aar extension |
| 12 | + |
| 13 | +### 2. Building |
| 14 | + |
| 15 | +Run `android.sh` at project root directory to build `ffmpeg-kit` and `ffmpeg` shared libraries. |
| 16 | + |
| 17 | +#### 2.1 Prerequisites |
| 18 | + |
| 19 | +`android.sh` requires the following packages and tools. |
| 20 | + |
| 21 | +1. Install Android tools listed below. |
| 22 | + - **Android SDK Build Tools** |
| 23 | + - **Android NDK r21e** or later with LLDB and CMake |
| 24 | + |
| 25 | +2. Use your package manager (apt, yum, dnf, brew, etc.) to install the following packages. |
| 26 | + |
| 27 | + ``` |
| 28 | + autoconf automake libtool pkg-config curl cmake gcc gperf texinfo yasm nasm bison autogen git wget autopoint meson ninja |
| 29 | + ``` |
| 30 | +
|
| 31 | +3. Set `ANDROID_SDK_ROOT` and `ANDROID_NDK_ROOT` environment variables. |
| 32 | + ``` |
| 33 | + export ANDROID_SDK_ROOT=<Android SDK Path> |
| 34 | + export ANDROID_NDK_ROOT=<Android NDK Path> |
| 35 | + ``` |
| 36 | +
|
| 37 | +4. `android.sh` needs network connectivity and internet access to `github.com` in order to download the source code |
| 38 | + of all libraries except `ffmpeg-kit`. |
| 39 | +
|
| 40 | +#### 2.2 Options |
| 41 | +
|
| 42 | +Use `--enable-<library name>` flags to support additional external or system libraries and |
| 43 | +`--disable-<architecture name>` to disable architectures you don't want to build. |
| 44 | +
|
| 45 | +``` |
| 46 | +./android.sh --enable-fontconfig --disable-arm-v7a-neon |
| 47 | +``` |
| 48 | +
|
| 49 | +Run `--help` to see all available build options. |
| 50 | +
|
| 51 | +#### 2.3 LTS Binaries |
| 52 | +
|
| 53 | +Use `--lts` option to build lts binaries for each architecture. |
| 54 | +
|
| 55 | +#### 2.4 Build Output |
| 56 | +
|
| 57 | +All libraries created by `android.sh` can be found under the `prebuilt` directory. |
| 58 | +
|
| 59 | +- `Android` archive (.aar file) for `Main` builds is located under the `bundle-android-aar` folder. |
| 60 | +- `Android` archive (.aar file) for `LTS` builds is located under the `bundle-android-aar-lts` folder. |
| 61 | +
|
| 62 | +### 3. Using |
| 63 | +
|
| 64 | +#### 3.1 Android API |
| 65 | +
|
| 66 | +1. Declare `mavenCentral` repository and add `FFmpegKit` dependency to your `build.gradle` in |
| 67 | + `ffmpeg-kit-<package name>` pattern. Use one of the `FFmpegKit` package names given in the |
| 68 | + project [README](https://github.com/tanersener/ffmpeg-kit). |
| 69 | +
|
| 70 | + ``` |
| 71 | + repositories { |
| 72 | + mavenCentral() |
| 73 | + } |
| 74 | +
|
| 75 | + dependencies { |
| 76 | + implementation 'com.arthenica:ffmpeg-kit-full:4.4.LTS' |
| 77 | + } |
| 78 | + ``` |
| 79 | +
|
| 80 | +2. Execute synchronous FFmpeg commands. |
| 81 | +
|
| 82 | + ``` |
| 83 | + import com.arthenica.ffmpegkit.FFmpegKit; |
| 84 | + import com.arthenica.ffmpegkit.ReturnCode; |
| 85 | +
|
| 86 | + FFmpegSession session = FFmpegKit.execute("-i file1.mp4 -c:v mpeg4 file2.mp4"); |
| 87 | + if (ReturnCode.isSuccess(session.getReturnCode())) { |
| 88 | + // SUCCESS |
| 89 | + } else if (ReturnCode.isCancel(session.getReturnCode())) { |
| 90 | + // CANCEL |
| 91 | + } else { |
| 92 | + // FAILURE |
| 93 | + Log.d(TAG, String.format("Command failed with state %s and rc %s.%s", session.getState(), session.getReturnCode(), session.getFailStackTrace())); |
| 94 | + } |
| 95 | + ``` |
| 96 | +
|
| 97 | +3. Execute asynchronous FFmpeg commands by providing session specific execute/log/session callbacks. |
| 98 | +
|
| 99 | + ``` |
| 100 | + FFmpegKit.executeAsync("-i file1.mp4 -c:v mpeg4 file2.mp4", new ExecuteCallback() { |
| 101 | +
|
| 102 | + @Override |
| 103 | + public void apply(Session session) { |
| 104 | + SessionState state = session.getState(); |
| 105 | + ReturnCode returnCode = session.getReturnCode(); |
| 106 | +
|
| 107 | + // CALLED WHEN SESSION IS EXECUTED |
| 108 | +
|
| 109 | + Log.d(TAG, String.format("FFmpeg process exited with state %s and rc %s.%s", state, returnCode, session.getFailStackTrace())); |
| 110 | + } |
| 111 | + }, new LogCallback() { |
| 112 | +
|
| 113 | + @Override |
| 114 | + public void apply(com.arthenica.ffmpegkit.Log log) { |
| 115 | +
|
| 116 | + // CALLED WHEN SESSION PRINTS LOGS |
| 117 | +
|
| 118 | + } |
| 119 | + }, new StatisticsCallback() { |
| 120 | +
|
| 121 | + @Override |
| 122 | + public void apply(Statistics statistics) { |
| 123 | +
|
| 124 | + // CALLED WHEN SESSION GENERATES STATISTICS |
| 125 | +
|
| 126 | + } |
| 127 | + }); |
| 128 | + ``` |
| 129 | +
|
| 130 | +4. Execute synchronous FFprobe commands. |
| 131 | +
|
| 132 | + ``` |
| 133 | + FFprobeSession session = FFprobeKit.execute(ffprobeCommand); |
| 134 | +
|
| 135 | + if (!ReturnCode.isSuccess(session.getReturnCode())) { |
| 136 | + Log.d(TAG, "Command failed. Please check output for the details."); |
| 137 | + } |
| 138 | + ``` |
| 139 | +
|
| 140 | +5. Get session output. |
| 141 | +
|
| 142 | + ``` |
| 143 | + Session session = FFmpegKit.execute("-i file1.mp4 -c:v mpeg4 file2.mp4"); |
| 144 | + Log.d(TAG, session.getOutput()); |
| 145 | + ``` |
| 146 | +
|
| 147 | +6. Stop ongoing FFmpeg operations. |
| 148 | +
|
| 149 | + - Stop all executions |
| 150 | + ``` |
| 151 | + FFmpegKit.cancel(); |
| 152 | + ``` |
| 153 | + - Stop a specific session |
| 154 | + ``` |
| 155 | + FFmpegKit.cancel(sessionId); |
| 156 | + ``` |
| 157 | +
|
| 158 | +7. Get media information for a file. |
| 159 | +
|
| 160 | + ``` |
| 161 | + MediaInformationSession mediaInformation = FFprobeKit.getMediaInformation("<file path or uri>"); |
| 162 | + mediaInformation.getMediaInformation(); |
| 163 | + ``` |
| 164 | +
|
| 165 | +8. List previous FFmpeg sessions. |
| 166 | +
|
| 167 | + ``` |
| 168 | + List<FFmpegSession> ffmpegSessions = FFmpegKit.listSessions(); |
| 169 | + for (int i = 0; i < ffmpegSessions.size(); i++) { |
| 170 | + FFmpegSession session = ffmpegSessions.get(i); |
| 171 | + Log.d(TAG, String.format("Session %d = id:%d, startTime:%s, duration:%s, state:%s, returnCode:%s.", |
| 172 | + i, |
| 173 | + session.getSessionId(), |
| 174 | + session.getStartTime(), |
| 175 | + session.getDuration(), |
| 176 | + session.getState(), |
| 177 | + session.getReturnCode())); |
| 178 | + } |
| 179 | + ``` |
| 180 | +
|
| 181 | +### 4. Test Application |
| 182 | +
|
| 183 | +You can see how `FFmpegKit` is used inside an application by running test applications developed under the |
| 184 | +[FFmpegKit Test](https://github.com/tanersener/ffmpeg-kit-test) project. |
0 commit comments