Add a troubleshooting section about slow seeking

#minor-release

PiperOrigin-RevId: 477432256

docs/troubleshooting.md

@@ -9,6 +9,7 @@ redirect_from:
 * [Fixing "SSLHandshakeException", "CertPathValidatorException" and "ERR_CERT_AUTHORITY_INVALID" errors][]
 * [Fixing "SSLHandshakeException", "CertPathValidatorException" and "ERR_CERT_AUTHORITY_INVALID" errors][]
 * [Why are some media files not seekable?][]
 * [Why are some media files not seekable?][]
 * [Why is seeking inaccurate in some MP3 files?][]
 * [Why is seeking inaccurate in some MP3 files?][]
+* [Why is seeking in my video slow?][]
 * [Why do some MPEG-TS files fail to play?][]
 * [Why do some MPEG-TS files fail to play?][]
 * [Why do some MP4/FMP4 files play incorrectly?][]
 * [Why do some MP4/FMP4 files play incorrectly?][]
 * [Why do some streams fail with HTTP response code 301 or 302?][]
 * [Why do some streams fail with HTTP response code 301 or 302?][]
@@ -104,6 +105,27 @@ If you control the media you're playing, we strongly advise that you use a more
 appropriate container format, such as MP4. There are no use cases we're aware of
 appropriate container format, such as MP4. There are no use cases we're aware of
 where MP3 is the best choice of media format.
 where MP3 is the best choice of media format.
 
 
+#### Why is seeking in my video slow? ####
+
+When the player seeks to a new playback position in a video it needs to do two
+things:
+
+1. Load the data corresponding to the new playback position into the buffer
+   (this may not be necessary if this data is already buffered).
+2. Flush the video decoder and start decoding from the I-frame (keyframe) before
+   the new playback position, due to the [intra-frame coding] used by most video
+   compression formats. In order to ensure the seek is 'accurate' (i.e.
+   playback starts exactly at the seek position), all frames between the
+   preceding I-frame and the seek position need to be decoded and immediately
+   discarded (without being shown on the screen).
+
+The latency introduced by (1) can be mitigated by either increasing the amount
+of data buffered in memory by the player, or [pre-caching the data to disk].
+
+The latency introduced by (2) can be mitigated by either reducing the accuracy
+of the seek using [`ExoPlayer.setSeekParameters`], or re-encoding the video
+to have more frequent I-frames (which will result in a larger output file).
+
 #### Why do some MPEG-TS files fail to play? ####
 #### Why do some MPEG-TS files fail to play? ####
 
 
 Some MPEG-TS files do not contain access unit delimiters (AUDs). By default
 Some MPEG-TS files do not contain access unit delimiters (AUDs). By default
@@ -309,6 +331,7 @@ particularly when playing DRM protected or high frame rate content, you can try
 [What formats does ExoPlayer support?]: #what-formats-does-exoplayer-support
 [What formats does ExoPlayer support?]: #what-formats-does-exoplayer-support
 [Why are some media files not seekable?]: #why-are-some-media-files-not-seekable
 [Why are some media files not seekable?]: #why-are-some-media-files-not-seekable
 [Why is seeking inaccurate in some MP3 files?]: #why-is-seeking-inaccurate-in-some-mp3-files
 [Why is seeking inaccurate in some MP3 files?]: #why-is-seeking-inaccurate-in-some-mp3-files
+[Why is seeking in my video slow?]: #why-is-seeking-in-my-video-slow
 [Why do some MPEG-TS files fail to play?]: #why-do-some-mpeg-ts-files-fail-to-play
 [Why do some MPEG-TS files fail to play?]: #why-do-some-mpeg-ts-files-fail-to-play
 [Why do some MP4/FMP4 files play incorrectly?]: #why-do-some-mp4fmp4-files-play-incorrectly
 [Why do some MP4/FMP4 files play incorrectly?]: #why-do-some-mp4fmp4-files-play-incorrectly
 [Why do some streams fail with HTTP response code 301 or 302?]: #why-do-some-streams-fail-with-http-response-code-301-or-302
 [Why do some streams fail with HTTP response code 301 or 302?]: #why-do-some-streams-fail-with-http-response-code-301-or-302
@@ -328,6 +351,9 @@ particularly when playing DRM protected or high frame rate content, you can try
 [set on a `DefaultExtractorsFactory`]: {{ site.base_url }}/customization.html#customizing-extractor-flags
 [set on a `DefaultExtractorsFactory`]: {{ site.base_url }}/customization.html#customizing-extractor-flags
 [`setMp3ExtractorFlags`]: {{ site.exo_sdk }}/extractor/DefaultExtractorsFactory#setMp3ExtractorFlags(@com.google.android.exoplayer2.extractor.mp4.Mp4Extractor.Flagsint)
 [`setMp3ExtractorFlags`]: {{ site.exo_sdk }}/extractor/DefaultExtractorsFactory#setMp3ExtractorFlags(@com.google.android.exoplayer2.extractor.mp4.Mp4Extractor.Flagsint)
 [`FLAG_ENABLE_INDEX_SEEKING`]: {{ site.exo_sdk }}/extractor/mp3/Mp3Extractor.html#FLAG_ENABLE_INDEX_SEEKING
 [`FLAG_ENABLE_INDEX_SEEKING`]: {{ site.exo_sdk }}/extractor/mp3/Mp3Extractor.html#FLAG_ENABLE_INDEX_SEEKING
+[intra-frame coding]: https://en.wikipedia.org/wiki/Intra-frame_coding
+[pre-caching the data to disk]: https://exoplayer.dev/downloading-media.html
+[`ExoPlayer.setSeekParameters]: {{ site.exo_sdk }}/ExoPlayer.html#setSeekParameters(com.google.android.exoplayer2.SeekParameters)
 [`FLAG_DETECT_ACCESS_UNITS`]: {{ site.exo_sdk }}/extractor/ts/DefaultTsPayloadReaderFactory.html#FLAG_DETECT_ACCESS_UNITS
 [`FLAG_DETECT_ACCESS_UNITS`]: {{ site.exo_sdk }}/extractor/ts/DefaultTsPayloadReaderFactory.html#FLAG_DETECT_ACCESS_UNITS
 [`FLAG_ALLOW_NON_IDR_KEYFRAMES`]: {{ site.exo_sdk }}/extractor/ts/DefaultTsPayloadReaderFactory.html#FLAG_ALLOW_NON_IDR_KEYFRAMES
 [`FLAG_ALLOW_NON_IDR_KEYFRAMES`]: {{ site.exo_sdk }}/extractor/ts/DefaultTsPayloadReaderFactory.html#FLAG_ALLOW_NON_IDR_KEYFRAMES
 [`setTsExtractorFlags`]: {{ site.exo_sdk }}/extractor/DefaultExtractorsFactory#setTsExtractorFlags(@com.google.android.exoplayer2.extractor.mp4.Mp4Extractor.Flagsint)
 [`setTsExtractorFlags`]: {{ site.exo_sdk }}/extractor/DefaultExtractorsFactory#setTsExtractorFlags(@com.google.android.exoplayer2.extractor.mp4.Mp4Extractor.Flagsint)