1# ExoPlayer FFmpeg module
2
3The FFmpeg module provides `FfmpegAudioRenderer`, which uses FFmpeg for decoding
4and 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 module 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 the module you need to clone this GitHub project and depend on its
17modules locally. Instructions for doing this can be found in the
18[top level README][]. The module is not provided via Google's Maven repository
19(see [#2781][] for more information).
20
21In addition, it's necessary to manually build the FFmpeg library, so that gradle
22can bundle the FFmpeg binaries in the APK:
23
24* Set the following shell variable:
25
26```
27cd "<path to project checkout>"
28FFMPEG_MODULE_PATH="$(pwd)/extensions/ffmpeg/src/main"
29```
30
31* Download the [Android NDK][] and set its location in a shell variable.
32  This build configuration has been tested on NDK r21.
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* Fetch FFmpeg and checkout an appropriate branch. We cannot guarantee
45  compatibility with all versions of FFmpeg. We currently recommend version 4.2:
46
47```
48cd "<preferred location for ffmpeg>" && \
49git clone git://source.ffmpeg.org/ffmpeg && \
50cd ffmpeg && \
51git checkout release/4.2 && \
52FFMPEG_PATH="$(pwd)"
53```
54
55* Configure the decoders to include. See the [Supported formats][] page for
56  details of the available decoders, and which formats they support.
57
58```
59ENABLED_DECODERS=(vorbis opus flac)
60```
61
62*   Add a link to the FFmpeg source code in the FFmpeg module `jni` directory.
63
64```
65cd "${FFMPEG_MODULE_PATH}/jni" && \
66ln -s "$FFMPEG_PATH" ffmpeg
67```
68
69* Execute `build_ffmpeg.sh` to build FFmpeg for `armeabi-v7a`, `arm64-v8a`,
70  `x86` and `x86_64`. The script can be edited if you need to build for
71  different architectures:
72
73```
74cd "${FFMPEG_MODULE_PATH}/jni" && \
75./build_ffmpeg.sh \
76  "${FFMPEG_MODULE_PATH}" "${NDK_PATH}" "${HOST_PLATFORM}" "${ENABLED_DECODERS[@]}"
77```
78
79## Build instructions (Windows)
80
81We do not provide support for building this module on Windows, however it should
82be possible to follow the Linux instructions in [Windows PowerShell][].
83
84[Windows PowerShell]: https://docs.microsoft.com/en-us/powershell/scripting/getting-started/getting-started-with-windows-powershell
85
86## Using the module
87
88Once you've followed the instructions above to check out, build and depend on
89the module, the next step is to tell ExoPlayer to use `FfmpegAudioRenderer`. How
90you do this depends on which player API you're using:
91
92*   If you're passing a `DefaultRenderersFactory` to `ExoPlayer.Builder`, you
93    can enable using the module by setting the `extensionRendererMode` parameter
94    of the `DefaultRenderersFactory` constructor to
95    `EXTENSION_RENDERER_MODE_ON`. This will use `FfmpegAudioRenderer` for
96    playback if `MediaCodecAudioRenderer` doesn't support the input format. Pass
97    `EXTENSION_RENDERER_MODE_PREFER` to give `FfmpegAudioRenderer` priority over
98    `MediaCodecAudioRenderer`.
99*   If you've subclassed `DefaultRenderersFactory`, add an `FfmpegAudioRenderer`
100    to the output list in `buildAudioRenderers`. ExoPlayer will use the first
101    `Renderer` in the list that supports the input media format.
102*   If you've implemented your own `RenderersFactory`, return an
103    `FfmpegAudioRenderer` instance from `createRenderers`. ExoPlayer will use
104    the first `Renderer` in the returned array that supports the input media
105    format.
106*   If you're using `ExoPlayer.Builder`, pass an `FfmpegAudioRenderer` in the
107    array of `Renderer`s. ExoPlayer will use the first `Renderer` in the list
108    that supports the input media format.
109
110Note: These instructions assume you're using `DefaultTrackSelector`. If you have
111a custom track selector the choice of `Renderer` is up to your implementation,
112so you need to make sure you are passing an `FfmpegAudioRenderer` to the player,
113then implement your own logic to use the renderer for a given track.
114
115[top level README]: https://github.com/google/ExoPlayer/blob/release-v2/README.md
116[Android NDK]: https://developer.android.com/tools/sdk/ndk/index.html
117[#2781]: https://github.com/google/ExoPlayer/issues/2781
118[Supported formats]: https://exoplayer.dev/supported-formats.html#ffmpeg-extension
119
120## Using the module in the demo application
121
122To try out playback using the module in the [demo application][], see
123[enabling extension decoders][].
124
125[demo application]: https://exoplayer.dev/demo-application.html
126[enabling extension decoders]: https://exoplayer.dev/demo-application.html#enabling-extension-decoders
127
128## Links
129
130* [Troubleshooting using extensions][]
131* [Javadoc][]
132
133[Troubleshooting using extensions]: https://exoplayer.dev/troubleshooting.html#how-can-i-get-a-decoding-extension-to-load-and-be-used-for-playback
134[Javadoc]: https://exoplayer.dev/doc/reference/index.html
135