1# ExoPlayer Opus extension # 2 3The Opus extension 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 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][]. 19 20In addition, it's necessary to build the extension's native components as 21follows: 22 23* Set the following environment variables: 24 25``` 26cd "<path to exoplayer checkout>" 27EXOPLAYER_ROOT="$(pwd)" 28OPUS_EXT_PATH="${EXOPLAYER_ROOT}/extensions/opus/src/main" 29``` 30 31* Download the [Android NDK][] and set its location in an environment variable. 32 This build configuration has been tested on NDK r20. 33 34``` 35NDK_PATH="<path to Android NDK>" 36``` 37 38* Fetch libopus: 39 40``` 41cd "${OPUS_EXT_PATH}/jni" && \ 42git clone https://git.xiph.org/opus.git libopus 43``` 44 45* Run the script to convert arm assembly to NDK compatible format: 46 47``` 48cd ${OPUS_EXT_PATH}/jni && ./convert_android_asm.sh 49``` 50 51* Build the JNI native libraries from the command line: 52 53``` 54cd "${OPUS_EXT_PATH}"/jni && \ 55${NDK_PATH}/ndk-build APP_ABI=all -j4 56``` 57 58[top level README]: https://github.com/google/ExoPlayer/blob/release-v2/README.md 59[Android NDK]: https://developer.android.com/tools/sdk/ndk/index.html 60 61## Build instructions (Windows) ## 62 63We do not provide support for building this extension on Windows, however it 64should be possible to follow the Linux instructions in [Windows PowerShell][]. 65 66[Windows PowerShell]: https://docs.microsoft.com/en-us/powershell/scripting/getting-started/getting-started-with-windows-powershell 67 68## Notes ## 69 70* Every time there is a change to the libopus checkout: 71 * Arm assembly should be converted by running `convert_android_asm.sh` 72 * Clean and re-build the project. 73* If you want to use your own version of libopus, place it in 74 `${OPUS_EXT_PATH}/jni/libopus`. 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 `LibopusAudioRenderer`. 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 `LibopusAudioRenderer` for 86 playback if `MediaCodecAudioRenderer` doesn't support the input format. Pass 87 `EXTENSION_RENDERER_MODE_PREFER` to give `LibopusAudioRenderer` priority over 88 `MediaCodecAudioRenderer`. 89* If you've subclassed `DefaultRenderersFactory`, add a `LibopusAudioRenderer` 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 a 93 `LibopusAudioRenderer` 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 a `LibopusAudioRenderer` 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 `LibopusAudioRenderer` to the 102player, then implement your own logic to use the renderer for a given track. 103 104## Using the extension in the demo application ## 105 106To try out playback using the extension in the [demo application][], see 107[enabling extension decoders][]. 108 109[demo application]: https://exoplayer.dev/demo-application.html 110[enabling extension decoders]: https://exoplayer.dev/demo-application.html#enabling-extension-decoders 111 112## Links ## 113 114* [Javadoc][]: Classes matching `com.google.android.exoplayer2.ext.opus.*` 115 belong to this module. 116 117[Javadoc]: https://exoplayer.dev/doc/reference/index.html 118