README.md
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