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][]
 * [Why are some media files not seekable?][]
 * [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 MP4/FMP4 files play incorrectly?][]
 * [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
 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? ####
 
 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
 [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-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-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
@@ -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
 [`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
+[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_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)