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