Update developer guide

demo-application.md

@@ -156,7 +156,7 @@ demo app using:
 adb shell am start -d https://yourdomain.com/samples.exolist.json
 {% endhighlight %}
 
-Clicking a `*.exolist.json` link (e.g. in the browser or an email client) on a
+Clicking a `*.exolist.json` link (e.g., in the browser or an email client) on a
 device with the demo app installed will also open it in the demo app. Hence
 hosting a `*.exolist.json` JSON file provides a simple way of distributing
 content for others to try in the demo app.
@@ -184,10 +184,10 @@ Supported optional extras for a single sample intent are:
   name1, value1, name2, value2 etc. if protected
 
 When using `adb shell am start` to fire an intent, an optional string extra can
-be set with `--es` (e.g. `--es extension mpd`). An optional boolean extra can be
-set with `--ez` (e.g. `--ez prefer_extension_decoders TRUE`). An optional string
-array extra can be set with `--esa` (e.g. `--esa drm_key_request_properties
-name1,value1`).
+be set with `--es` (e.g., `--es extension mpd`). An optional boolean extra can
+be set with `--ez` (e.g., `--ez prefer_extension_decoders TRUE`). An optional
+string array extra can be set with `--esa` (e.g.,
+`--esa drm_key_request_properties name1,value1`).
 
 To play a playlist of samples set the intent's action to
 `com.google.android.exoplayer.demo.action.VIEW_LIST` and use a `uri_list` string

faqs.md

@@ -5,6 +5,8 @@ weight: 5
 ---
 
 * [What formats does ExoPlayer support?][]
+* [Why are some media files not seekable?][]
+* [How do I keep audio playing when my app is backgrounded?][]
 * [How do I get smooth animation/scrolling of video?][]
 * [Should I use SurfaceView or TextureView?][]
 * [Does ExoPlayer support emulators?][]
@@ -15,6 +17,34 @@ weight: 5
 
 See the [Supported formats][] page.
 
+#### Why are some media files not seekable? ####
+
+ExoPlayer does not support seeking in media where the only method for performing
+accurate seek operations is for the player to scan and index the entire file.
+ExoPlayer considers such files as unseekable. Most modern media container
+formats include metadata for seeking (e.g., a sample index), have a well defined
+seek algorithm (e.g., interpolated bisection search for Ogg), or indicate that
+their content is constant bitrate. Efficient seek operations are possible and
+supported by ExoPlayer in these cases.
+
+If you require seeking but have unseekable media, we suggest converting your
+content to use a more appropriate container format. In the specific case of
+unseekable MP3 files, you can enable seeking under the assumption that the
+files have a constant bitrate using [FLAG_ENABLE_CONSTANT_BITRATE_SEEKING][].
+
+#### How do I keep audio playing when my app is backgrounded? ####
+
+There are a few steps that you need to take to ensure continued playback of
+audio when your app is in the background:
+
+1. You need to have a running [foreground service][]. This prevents the system
+   from killing your process to free up resources.
+1. You need to hold a [WifiLock][] and a [WakeLock][]. These ensure that the
+   system keeps the WiFi radio and CPU awake.
+
+It's important that you stop the service and release the locks as soon as audio
+is no longer being played.
+
 #### How do I get smooth animation/scrolling of video? ####
 
 `SurfaceView` rendering wasn't properly synchronized with view animations until
@@ -58,8 +88,15 @@ ExoPlayer team. Where possible, we recommend testing media applications on
 physical devices rather than emulators.
 
 [What formats does ExoPlayer support?]: #what-formats-does-exoplayer-support
+[Why are some media files not seekable?]: #why-are-some-media-files-not-seekable
+[How do I keep audio playing when my app is backgrounded?]: #how-do-i-keep-audio-playing-when-my-app-is-backgrounded
 [How do I get smooth animation/scrolling of video?]: #how-do-i-get-smooth-animationscrolling-of-video
 [Should I use SurfaceView or TextureView?]: #should-i-use-surfaceview-or-textureview
 [Does ExoPlayer support emulators?]: #does-exoplayer-support-emulators
+
 [Supported formats]: https://google.github.io/ExoPlayer/supported-formats.html
+[FLAG_ENABLE_CONSTANT_BITRATE_SEEKING]: https://google.github.io/ExoPlayer/doc/reference/com/google/android/exoplayer2/extractor/mp3/Mp3Extractor.html#FLAG_ENABLE_CONSTANT_BITRATE_SEEKING
+[foreground service]: https://developer.android.com/guide/components/services.html#Foreground
+[WifiLock]: https://developer.android.com/reference/android/net/wifi/WifiManager.WifiLock.html
+[WakeLock]: https://developer.android.com/reference/android/os/PowerManager.WakeLock.html
 [`SDK_INT`]: https://developer.android.com/reference/android/os/Build.VERSION.html#SDK_INT

