media3/extensions/vp9/README.md

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.

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:

cd "${VP9_EXT_PATH}/jni" && \
git clone https://chromium.googlesource.com/webm/libvpx libvpx

• Checkout the appropriate branch of libvpx (the scripts and makefiles bundled in this repo are known to work only at specific versions of the library - we will update this periodically as newer versions of libvpx are released):

cd "${VP9_EXT_PATH}/jni/libvpx" && \
git checkout tags/v1.8.0 -b v1.8.0

• 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

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, place it in ${VP9_EXT_PATH}/jni/libvpx. Please note that generate_libvpx_android_configs.sh and the makefiles may need to be modified to work with arbitrary versions of libvpx.

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 Renderers. 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.