Turn on HLS chunkless preparation by default.

Using chunkless preparation greatly improves start up time if the master
playlist declares CODECS for the renditions. Hence, we turn this on
by default as it benefits most well-defined HLS master playlists.

The only known reason why developers may want to turn this feature off is
when the renditions contain muxed closed-caption tracks that are not
declared in the master playlist. So this change also updates the documentation
and RELEASENOTES to point out this caveat.

PiperOrigin-RevId: 413950036

RELEASENOTES.md

@@ -37,6 +37,11 @@
     *   Support the `forced-subtitle` track role
     *   Support the `forced-subtitle` track role
         ([#9727](https://github.com/google/ExoPlayer/issues/9727)).
         ([#9727](https://github.com/google/ExoPlayer/issues/9727)).
 *   HLS:
 *   HLS:
+    *   Use chunkless preparation by default to improve start up time. If your
+        renditions contain muxed closed-caption tracks that are *not* declared
+        in the master playlist, you should add them to the master playlist to be
+        available for playback, or turn off chunkless preparation with
+        `HlsMediaSource.Factory.setAllowChunklessPreparation(false)`.
     *   Support key-frame accurate seeking in HLS
     *   Support key-frame accurate seeking in HLS
         ([#2882](https://github.com/google/ExoPlayer/issues/2882)).
         ([#2882](https://github.com/google/ExoPlayer/issues/2882)).
     *   Correctly populate `Format.label` for audio only HLS streams
     *   Correctly populate `Format.label` for audio only HLS streams

docs/hls.md

@@ -86,23 +86,28 @@ player.addListener(
 ExoPlayer provides multiple ways for you to tailor playback experience to your
 ExoPlayer provides multiple ways for you to tailor playback experience to your
 app's needs. See the [Customization page][] for examples.
 app's needs. See the [Customization page][] for examples.
 
 
-### Enabling faster start-up times ###
-
-You can improve HLS start up times noticeably by enabling chunkless preparation.
-When you enable chunkless preparation and `#EXT-X-STREAM-INF` tags contain the
-`CODECS` attribute, ExoPlayer will avoid downloading media segments as part of
-preparation. The following snippet shows how to enable chunkless preparation.
-
+### Disabling chunkless preparation ###
+
+By default, ExoPlayer will use chunkless preparation. This means that ExoPlayer
+will only use the information in the master playlist to prepare the stream,
+which works if the `#EXT-X-STREAM-INF` tags contain the `CODECS` attribute.
+
+You may need to disable this feature if your media segments contain muxed
+closed-caption tracks that are not declared in the master playlist with a
+`#EXT-X-MEDIA:TYPE=CLOSED-CAPTIONS` tag. Otherwise, these closed-caption tracks
+won't be detected and played. You can disable chunkless preparation in the
+`HlsMediaSource.Factory` as shown in the following snippet. Note that this
+will increase start up time as ExoPlayer needs to download a media segment to
+discover these additional tracks and it is preferable to declare the
+closed-caption tracks in the master playlist instead.
 ~~~
 ~~~
 HlsMediaSource hlsMediaSource =
 HlsMediaSource hlsMediaSource =
     new HlsMediaSource.Factory(dataSourceFactory)
     new HlsMediaSource.Factory(dataSourceFactory)
-        .setAllowChunklessPreparation(true)
+        .setAllowChunklessPreparation(false)
         .createMediaSource(MediaItem.fromUri(hlsUri));
         .createMediaSource(MediaItem.fromUri(hlsUri));
 ~~~
 ~~~
 {: .language-java}
 {: .language-java}
 
 
-You can find more details in our [Medium post about chunkless preparation][].
-
 ## Creating high quality HLS content ##
 ## Creating high quality HLS content ##
 
 
 In order to get the most out of ExoPlayer, there are certain guidelines you can
 In order to get the most out of ExoPlayer, there are certain guidelines you can
@@ -127,5 +132,4 @@ The following guidelines apply specifically for live streams:
 [PlayerView]: {{ site.exo_sdk }}/ui/PlayerView.html
 [PlayerView]: {{ site.exo_sdk }}/ui/PlayerView.html
 [UI components]: {{ site.baseurl }}/ui-components.html
 [UI components]: {{ site.baseurl }}/ui-components.html
 [Customization page]: {{ site.baseurl }}/customization.html
 [Customization page]: {{ site.baseurl }}/customization.html
-[Medium post about chunkless preparation]: https://medium.com/google-exoplayer/faster-hls-preparation-f6611aa15ea6
 [Medium post about HLS playback in ExoPlayer]: https://medium.com/google-exoplayer/hls-playback-in-exoplayer-a33959a47be7
 [Medium post about HLS playback in ExoPlayer]: https://medium.com/google-exoplayer/hls-playback-in-exoplayer-a33959a47be7

library/hls/src/main/java/com/google/android/exoplayer2/source/hls/HlsMediaSource.java

@@ -142,6 +142,7 @@ public final class HlsMediaSource extends BaseMediaSource
       metadataType = METADATA_TYPE_ID3;
       metadataType = METADATA_TYPE_ID3;
       streamKeys = Collections.emptyList();
       streamKeys = Collections.emptyList();
       elapsedRealTimeOffsetMs = C.TIME_UNSET;
       elapsedRealTimeOffsetMs = C.TIME_UNSET;
+      allowChunklessPreparation = true;
     }
     }
 
 
     /**
     /**