From b174bcc173f34b63fde94ca1a1a32ccf0fa7164d Mon Sep 17 00:00:00 2001 From: andrewlewis Date: Thu, 17 Aug 2017 06:40:44 -0700 Subject: [PATCH] Update extension README with usage instructions Issue: #3162 ------------- Created by MOE: https://github.com/google/moe MOE_MIGRATED_REVID=165572088 --- extensions/ffmpeg/README.md | 49 ++++++++++++++++++++++++++++++------ extensions/flac/README.md | 50 +++++++++++++++++++++++++++++++------ extensions/opus/README.md | 41 ++++++++++++++++++++++++------ extensions/vp9/README.md | 48 +++++++++++++++++++++++++++++------ 4 files changed, 160 insertions(+), 28 deletions(-) diff --git a/extensions/ffmpeg/README.md b/extensions/ffmpeg/README.md index b4514effbc..fbc919c36d 100644 --- a/extensions/ffmpeg/README.md +++ b/extensions/ffmpeg/README.md @@ -2,17 +2,18 @@ ## Description ## -The FFmpeg extension is a [Renderer][] implementation that uses FFmpeg to decode -audio. - -[Renderer]: https://google.github.io/ExoPlayer/doc/reference/com/google/android/exoplayer2/Renderer.html +The FFmpeg extension provides `FfmpegAudioRenderer`, which uses FFmpeg for +decoding and can render audio encoded in a variety of formats. ## 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: +[top level README][]. The extension is not provided via JCenter (see [#2781][] +for more information). + +In addition, it's necessary to build the extension's native components as +follows: * Set the following environment variables: @@ -34,7 +35,11 @@ NDK_PATH="" HOST_PLATFORM="linux-x86_64" ``` -* Fetch and build FFmpeg. For example, to fetch and build for armeabi-v7a, +* Fetch and build FFmpeg. The configuration flags determine which formats will + be supported. See the [Supported formats][] page for more details of the + available flags. + +For example, to fetch and build for armeabi-v7a, arm64-v8a and x86 on Linux x86_64: ``` @@ -103,5 +108,35 @@ cd "${FFMPEG_EXT_PATH}"/jni && \ ${NDK_PATH}/ndk-build APP_ABI="armeabi-v7a arm64-v8a x86" -j4 ``` +## 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 `FfmpegAudioRenderer`. +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 + `FfmpegAudioRenderer` for playback if `MediaCodecAudioRenderer` doesn't + support the input format. Pass `EXTENSION_RENDERER_MODE_PREFER` to give + `FfmpegAudioRenderer` priority over `MediaCodecAudioRenderer`. +* If you've subclassed `DefaultRenderersFactory`, add an `FfmpegAudioRenderer` + to the output list in `buildAudioRenderers`. ExoPlayer will use the first + `Renderer` in the list that supports the input media format. +* If you've implemented your own `RenderersFactory`, return an + `FfmpegAudioRenderer` 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 an `FfmpegAudioRenderer` + 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 `FfmpegAudioRenderer` to the player, +then implement your own logic to use the renderer for a given track. + [top level README]: https://github.com/google/ExoPlayer/blob/release-v2/README.md [Android NDK]: https://developer.android.com/tools/sdk/ndk/index.html +[#2781]: https://github.com/google/ExoPlayer/issues/2781 +[Supported formats]: https://google.github.io/ExoPlayer/supported-formats.html#ffmpeg-extension diff --git a/extensions/flac/README.md b/extensions/flac/README.md index 9db2e5727d..505482f7ed 100644 --- a/extensions/flac/README.md +++ b/extensions/flac/README.md @@ -2,18 +2,17 @@ ## Description ## -The Flac extension is a [Renderer][] implementation that helps you bundle -libFLAC (the Flac decoding library) into your app and use it along with -ExoPlayer to play Flac audio on Android devices. - -[Renderer]: https://google.github.io/ExoPlayer/doc/reference/com/google/android/exoplayer2/Renderer.html +The Flac extension provides `FlacExtractor` and `LibflacAudioRenderer`, which +use libFLAC (the Flac decoding library) to extract and decode FLAC audio. ## 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: +[top level README][]. + +In addition, it's necessary to build the extension's native components as +follows: * Set the following environment variables: @@ -46,3 +45,40 @@ ${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 + +## 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 the extractor and/or +renderer. + +### Using `FlacExtractor` ### + +`FlacExtractor` is used via `ExtractorMediaSource`. If you're using +`DefaultExtractorsFactory`, `FlacExtractor` will automatically be used to read +`.flac` files. If you're not using `DefaultExtractorsFactory`, return a +`FlacExtractor` from your `ExtractorsFactory.createExtractors` implementation. + +### Using `LibflacAudioRenderer` ### + +* 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 + `LibflacAudioRenderer` for playback if `MediaCodecAudioRenderer` doesn't + support the input format. Pass `EXTENSION_RENDERER_MODE_PREFER` to give + `LibflacAudioRenderer` priority over `MediaCodecAudioRenderer`. +* If you've subclassed `DefaultRenderersFactory`, add a `LibflacAudioRenderer` + to the output list in `buildAudioRenderers`. ExoPlayer will use the first + `Renderer` in the list that supports the input media format. +* If you've implemented your own `RenderersFactory`, return a + `LibflacAudioRenderer` 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 `LibflacAudioRenderer` + 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 `LibflacAudioRenderer` to the +player, then implement your own logic to use the renderer for a given track. diff --git a/extensions/opus/README.md b/extensions/opus/README.md index e5f5bcb168..cc21c77cf9 100644 --- a/extensions/opus/README.md +++ b/extensions/opus/README.md @@ -2,18 +2,17 @@ ## Description ## -The Opus extension is a [Renderer][] implementation that helps you bundle -libopus (the Opus decoding library) into your app and use it along with -ExoPlayer to play Opus audio on Android devices. - -[Renderer]: https://google.github.io/ExoPlayer/doc/reference/com/google/android/exoplayer2/Renderer.html +The Opus extension provides `LibopusAudioRenderer`, which uses +libopus (the Opus decoding library) to decode Opus audio. ## 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: +[top level README][]. + +In addition, it's necessary to build the extension's native components as +follows: * Set the following environment variables: @@ -59,3 +58,31 @@ ${NDK_PATH}/ndk-build APP_ABI=all -j4 * Clean and re-build the project. * If you want to use your own version of libopus, place it in `${OPUS_EXT_PATH}/jni/libopus`. + +## 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 `LibopusAudioRenderer`. +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 + `LibopusAudioRenderer` for playback if `MediaCodecAudioRenderer` doesn't + support the input format. Pass `EXTENSION_RENDERER_MODE_PREFER` to give + `LibopusAudioRenderer` priority over `MediaCodecAudioRenderer`. +* If you've subclassed `DefaultRenderersFactory`, add a `LibopusAudioRenderer` + to the output list in `buildAudioRenderers`. ExoPlayer will use the first + `Renderer` in the list that supports the input media format. +* If you've implemented your own `RenderersFactory`, return a + `LibopusAudioRenderer` 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 `LibopusAudioRenderer` + 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 `LibopusAudioRenderer` to the +player, then implement your own logic to use the renderer for a given track. diff --git a/extensions/vp9/README.md b/extensions/vp9/README.md index 87c5c8d54f..d28aa70db0 100644 --- a/extensions/vp9/README.md +++ b/extensions/vp9/README.md @@ -2,18 +2,17 @@ ## Description ## -The VP9 extension is a [Renderer][] implementation that helps you bundle libvpx -(the VP9 decoding library) into your app and use it along with ExoPlayer to play -VP9 video on Android devices. - -[Renderer]: https://google.github.io/ExoPlayer/doc/reference/com/google/android/exoplayer2/Renderer.html +The VP9 extension provides `LibvpxVideoRenderer`, which uses +libvpx (the VPx decoding library) to decode VP9 video. ## 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: +[top level README][]. + +In addition, it's necessary to build the extension's native components as +follows: * Set the following environment variables: @@ -76,3 +75,38 @@ ${NDK_PATH}/ndk-build APP_ABI=all -j4 `${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`.