Add instructions to enable asynchronous buffer queueing

PiperOrigin-RevId: 434713295

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
 

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

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