1# ExoPlayer Opus module
2
3The Opus module provides `LibopusAudioRenderer`, which uses libopus (the Opus
4decoding library) to decode Opus audio.
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][].
19
20In addition, it's necessary to build the module's native components as follows:
21
22* Set the following environment variables:
23
24```
25cd "<path to project checkout>"
26OPUS_MODULE_PATH="$(pwd)/extensions/opus/src/main"
27```
28
29* Download the [Android NDK][] and set its location in an environment variable.
30  This build configuration has been tested on NDK r21.
31
32```
33NDK_PATH="<path to Android NDK>"
34```
35
36* Fetch libopus:
37
38```
39cd "${OPUS_MODULE_PATH}/jni" && \
40git clone https://gitlab.xiph.org/xiph/opus.git libopus
41```
42
43* Run the script to convert arm assembly to NDK compatible format:
44
45```
46cd ${OPUS_MODULE_PATH}/jni && ./convert_android_asm.sh
47```
48
49* Build the JNI native libraries from the command line:
50
51```
52cd "${OPUS_MODULE_PATH}"/jni && \
53${NDK_PATH}/ndk-build APP_ABI=all -j4
54```
55
56[top level README]: https://github.com/google/ExoPlayer/blob/release-v2/README.md
57[Android NDK]: https://developer.android.com/tools/sdk/ndk/index.html
58
59## Build instructions (Windows)
60
61We do not provide support for building this module on Windows, however it should
62be possible to follow the Linux instructions in [Windows PowerShell][].
63
64[Windows PowerShell]: https://docs.microsoft.com/en-us/powershell/scripting/getting-started/getting-started-with-windows-powershell
65
66## Notes
67
68* Every time there is a change to the libopus checkout:
69  * Arm assembly should be converted by running `convert_android_asm.sh`
70  * Clean and re-build the project.
71* If you want to use your own version of libopus, place it in
72  `${OPUS_MODULE_PATH}/jni/libopus`.
73
74## Using the module
75
76Once you've followed the instructions above to check out, build and depend on
77the module, the next step is to tell ExoPlayer to use `LibopusAudioRenderer`.
78How you do this depends on which player API you're using:
79
80*   If you're passing a `DefaultRenderersFactory` to `ExoPlayer.Builder`, you
81    can enable using the module by setting the `extensionRendererMode` parameter
82    of the `DefaultRenderersFactory` constructor to
83    `EXTENSION_RENDERER_MODE_ON`. This will use `LibopusAudioRenderer` for
84    playback if `MediaCodecAudioRenderer` doesn't support the input format. Pass
85    `EXTENSION_RENDERER_MODE_PREFER` to give `LibopusAudioRenderer` priority
86    over `MediaCodecAudioRenderer`.
87*   If you've subclassed `DefaultRenderersFactory`, add a `LibopusAudioRenderer`
88    to the output list in `buildAudioRenderers`. ExoPlayer will use the first
89    `Renderer` in the list that supports the input media format.
90*   If you've implemented your own `RenderersFactory`, return a
91    `LibopusAudioRenderer` instance from `createRenderers`. ExoPlayer will use
92    the first `Renderer` in the returned array that supports the input media
93    format.
94*   If you're using `ExoPlayer.Builder`, pass a `LibopusAudioRenderer` in the
95    array of `Renderer`s. ExoPlayer will use the first `Renderer` in the list
96    that supports the input media format.
97
98Note: These instructions assume you're using `DefaultTrackSelector`. If you have
99a custom track selector the choice of `Renderer` is up to your implementation,
100so you need to make sure you are passing an `LibopusAudioRenderer` to the
101player, then implement your own logic to use the renderer for a given track.
102
103## Using the module in the demo application
104
105To try out playback using the module in the [demo application][], see
106[enabling extension decoders][].
107
108[demo application]: https://exoplayer.dev/demo-application.html
109[enabling extension decoders]: https://exoplayer.dev/demo-application.html#enabling-extension-decoders
110
111## Links
112
113* [Javadoc][]
114
115[Javadoc]: https://exoplayer.dev/doc/reference/index.html
116