guide.md

@@ -155,7 +155,7 @@ creating a `SimpleExoPlayer`.
 Handler mainHandler = new Handler();
 BandwidthMeter bandwidthMeter = new DefaultBandwidthMeter();
 TrackSelection.Factory videoTrackSelectionFactory =
-    new AdaptiveVideoTrackSelection.Factory(bandwidthMeter);
+    new AdaptiveTrackSelection.Factory(bandwidthMeter);
 TrackSelector trackSelector =
     new DefaultTrackSelector(videoTrackSelectionFactory);
 
@@ -273,9 +273,9 @@ LoopingMediaSource loopingSource = new LoopingMediaSource(source);
 `ConcatenatingMediaSource` enables sequential playback of two or more individual
 `MediaSource`s. The following example plays two videos in sequence. Transitions
 between sources are seamless. There is no requirement that the sources being
-concatenated are of the same format (e.g. it’s fine to concatenate a video file
+concatenated are of the same format (e.g., it’s fine to concatenate a video file
 containing 480p H264 with one that contains 720p VP9). The sources may even be
-of different types (e.g. it’s fine to concatenate a video with an audio only
+of different types (e.g., it’s fine to concatenate a video with an audio only
 stream).
 
 {% highlight java %}
@@ -348,7 +348,7 @@ also show an appropriate error to the user if playback fails.
 
 When using `SimpleExoPlayer`, additional listeners can be set on the player. In
 particular `setVideoListener` allows an application to receive events related to
-video rendering that may be useful for adjusting the UI (e.g. the aspect ratio
+video rendering that may be useful for adjusting the UI (e.g., the aspect ratio
 of the `Surface` onto which video is being rendered). Other listeners can be set
 to on a `SimpleExoPlayer` to receive debugging information, for example by
 calling `setVideoDebugListener` and `setAudioDebugListener`.
@@ -422,7 +422,7 @@ which provide `MediaCrypto` objects for decryption as well as ensuring that the
 required decryption keys are available to the underlying DRM module being used.
 
 The ExoPlayer library provides a default implementation of `DrmSessionManager`,
-called `StreamingDrmSessionManager`, which uses `MediaDrm`. The session manager
+called `DefaultDrmSessionManager`, which uses `MediaDrm`. The session manager
 supports any DRM scheme for which a modular DRM component exists on the device.
 All Android devices are required to support Widevine modular DRM (with L3
 security, although many devices also support L1). Some devices may support

supported-devices.md

@@ -35,5 +35,5 @@ be found
   using a certain type of HDMI to DVI cable, which causes video being played too
   quickly. Use of an HDMI to DVI cable is not realistic for an end user setup
   because such cables cannot carry audio. Hence this issue can be safely
-  ignored. We suggest using a realistic end user setup (e.g. the device
+  ignored. We suggest using a realistic end user setup (e.g., the device
   connected to a TV using a standard HDMI cable) for development and testing.

supported-formats.md

@@ -8,14 +8,14 @@ When defining the formats that ExoPlayer supports, it's important to note that
 "media formats" are in fact defined at multiple levels. From the lowest level to
 the highest, these are:
 
-* The format of the individual media samples (e.g. a frame of video or a frame
+* The format of the individual media samples (e.g., a frame of video or a frame
   of audio). We call these *sample formats*. Note that a typical video file will
-  contain media in at least two sample formats; one for video (e.g. H.264) and
-  one for audio (e.g. AAC).
+  contain media in at least two sample formats; one for video (e.g., H.264) and
+  one for audio (e.g., AAC).
 * The format of the container that houses the media samples and associated
   metadata. We call these *container formats*. A media file has a single
-  container format (e.g. MP4), which is commonly indicated by the file
-  extension. Note that for some audio only formats (e.g. MP3), the sample and
+  container format (e.g., MP4), which is commonly indicated by the file
+  extension. Note that for some audio only formats (e.g., MP3), the sample and
   container formats may be the same.
 * Adaptive streaming technologies such as DASH, SmoothStreaming and HLS. These
   are not media formats as such, however it's still necessary to define what
@@ -113,7 +113,7 @@ ExoPlayer. The contained audio and video sample formats must also be supported
 | ADTS (AAC) | YES | Not seekable* |
 | Flac | YES | Using the [Flac extension][] only |
 
-\* Seeking is unsupported because the container does not provide metadata (e.g.
+\* Seeking is unsupported because the container does not provide metadata (e.g.,
 a sample index) to allow a media player to perform a seek in an efficient way.
 If seeking is required, we suggest using a more appropriate container format.