1# ExoPlayer AV1 extension # 2 3The AV1 extension provides `Libgav1VideoRenderer`, which uses libgav1 native 4library to decode AV1 videos. 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 fetch cpu_features library and libgav1 with its 21dependencies as follows: 22 23* Set the following environment variables: 24 25``` 26cd "<path to exoplayer checkout>" 27EXOPLAYER_ROOT="$(pwd)" 28AV1_EXT_PATH="${EXOPLAYER_ROOT}/extensions/av1/src/main" 29``` 30 31* Fetch cpu_features library: 32 33``` 34cd "${AV1_EXT_PATH}/jni" && \ 35git clone https://github.com/google/cpu_features 36``` 37 38* Fetch libgav1: 39 40``` 41cd "${AV1_EXT_PATH}/jni" && \ 42git clone https://chromium.googlesource.com/codecs/libgav1 libgav1 43``` 44 45* Fetch Abseil: 46 47``` 48cd "${AV1_EXT_PATH}/jni/libgav1" && \ 49git clone https://github.com/abseil/abseil-cpp.git third_party/abseil-cpp 50``` 51 52* [Install CMake][]. 53 54Having followed these steps, gradle will build the extension automatically when 55run on the command line or via Android Studio, using [CMake][] and [Ninja][] 56to configure and build libgav1 and the extension's [JNI wrapper library][]. 57 58[top level README]: https://github.com/google/ExoPlayer/blob/release-v2/README.md 59[Install CMake]: https://developer.android.com/studio/projects/install-ndk 60[CMake]: https://cmake.org/ 61[Ninja]: https://ninja-build.org 62[JNI wrapper library]: https://github.com/google/ExoPlayer/blob/release-v2/extensions/av1/src/main/jni/gav1_jni.cc 63 64## Build instructions (Windows) ## 65 66We do not provide support for building this extension on Windows, however it 67should be possible to follow the Linux instructions in [Windows PowerShell][]. 68 69[Windows PowerShell]: https://docs.microsoft.com/en-us/powershell/scripting/getting-started/getting-started-with-windows-powershell 70 71## Using the extension ## 72 73Once you've followed the instructions above to check out, build and depend on 74the extension, the next step is to tell ExoPlayer to use `Libgav1VideoRenderer`. 75How you do this depends on which player API you're using: 76 77* If you're passing a `DefaultRenderersFactory` to `SimpleExoPlayer.Builder`, 78 you can enable using the extension by setting the `extensionRendererMode` 79 parameter of the `DefaultRenderersFactory` constructor to 80 `EXTENSION_RENDERER_MODE_ON`. This will use `Libgav1VideoRenderer` for 81 playback if `MediaCodecVideoRenderer` doesn't support decoding the input AV1 82 stream. Pass `EXTENSION_RENDERER_MODE_PREFER` to give `Libgav1VideoRenderer` 83 priority over `MediaCodecVideoRenderer`. 84* If you've subclassed `DefaultRenderersFactory`, add a `Libvgav1VideoRenderer` 85 to the output list in `buildVideoRenderers`. ExoPlayer will use the first 86 `Renderer` in the list that supports the input media format. 87* If you've implemented your own `RenderersFactory`, return a 88 `Libgav1VideoRenderer` instance from `createRenderers`. ExoPlayer will use the 89 first `Renderer` in the returned array that supports the input media format. 90* If you're using `ExoPlayer.Builder`, pass a `Libgav1VideoRenderer` in the 91 array of `Renderer`s. ExoPlayer will use the first `Renderer` in the list that 92 supports the input media format. 93 94Note: These instructions assume you're using `DefaultTrackSelector`. If you have 95a custom track selector the choice of `Renderer` is up to your implementation. 96You need to make sure you are passing a `Libgav1VideoRenderer` to the player and 97then you need to implement your own logic to use the renderer for a given track. 98 99## Using the extension in the demo application ## 100 101To try out playback using the extension in the [demo application][], see 102[enabling extension decoders][]. 103 104[demo application]: https://exoplayer.dev/demo-application.html 105[enabling extension decoders]: https://exoplayer.dev/demo-application.html#enabling-extension-decoders 106 107## Rendering options ## 108 109There are two possibilities for rendering the output `Libgav1VideoRenderer` 110gets from the libgav1 decoder: 111 112* GL rendering using GL shader for color space conversion 113 * If you are using `SimpleExoPlayer` with `PlayerView`, enable this option by 114 setting `surface_type` of `PlayerView` to be 115 `video_decoder_gl_surface_view`. 116 * Otherwise, enable this option by sending `Libgav1VideoRenderer` a message 117 of type `C.MSG_SET_VIDEO_DECODER_OUTPUT_BUFFER_RENDERER` with an instance of 118 `VideoDecoderOutputBufferRenderer` as its object. 119 120* Native rendering using `ANativeWindow` 121 * If you are using `SimpleExoPlayer` with `PlayerView`, this option is enabled 122 by default. 123 * Otherwise, enable this option by sending `Libgav1VideoRenderer` a message of 124 type `C.MSG_SET_SURFACE` with an instance of `SurfaceView` as its object. 125 126Note: Although the default option uses `ANativeWindow`, based on our testing the 127GL rendering mode has better performance, so should be preferred 128 129## Links ## 130 131* [Javadoc][]: Classes matching `com.google.android.exoplayer2.ext.av1.*` 132 belong to this module. 133 134[Javadoc]: https://exoplayer.dev/doc/reference/index.html 135