127 lines
4.8 KiB
Markdown
127 lines
4.8 KiB
Markdown
# ExoPlayer VP9 extension #
|
|
|
|
The VP9 extension provides `LibvpxVideoRenderer`, which uses libvpx (the VPx
|
|
decoding library) to decode VP9 video.
|
|
|
|
## License note ##
|
|
|
|
Please note that whilst the code in this repository is licensed under
|
|
[Apache 2.0][], using this extension also requires building and including one or
|
|
more external libraries as described below. These are licensed separately.
|
|
|
|
[Apache 2.0]: https://github.com/google/ExoPlayer/blob/release-v2/LICENSE
|
|
|
|
## Build instructions ##
|
|
|
|
To use this extension you need to clone the ExoPlayer repository and depend on
|
|
its modules locally. Instructions for doing this can be found in ExoPlayer's
|
|
[top level README][].
|
|
|
|
In addition, it's necessary to build the extension's native components as
|
|
follows:
|
|
|
|
* Set the following environment variables:
|
|
|
|
```
|
|
cd "<path to exoplayer checkout>"
|
|
EXOPLAYER_ROOT="$(pwd)"
|
|
VP9_EXT_PATH="${EXOPLAYER_ROOT}/extensions/vp9/src/main"
|
|
```
|
|
|
|
* Download the [Android NDK][] and set its location in an environment variable.
|
|
|
|
```
|
|
NDK_PATH="<path to Android NDK>"
|
|
```
|
|
|
|
* Fetch libvpx and libyuv:
|
|
|
|
```
|
|
cd "${VP9_EXT_PATH}/jni" && \
|
|
git clone https://chromium.googlesource.com/webm/libvpx libvpx && \
|
|
git clone https://chromium.googlesource.com/libyuv/libyuv libyuv
|
|
```
|
|
|
|
* Checkout the appropriate branches of libvpx and libyuv (the scripts and
|
|
makefiles bundled in this repo are known to work only at these versions of the
|
|
libraries - we will update this periodically as newer versions of
|
|
libvpx/libyuv are released):
|
|
|
|
```
|
|
cd "${VP9_EXT_PATH}/jni/libvpx" && \
|
|
git checkout tags/v1.6.1 -b v1.6.1 && \
|
|
cd "${VP9_EXT_PATH}/jni/libyuv" && \
|
|
git checkout 996a2bbd
|
|
```
|
|
|
|
* Run a script that generates necessary configuration files for libvpx:
|
|
|
|
```
|
|
cd ${VP9_EXT_PATH}/jni && \
|
|
./generate_libvpx_android_configs.sh "${NDK_PATH}"
|
|
```
|
|
|
|
* Build the JNI native libraries from the command line:
|
|
|
|
```
|
|
cd "${VP9_EXT_PATH}"/jni && \
|
|
${NDK_PATH}/ndk-build APP_ABI=all -j4
|
|
```
|
|
|
|
[top level README]: https://github.com/google/ExoPlayer/blob/release-v2/README.md
|
|
[Android NDK]: https://developer.android.com/tools/sdk/ndk/index.html
|
|
[#3520]: https://github.com/google/ExoPlayer/issues/3520
|
|
|
|
## Notes ##
|
|
|
|
* Every time there is a change to the libvpx checkout:
|
|
* Android config scripts should be re-generated by running
|
|
`generate_libvpx_android_configs.sh`
|
|
* Clean and re-build the project.
|
|
* If you want to use your own version of libvpx or libyuv, place it in
|
|
`${VP9_EXT_PATH}/jni/libvpx` or `${VP9_EXT_PATH}/jni/libyuv` respectively. But
|
|
please note that `generate_libvpx_android_configs.sh` and the makefiles need
|
|
to be modified to work with arbitrary versions of libvpx and libyuv.
|
|
|
|
## Using the extension ##
|
|
|
|
Once you've followed the instructions above to check out, build and depend on
|
|
the extension, the next step is to tell ExoPlayer to use `LibvpxVideoRenderer`.
|
|
How you do this depends on which player API you're using:
|
|
|
|
* If you're passing a `DefaultRenderersFactory` to
|
|
`ExoPlayerFactory.newSimpleInstance`, you can enable using the extension by
|
|
setting the `extensionRendererMode` parameter of the `DefaultRenderersFactory`
|
|
constructor to `EXTENSION_RENDERER_MODE_ON`. This will use
|
|
`LibvpxVideoRenderer` for playback if `MediaCodecVideoRenderer` doesn't
|
|
support decoding the input VP9 stream. Pass `EXTENSION_RENDERER_MODE_PREFER`
|
|
to give `LibvpxVideoRenderer` priority over `MediaCodecVideoRenderer`.
|
|
* If you've subclassed `DefaultRenderersFactory`, add a `LibvpxVideoRenderer`
|
|
to the output list in `buildVideoRenderers`. ExoPlayer will use the first
|
|
`Renderer` in the list that supports the input media format.
|
|
* If you've implemented your own `RenderersFactory`, return a
|
|
`LibvpxVideoRenderer` instance from `createRenderers`. ExoPlayer will use the
|
|
first `Renderer` in the returned array that supports the input media format.
|
|
* If you're using `ExoPlayerFactory.newInstance`, pass a `LibvpxVideoRenderer`
|
|
in the array of `Renderer`s. ExoPlayer will use the first `Renderer` in the
|
|
list that supports the input media format.
|
|
|
|
Note: These instructions assume you're using `DefaultTrackSelector`. If you have
|
|
a custom track selector the choice of `Renderer` is up to your implementation,
|
|
so you need to make sure you are passing an `LibvpxVideoRenderer` to the
|
|
player, then implement your own logic to use the renderer for a given track.
|
|
|
|
`LibvpxVideoRenderer` can optionally output to a `VpxVideoSurfaceView` when not
|
|
being used via `SimpleExoPlayer`, in which case color space conversion will be
|
|
performed using a GL shader. To enable this mode, send the renderer a message of
|
|
type `LibvpxVideoRenderer.MSG_SET_OUTPUT_BUFFER_RENDERER` with the
|
|
`VpxVideoSurfaceView` as its object, instead of sending `MSG_SET_SURFACE` with a
|
|
`Surface`.
|
|
|
|
## Links ##
|
|
|
|
* [Javadoc][]: Classes matching `com.google.android.exoplayer2.ext.vp9.*`
|
|
belong to this module.
|
|
|
|
[Javadoc]: https://google.github.io/ExoPlayer/doc/reference/index.html
|