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