Dev guide updates for 2.12

_data/navigation.yml

@@ -27,10 +27,12 @@ en:
         url:    hello-world.html
       - title:  Listening to player events
         url:    listening-to-player-events.html
-      - title:  Media sources
-        url:    media-sources.html
       - title:  Playlists
         url:    playlists.html
+      - title:  Media items
+        url:    media-items.html
+      - title:  Media sources
+        url:    media-sources.html
       - title:  Track selection
         url:    track-selection.html
       - title:  UI components

supported-formats-dash.md → _page_fragments/supported-formats-dash.md

@@ -19,6 +19,6 @@ also be supported (see the
 | **Metadata** |||
 | EMSG metadata | YES | Embedded in FMP4 |
 | **Content protection** |||
-| Widevine | YES | API 19+ ("cenc" scheme) and 25+ ("cbcs", "cbc1" and "cens" schemes) |
+| Widevine | YES | API 19+ ("cenc" scheme) and 25+ ("cbcs" scheme) |
 | PlayReady SL2000 | YES | Android TV only |
 | ClearKey | YES | API 21+ |

supported-formats-progressive.md → _page_fragments/supported-formats-progressive.md

@@ -28,7 +28,7 @@ enabling approximate seeking using a constant bitrate assumption. This
 functionality is not enabled by default. The simplest way to enable this
 functionality for all extractors that support it is to use
 `DefaultExtractorsFactory.setConstantBitrateSeekingEnabled`, as described
-[here](progressive.html#enabling-constant-bitrate-seeking).
+[here](customization.html#enabling-constant-bitrate-seeking).
 
 \*\*\* The [FLAC extension][] extractor outputs raw audio, which can be handled
 by the framework on all API levels. The [core library][] FLAC extractor outputs

ad-insertion.md

@@ -15,11 +15,12 @@ skippable.
 
 When using ExoPlayer's `AdsMediaSource` for client-side ad insertion, the player
 has information about the ads to be played. This has several benefits:
-- The player can expose metadata and functionality relating to ads via its API.
-- [ExoPlayer UI components][] can show markers for ad positions automatically,
-and change behavior depending on whether ad is playing.
-- Internally, the player can keep a consistent buffer across transitions between
-ads and content.
+
+* The player can expose metadata and functionality relating to ads via its API.
+* [ExoPlayer UI components][] can show markers for ad positions automatically,
+  and change their behavior depending on whether ad is playing.
+* Internally, the player can keep a consistent buffer across transitions between
+  ads and content.
 
 In this setup, the player takes care of switching between ads and content, which
 means that apps don't need to take care of controlling multiple separate
@@ -29,25 +30,58 @@ When preparing content videos and ad tags for use with client-side ad insertion,
 ads should ideally be positioned at synchronization samples (keyframes) in the
 content video so that the player can resume content playback seamlessly.
 
+### Declarative ad support ###
+
+An ad tag URI can be specified when building a `MediaItem`:
+
+~~~
+MediaItem mediaItem =
+    new MediaItem.Builder().setUri(videoUri).setAdTagUri(adTagUri).build();
+~~~
+{: .language-java}
+
+To enable player support for media items that specify ad tags, it's necessary to
+build and inject a `DefaultMediaSourceFactory` configured with an
+`AdsLoaderProvider` and an `AdViewProvider` when creating the player:
+
+~~~
+MediaSourceFactory mediaSourceFactory =
+    new DefaultMediaSourceFactory(context)
+        .setAdsLoaderProvider(adsLoaderProvider)
+        .setAdViewProvider(playerView);
+SimpleExoPlayer player = new SimpleExoPlayer.Builder(context)
+    .setMediaSourceFactory(mediaSourceFactory)
+    .build();
+~~~
+{: .language-java}
+
+Internally, `DefaultMediaSourceFactory` will wrap the content media source in an
+`AdsMediaSource`. The `AdsMediaSource` will obtain an `AdsLoader` from the
+`AdsLoaderProvider` and use it to insert ads as defined by the media item's ad
+tag.
+
+ExoPlayer's `StyledPlayerView` and `PlayerView` UI components both implement
+`AdViewProvider`. The IMA extension provides an easy to use `AdsLoader`, as
+described below.
+
 ### IMA extension ###
 
-The [ExoPlayer IMA extension][] makes it easy to integrate client-side ad
-insertion into your app. It wraps the functionality of the [client-side IMA
-SDK][] to support playback of VAST/VMAP ad tags. For instructions on how to use
-the extension, please see the [README][], which describes how to set up playback
-using an `AdsMediaSource` and the extension's `ImaAdsLoader`, and how to handle
-backgrounding/resuming playback.
+The [ExoPlayer IMA extension][] provides `ImaAdsLoader`, making it easy to
+integrate client-side ad insertion into your app. It wraps the functionality of
+the [client-side IMA SDK][] to support playback of VAST/VMAP ad tags. For
+instructions on how to use the extension, including how to handle backgrounding
+and resuming playback, please see the [README][].
 
-The [demo application][] can also use the IMA extension when it is built using a
-build variant with extensions, and includes several sample VAST/VMAP ad tags in
-the sample list.
+The [demo application][] uses the IMA extension, and includes several sample
+VAST/VMAP ad tags in the sample list.
 
 #### UI considerations ####
 
-`PlayerView` will hide controls during playback of ads by default, but apps can
-toggle this behavior via `PlayerView.setControllerHideDuringAds(false)`. The IMA
-SDK will show additional views on top of the player while an ad is playing
-(e.g., a 'more info' link and a skip button, if applicable).
+`StyledPlayerView` and `PlayerView` hide controls during playback of ads by
+default, but apps can toggle this behavior by calling
+`setControllerHideDuringAds`, which is defined on both views. The IMA SDK will
+show additional views on top of the player while an ad is playing (e.g., a 'more
+info' link and a skip button, if applicable).
 
 Since advertisers expect a consistent experience across apps, the IMA SDK does
 not allow customization of the views that it shows while an ad is playing.
@@ -56,33 +90,57 @@ not allow customization of the views that it shows while an ad is playing.
 The IMA SDK may report whether ads are obscured by application provided views
 rendered on top of the player. Apps that need to overlay views that are
 essential for controlling playback must register them with the IMA SDK so that
-they can be omitted from viewability calculations. To do that, implement the
-`AdsLoader.AdViewProvider` interface and pass the implementation when
-constructing the `AdsMediaSource`. `PlayerView` implements this interface to
-register its controls overlay. For more information, see [Open Measurement in
-the IMA SDK][].
+they can be omitted from viewability calculations. When using `StyledPlayerView`
+or `PlayerView` as the `AdViewProvider`, they will automatically register their
+control overlays. Apps that use a custom player UI must register overlay views
+by returning them from `AdViewProvider.getAdOverlayInfos`.
+
+For more information about overlay views, see
+[Open Measurement in the IMA SDK][].
 
 #### Companion ads ####
 
 Some ad tags contain additional companion ads that can be shown in 'slots' in an
 app UI. These slots can be passed via
-`ImaAdsLoader.getAdDisplayContainer().setCompanionSlots(slots)`. For more
-information see [Adding Companion Ads][].
+`ImaAdsLoader.Builder.setCompanionAdSlots(slots)`. For more information see
+[Adding Companion Ads][].
 
 ### Using a third-party ads SDK ###
 
-If you need to load ads via a third-party ads SDK, it's worth checking first
-whether it already provides an ExoPlayer integration.
-
-If not, implementing a custom `AdsLoader` allows you to take advantage of
-`AdsMediaSource`. `ImaAdsLoader` acts as an example implementation.
-
-Alternatively you can use ExoPlayer's [playlist support][] to build a sequence
-of ads and content clips. To produce a content clip, wrap the content media
-source in a `ClippingMediaSource`, passing the relevant start/end times based on
-positions of the preceding/following ads (if any). In this approach the player
-doesn't know about ads, but it's still possible show ad markers in ExoPlayer's
-PlayerView via `PlayerView.setExtraAdGroupMarkers`.
+If you need to load ads via a third-party ads SDK, it's worth checking whether
+it already provides an ExoPlayer integration. If not, implementing a custom
+`AdsLoader` that wraps the third-party ads SDK is the recommended approach,
+since it provides the benefits of `AdsMediaSource` described above.
+`ImaAdsLoader` acts as an example implementation.
+
+Alternatively, you can use ExoPlayer's [playlist support][] to build a sequence
+of ads and content clips:
+
+~~~
+// A pre-roll ad.
+MediaItem preRollAd = MediaItem.fromUri(preRollAdUri);
+// The start of the content.
+MediaItem contentStart =
+    new MediaItem.Builder()
+        .setUri(contentUri)
+        .setClipEndPositionMs(120_000)
+        .build();
+// A mid-roll ad.
+MediaItem midRollAd = MediaItem.fromUri(midRollAdUri);
+// The rest of the content
+MediaItem contentEnd =
+    new MediaItem.Builder()
+        .setUri(contentUri)
+        .setClipStartPositionMs(120_000)
+        .build();
+
+// Build the playlist.
+player.addMediaItem(preRollAd);
+player.addMediaItem(contentStart);
+player.addMediaItem(midRollAd);
+player.addMediaItem(contentEnd);
+~~~
+{: .language-java}
 
 ## Server-side ad insertion ##
 
@@ -104,13 +162,13 @@ provide any integration with the DAI part of the IMA SDK.
 
 [VAST]: https://www.iab.com/wp-content/uploads/2015/06/VASTv3_0.pdf
 [VMAP]: https://www.iab.com/guidelines/digital-video-multiple-ad-playlist-vmap-1-0-1/
-[ExoPlayer UI components]: {{ site.baseurl }}/ui-components.md
+[ExoPlayer UI components]: {{ site.baseurl }}/ui-components.html
 [ExoPlayer IMA extension]: https://github.com/google/ExoPlayer/tree/release-v2/extensions/ima
 [client-side IMA SDK]: https://developers.google.com/interactive-media-ads/docs/sdks/android
 [README]: https://github.com/google/ExoPlayer/tree/release-v2/extensions/ima
 [demo application]: {{ site.baseurl }}/demo-application.html
 [Open Measurement in the IMA SDK]: https://developers.google.com/interactive-media-ads/docs/sdks/android/omsdk
 [Adding Companion Ads]: https://developers.google.com/interactive-media-ads/docs/sdks/android/companions
-[playlist support]: {{ site.baseurl }}/playlists.md
+[playlist support]: {{ site.baseurl }}/playlists.html
 [incorporating ads into a playlist]: https://developer.apple.com/documentation/http_live_streaming/example_playlists_for_http_live_streaming/incorporating_ads_into_a_playlist
 [supported formats]: {{ site.baseurl }}/supported-formats.html

battery-consumption.md

@@ -53,23 +53,24 @@ consumption across the Android device and media content ecosystems.
 
 ### Audio playback ###
 
-For audio playback, our measurements show that ExoPlayer can draw significantly
-more power than MediaPlayer. This is particularly true for devices that support
-audio offload, which allows audio processing to be offloaded from the CPU to a
-dedicated signal processor. MediaPlayer is able to make use of audio offload to
-reduce power consumption, whereas ExoPlayer cannot because there are no public
-APIs in the Android framework for enabling it. Note that this also means audio
-offload cannot be used by any other application level media players, or by apps
-that are using `AudioTrack` directly.
+For short audio playbacks or playbacks when the screen is on, using ExoPlayer
+does not have a significant impact on power compared to using MediaPlayer.
 
-Whether the increased robustness, flexibility and feature set that ExoPlayer
-provides over MediaPlayer is worth the increased power consumption for audio
-only use cases is something an app developer must decide, taking their
-requirements and app usage patterns into account.
+For long playbacks with the screen off, ExoPlayer's audio offload mode needs to
+be used or ExoPlayer may consume significantly more power than MediaPlayer.
+Audio offload allows audio processing to be offloaded from the CPU to a
+dedicated signal processor. It is used by default by MediaPlayer but not
+ExoPlayer. ExoPlayer introduced support for audio offload in 2.12 as an
+experimental feature. See `DefaultRenderersFactory.setEnableAudioOffload` and
+`ExoPlayer.experimentalSetOffloadSchedulingEnabled` for more details on how
+to enable it.
 
-New public APIs in Android Q will enable ExoPlayer, as well as other application
-level media players, to utilize audio offload functionality. We plan to make use
-of these APIs in a future ExoPlayer release.
-{:.info}
+Due to SDK API limitations, ExoPlayer's audio offload mode is only available on
+devices running Android 10 and above. MediaPlayer can use audio offload on
+devices running earlier versions of Android. Whether the increased robustness,
+flexibility and feature set that ExoPlayer provides over MediaPlayer is worth
+the increased power consumption for audio only use cases on older devices is
+something an app developer must decide, taking their requirements and app usage
+patterns into account.
 
 [Monsoon power monitor]: https://www.msoon.com/battery-configuration