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