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