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