diff --git a/docs/customization.md b/docs/customization.md index 5ac250ce72..41f1d151f1 100644 --- a/docs/customization.md +++ b/docs/customization.md @@ -206,6 +206,38 @@ DefaultExtractorsFactory extractorsFactory = The `ExtractorsFactory` can then be injected via `DefaultMediaSourceFactory` as described for customizing extractor flags above. + +### Enabling asynchronous buffer queueing ### + +Asynchronous buffer queueing is an enhancement in ExoPlayer's rendering pipeline +that improves dropped frames and audio underruns. With asynchronous buffer +queueing, the player is operating the platform's `MediaCodec` in [asynchronous +mode][], thus the feature is applicable when content is decoded using the +platform decoders. The player also utilizes additional threads for scheduling +decoding and rendering of data. + +The feature is enabled by default on devices with Android 12 onwards and you can +also enable it in your app for other devices too. For example, consider enabling +asynchronous buffer queueing if you observe dropped frames or audio underruns on +specific devices, particularly with Widevine-protected or high frame-rate +content. + +In the simplest case, you need to inject a `DefaultRenderersFactory` to the +player as follows: + +~~~ +DefaultRenderersFactory renderersFactory = + new DefaultRenderersFactory(context) + .forceEnableMediaCodecAsynchronousQueueing(); +ExoPlayer exoPlayer = new ExoPlayer.Builder(context, renderersFactory).build(); +~~~ +{: .language-java} + +If however in your app you are instantiating the player with custom renderers, +then make sure to create the `MediaCodecVideoRenderer` and +`MediaCodecAudioRenderer` instances passing an +`AsynchronousMediaCodecAdapter.Factory` to their constructor. + ## MediaSource customization ## The examples above inject customized components for use during playback of all @@ -274,4 +306,5 @@ When building custom components, we recommend the following: [OkHttp extension]: https://github.com/google/ExoPlayer/tree/release-v2/extensions/okhttp [LoadErrorHandlingPolicy]: {{ site.exo_sdk }}/upstream/LoadErrorHandlingPolicy.html [media source based playlist API]: {{ site.baseurl }}/media-sources.html#media-source-based-playlist-api +[asynchronous mode]: https://developer.android.com/reference/android/media/MediaCodec#asynchronous-processing-using-buffers diff --git a/docs/drm.md b/docs/drm.md index 0ab2118e99..92b0027ad1 100644 --- a/docs/drm.md +++ b/docs/drm.md @@ -99,6 +99,13 @@ MediaSource.Factory mediaSourceFactory = ~~~ {: .language-java} +### Improving playback performance ### + +If you're experiencing video stuttering (dropped frames and/or audio underruns) +with Widevide-protected content on a device with Android version prior to 12, +you can try [enabling asynchronous buffer queueing]. + [main demo app]: {{ site.release_v2 }}/demos/main [`MediaDrm`]: {{ site.android_sdk }}/android/media/MediaDrm.html [used when building the player]: {{ site.baseurl }}/media-sources.html#customizing-media-source-creation +[enabling asynchronous buffer queueing]: {{ site.baseurl }}/customization.html#enabling-asynchronous-buffer-queueing diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index d547b285ff..f66f446462 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -22,6 +22,7 @@ redirect_from: * [Why does content fail to play, but no error is surfaced?] * [How can I get a decoding extension to load and be used for playback?][] * [Can I play YouTube videos directly with ExoPlayer?][] +* [Video playback is stuttering][] --- @@ -293,6 +294,17 @@ No, ExoPlayer cannot play videos from YouTube, i.e., urls of the form Android Player API](https://developers.google.com/youtube/android/player/) which is the official way to play YouTube videos on Android. +#### Video playback is stuttering ### + +The device on which you're observing this may not be able to decode the content +fast enough if, for example, the content bitrate or resolution exceeds the +device capabilities. You may need to use lower quality content to obtain good +performance on such devices. + +If you're experiencing this on a device with Android version prior to 12, +particularly with Widevine-protected or high frame-rate content, you can try +[enabling asynchronous buffer queueing]. + [Fixing "Cleartext HTTP traffic not permitted" errors]: #fixing-cleartext-http-traffic-not-permitted-errors [Fixing "SSLHandshakeException", "CertPathValidatorException" and "ERR_CERT_AUTHORITY_INVALID" errors]: #fixing-sslhandshakeexception-certpathvalidatorexception-and-err_cert_authority_invalid-errors [What formats does ExoPlayer support?]: #what-formats-does-exoplayer-support @@ -311,7 +323,7 @@ is the official way to play YouTube videos on Android. [Why does content fail to play, but no error is surfaced?]: #why-does-content-fail-to-play-but-no-error-is-surfaced [How can I get a decoding extension to load and be used for playback?]: #how-can-i-get-a-decoding-extension-to-load-and-be-used-for-playback [Can I play YouTube videos directly with ExoPlayer?]: #can-i-play-youtube-videos-directly-with-exoplayer - +[Video playback is stuttering]: #video-playback-is-stuttering [Supported formats]: {{ site.baseurl }}/supported-formats.html [set on a `DefaultExtractorsFactory`]: {{ site.base_url }}/customization.html#customizing-extractor-flags @@ -349,3 +361,4 @@ is the official way to play YouTube videos on Android. [`DefaultRenderersFactory`]: {{ site.exo_sdk }}/DefaultRenderersFactory.html [`LibraryLoader`]: {{ site.exo_sdk }}/util/LibraryLoader.html [`EventLogger`]: {{ site.baseurl }}/debug-logging.html +[enabling asynchronous buffer queueing]: {{ site.baseurl }}/customization.html#enabling-asynchronous-buffer-queueing