1# ExoPlayer VP9 module
2
3The VP9 module provides `LibvpxVideoRenderer`, which uses libvpx (the VPx
4decoding library) to decode VP9 video.
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 build the module's native components as follows:
21
22* Set the following environment variables:
23
24```
25cd "<path to project checkout>"
26VP9_MODULE_PATH="$(pwd)/extensions/vp9/src/main"
27```
28
29* Download the [Android NDK][] and set its location in an environment variable.
30  This build configuration has been tested on NDK r21.
31
32```
33NDK_PATH="<path to Android NDK>"
34```
35
36* Fetch an appropriate branch of libvpx. We cannot guarantee compatibility
37  with all versions of libvpx. We currently recommend version 1.8.0:
38
39```
40cd "<preferred location for libvpx>" && \
41git clone https://chromium.googlesource.com/webm/libvpx && \
42cd libvpx && \
43git checkout tags/v1.8.0 -b v1.8.0 && \
44LIBVPX_PATH="$(pwd)"
45```
46
47*   Add a link to the libvpx source code in the vp9 module `jni` directory and
48    run a script that generates necessary configuration files for libvpx:
49
50```
51cd ${VP9_MODULE_PATH}/jni && \
52ln -s "$LIBVPX_PATH" libvpx && \
53./generate_libvpx_android_configs.sh
54```
55
56* Build the JNI native libraries from the command line:
57
58```
59cd "${VP9_MODULE_PATH}"/jni && \
60${NDK_PATH}/ndk-build APP_ABI=all -j4
61```
62
63[top level README]: https://github.com/google/ExoPlayer/blob/release-v2/README.md
64[Android NDK]: https://developer.android.com/tools/sdk/ndk/index.html
65
66## Build instructions (Windows)
67
68We do not provide support for building this module on Windows, however it should
69be possible to follow the Linux instructions in [Windows PowerShell][].
70
71[Windows PowerShell]: https://docs.microsoft.com/en-us/powershell/scripting/getting-started/getting-started-with-windows-powershell
72
73## Notes
74
75* Every time there is a change to the libvpx checkout:
76  * Android config scripts should be re-generated by running
77    `generate_libvpx_android_configs.sh`
78  * Clean and re-build the project.
79* If you want to use your own version of libvpx, point to it with the
80  `${VP9_MODULE_PATH}/jni/libvpx` symlink. Please note that
81  `generate_libvpx_android_configs.sh` and the makefiles may need to be modified
82  to work with arbitrary versions of libvpx.
83
84## Using the module
85
86Once you've followed the instructions above to check out, build and depend on
87the module, the next step is to tell ExoPlayer to use `LibvpxVideoRenderer`.
88How you do this depends on which player API you're using:
89
90*   If you're passing a `DefaultRenderersFactory` to `ExoPlayer.Builder`, you
91    can enable using the module by setting the `extensionRendererMode` parameter
92    of the `DefaultRenderersFactory` constructor to
93    `EXTENSION_RENDERER_MODE_ON`. This will use `LibvpxVideoRenderer` for
94    playback if `MediaCodecVideoRenderer` doesn't support decoding the input VP9
95    stream. Pass `EXTENSION_RENDERER_MODE_PREFER` to give `LibvpxVideoRenderer`
96    priority over `MediaCodecVideoRenderer`.
97*   If you've subclassed `DefaultRenderersFactory`, add a `LibvpxVideoRenderer`
98    to the output list in `buildVideoRenderers`. ExoPlayer will use the first
99    `Renderer` in the list that supports the input media format.
100*   If you've implemented your own `RenderersFactory`, return a
101    `LibvpxVideoRenderer` instance from `createRenderers`. ExoPlayer will use
102    the first `Renderer` in the returned array that supports the input media
103    format.
104*   If you're using `ExoPlayer.Builder`, pass a `LibvpxVideoRenderer` in the
105    array of `Renderer`s. ExoPlayer will use the first `Renderer` in the list
106    that supports the input media format.
107
108Note: These instructions assume you're using `DefaultTrackSelector`. If you have
109a custom track selector the choice of `Renderer` is up to your implementation,
110so you need to make sure you are passing an `LibvpxVideoRenderer` to the
111player, then implement your own logic to use the renderer for a given track.
112
113## Using the module in the demo application
114
115To try out playback using the module in the [demo application][], see
116[enabling extension decoders][].
117
118[demo application]: https://exoplayer.dev/demo-application.html
119[enabling extension decoders]: https://exoplayer.dev/demo-application.html#enabling-extension-decoders
120
121## Rendering options
122
123There are two possibilities for rendering the output `LibvpxVideoRenderer`
124gets from the libvpx decoder:
125
126*   GL rendering using GL shader for color space conversion
127
128    *   If you are using `ExoPlayer` with `PlayerView` or
129        `StyledPlayerView`, enable this option by setting `surface_type` of view
130        to be `video_decoder_gl_surface_view`.
131    *   Otherwise, enable this option by sending `LibvpxVideoRenderer` a message
132        of type `Renderer.MSG_SET_VIDEO_OUTPUT` with an instance of
133        `VideoDecoderOutputBufferRenderer` as its object.
134        `VideoDecoderGLSurfaceView` is the concrete
135        `VideoDecoderOutputBufferRenderer` implementation used by
136        `PlayerView` and `StyledPlayerView`.
137
138*   Native rendering using `ANativeWindow`
139
140    *   If you are using `ExoPlayer` with `PlayerView` or
141        `StyledPlayerView`, this option is enabled by default.
142    *   Otherwise, enable this option by sending `LibvpxVideoRenderer` a message
143        of type `Renderer.MSG_SET_VIDEO_OUTPUT` with an instance of
144        `SurfaceView` as its object.
145
146Note: Although the default option uses `ANativeWindow`, based on our testing the
147GL rendering mode has better performance, so should be preferred.
148
149## Links
150
151*   [Javadoc][]
152
153[Javadoc]: https://exoplayer.dev/doc/reference/index.html
154