README.md
1# ExoPlayer FFmpeg extension #
2
3The FFmpeg extension provides `FfmpegAudioRenderer`, which uses FFmpeg for
4decoding and can render audio encoded in a variety of formats.
5
6## License note ##
7
8Please note that whilst the code in this repository is licensed under
9[Apache 2.0][], using this extension also requires building and including one or
10more external libraries as described below. These are licensed separately.
11
12[Apache 2.0]: https://github.com/google/ExoPlayer/blob/release-v2/LICENSE
13
14## Build instructions (Linux, macOS) ##
15
16To use this extension you need to clone the ExoPlayer repository and depend on
17its modules locally. Instructions for doing this can be found in ExoPlayer's
18[top level README][]. The extension is not provided via JCenter (see [#2781][]
19for more information).
20
21In addition, it's necessary to build the extension's native components as
22follows:
23
24* Set the following shell variable:
25
26```
27cd "<path to exoplayer checkout>"
28FFMPEG_EXT_PATH="$(pwd)/extensions/ffmpeg/src/main/jni"
29```
30
31* Download the [Android NDK][] and set its location in a shell variable.
32 This build configuration has been tested on NDK r20.
33
34```
35NDK_PATH="<path to Android NDK>"
36```
37
38* Set the host platform (use "darwin-x86_64" for Mac OS X):
39
40```
41HOST_PLATFORM="linux-x86_64"
42```
43
44* Configure the decoders to include. See the [Supported formats][] page for
45 details of the available decoders, and which formats they support.
46
47```
48ENABLED_DECODERS=(vorbis opus flac)
49```
50
51* Fetch and build FFmpeg. Executing `build_ffmpeg.sh` will fetch and build
52 FFmpeg 4.2 for `armeabi-v7a`, `arm64-v8a`, `x86` and `x86_64`. The script can
53 be edited if you need to build for different architectures.
54
55```
56cd "${FFMPEG_EXT_PATH}" && \
57./build_ffmpeg.sh \
58 "${FFMPEG_EXT_PATH}" "${NDK_PATH}" "${HOST_PLATFORM}" "${ENABLED_DECODERS[@]}"
59```
60
61* Build the JNI native libraries, setting `APP_ABI` to include the architectures
62 built in the previous step. For example:
63
64```
65cd "${FFMPEG_EXT_PATH}" && \
66${NDK_PATH}/ndk-build APP_ABI="armeabi-v7a arm64-v8a x86 x86_64" -j4
67```
68
69## Build instructions (Windows) ##
70
71We do not provide support for building this extension on Windows, however it
72should be possible to follow the Linux instructions in [Windows PowerShell][].
73
74[Windows PowerShell]: https://docs.microsoft.com/en-us/powershell/scripting/getting-started/getting-started-with-windows-powershell
75
76## Using the extension ##
77
78Once you've followed the instructions above to check out, build and depend on
79the extension, the next step is to tell ExoPlayer to use `FfmpegAudioRenderer`.
80How you do this depends on which player API you're using:
81
82* If you're passing a `DefaultRenderersFactory` to `SimpleExoPlayer.Builder`,
83 you can enable using the extension by setting the `extensionRendererMode`
84 parameter of the `DefaultRenderersFactory` constructor to
85 `EXTENSION_RENDERER_MODE_ON`. This will use `FfmpegAudioRenderer` for playback
86 if `MediaCodecAudioRenderer` doesn't support the input format. Pass
87 `EXTENSION_RENDERER_MODE_PREFER` to give `FfmpegAudioRenderer` priority over
88 `MediaCodecAudioRenderer`.
89* If you've subclassed `DefaultRenderersFactory`, add an `FfmpegAudioRenderer`
90 to the output list in `buildAudioRenderers`. ExoPlayer will use the first
91 `Renderer` in the list that supports the input media format.
92* If you've implemented your own `RenderersFactory`, return an
93 `FfmpegAudioRenderer` instance from `createRenderers`. ExoPlayer will use the
94 first `Renderer` in the returned array that supports the input media format.
95* If you're using `ExoPlayer.Builder`, pass an `FfmpegAudioRenderer` in the
96 array of `Renderer`s. ExoPlayer will use the first `Renderer` in the list that
97 supports the input media format.
98
99Note: These instructions assume you're using `DefaultTrackSelector`. If you have
100a custom track selector the choice of `Renderer` is up to your implementation,
101so you need to make sure you are passing an `FfmpegAudioRenderer` to the player,
102then implement your own logic to use the renderer for a given track.
103
104[top level README]: https://github.com/google/ExoPlayer/blob/release-v2/README.md
105[Android NDK]: https://developer.android.com/tools/sdk/ndk/index.html
106[#2781]: https://github.com/google/ExoPlayer/issues/2781
107[Supported formats]: https://exoplayer.dev/supported-formats.html#ffmpeg-extension
108
109## Using the extension in the demo application ##
110
111To try out playback using the extension in the [demo application][], see
112[enabling extension decoders][].
113
114[demo application]: https://exoplayer.dev/demo-application.html
115[enabling extension decoders]: https://exoplayer.dev/demo-application.html#enabling-extension-decoders
116
117## Links ##
118
119* [Troubleshooting using extensions][]
120* [Javadoc][]: Classes matching `com.google.android.exoplayer2.ext.ffmpeg.*`
121 belong to this module.
122
123[Troubleshooting using extensions]: https://exoplayer.dev/troubleshooting.html#how-can-i-get-a-decoding-extension-to-load-and-be-used-for-playback
124[Javadoc]: https://exoplayer.dev/doc/reference/index.html
125