loliball/media
1
0
Fork 0
mirror of https://github.com/androidx/media.git synced 2025-05-07 07:30:22 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Update the playback speed details in the live streaming dev guide

Browse Source 
ExoPlayer's default behaviour changed in b12918d1e6.

Issue: google/ExoPlayer#10170
#minor-release
PiperOrigin-RevId: 443611196
This commit is contained in:
ibaker 2022-04-22 10:42:35 +01:00 committed by Ian Baker
parent 20dac7cb0b
commit f08dea266e
1 changed files with 53 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

95
docs/live-streaming.md
View File

@ -16,13 +16,6 @@ and can only be played at one position. The documentation on this page is only
relevant to adaptive live streams. relevant to adaptive live streams.
{:.info} {:.info}
ExoPlayer adjusts the live offset by slightly changing the playback speed.
The player will try to match user and media preferences, but will also try to
react to changing network conditions. For example, if rebuffers occur during
playback, the player will move further away from the live edge. If there is
enough available buffer over a longer period of time, the player will move
closer to the live edge again.
## Detecting and monitoring live playbacks ## ## Detecting and monitoring live playbacks ##
Every time a live window is updated, registered `Player.Listener` instances Every time a live window is updated, registered `Player.Listener` instances
@ -87,10 +80,13 @@ components to support additional modes when playing live streams.
## Configuring live playback parameters ## ## Configuring live playback parameters ##
By default, ExoPlayer uses live playback parameters defined by the media. If you ExoPlayer uses some parameters to control the offset of the playback position
want to configure the live playback parameters yourself, you can set them on a from the live edge, and the range of playback speeds that can be used to
per `MediaItem` basis by calling `MediaItem.Builder.setLiveConfiguration`. If adjust this offset.
you'd like to set these values globally for all items, you can set them on the
By default, ExoPlayer reads values for these parameters directly from the media.
These values can also be provided per `MediaItem`, by calling
`MediaItem.Builder.setLiveConfiguration`, or set globally on the
`DefaultMediaSourceFactory` provided to the player. In both cases, the provided `DefaultMediaSourceFactory` provided to the player. In both cases, the provided
values will override parameters defined by the media. values will override parameters defined by the media.
@ -130,40 +126,31 @@ Available configuration values are:
* `maxPlaybackSpeed`: The maximum playback speed the player can use to catch up * `maxPlaybackSpeed`: The maximum playback speed the player can use to catch up
when trying to reach the target live offset. when trying to reach the target live offset.
## Playback speed adjustment ##
When playing a low-latency live stream ExoPlayer adjusts the live offset by
slightly changing the playback speed. The player will try to match the target
live offset provided by the media or the app, but will also try to react to
changing network conditions. For example, if rebuffers occur during playback,
the player will slow down playback slightly to move further away from the live
edge. If the network then becomes stable enough to support playing closer to the
live edge again, the player will speed up playback to move back toward the
target live offset.
If automatic playback speed adjustment is not desired, it can be disabled by If automatic playback speed adjustment is not desired, it can be disabled by
setting `minPlaybackSpeed` and `maxPlaybackSpeed` to `1.0f`. setting `minPlaybackSpeed` and `maxPlaybackSpeed` properties to `1.0f`.
Similarly, it can be enabled for non-low-latency live streams by setting these
explicitly to values other than `1.0f`. See
[the configuration section above](#configuring-live-playback-parameters) for
more details on how these properties can be set.
## BehindLiveWindowException and ERROR_CODE_BEHIND_LIVE_WINDOW ## ### Customizing the playback speed adjustment algorithm ###
The playback position may fall behind the live window, for example if the player If speed adjustment is enabled, a `LivePlaybackSpeedControl` defines what
is paused or buffering for a long enough period of time. If this happens then adjustments are made. It's possible to implement a custom
playback will fail and an exception with error code `LivePlaybackSpeedControl`, or to customize the default implementation, which is
`ERROR_CODE_BEHIND_LIVE_WINDOW` will be reported via `DefaultLivePlaybackSpeedControl`. In both cases an instance can be set when
`Player.Listener.onPlayerError`. Application code may wish to handle such building the player:
errors by resuming playback at the default position. The [PlayerActivity][] of
the demo app exemplifies this approach.
~~~
@Override
public void onPlayerError(PlaybackException error) {
if (eror.errorCode == PlaybackException.ERROR_CODE_BEHIND_LIVE_WINDOW) {
// Re-initialize player at the current live window default position.
player.seekToDefaultPosition();
player.prepare();
} else {
// Handle other errors.
}
}
~~~
{: .language-java}
## Customizing the playback speed adjustment algorithm ##
To stay close to the target live offset, a `LivePlaybackSpeedControl` is used to
make adjustments to the playback speed during live playbacks. It's possible to
implement a custom `LivePlaybackSpeedControl`, or to customize the default
implementation, which is `DefaultLivePlaybackSpeedControl`. In both cases an
instance can be set when building the player:
~~~ ~~~
ExoPlayer player = ExoPlayer player =
@ -195,6 +182,30 @@ Relevant customization parameters of `DefaultLivePlaybackSpeedControl` are:
a lower value means the estimation will adjust faster at a higher risk of a lower value means the estimation will adjust faster at a higher risk of
running into rebuffers. running into rebuffers.
## BehindLiveWindowException and ERROR_CODE_BEHIND_LIVE_WINDOW ##
The playback position may fall behind the live window, for example if the player
is paused or buffering for a long enough period of time. If this happens then
playback will fail and an exception with error code
`ERROR_CODE_BEHIND_LIVE_WINDOW` will be reported via
`Player.Listener.onPlayerError`. Application code may wish to handle such
errors by resuming playback at the default position. The [PlayerActivity][] of
the demo app exemplifies this approach.
~~~
@Override
public void onPlayerError(PlaybackException error) {
if (eror.errorCode == PlaybackException.ERROR_CODE_BEHIND_LIVE_WINDOW) {
// Re-initialize player at the current live window default position.
player.seekToDefaultPosition();
player.prepare();
} else {
// Handle other errors.
}
}
~~~
{: .language-java}
[Supported Formats page]: {{ site.baseurl }}/supported-formats.html [Supported Formats page]: {{ site.baseurl }}/supported-formats.html
[default UI components]: {{ site.baseurl }}/ui-components.html [default UI components]: {{ site.baseurl }}/ui-components.html
[pending feature request (#2213)]: https://github.com/google/ExoPlayer/issues/2213 [pending feature request (#2213)]: https://github.com/google/ExoPlayer/issues/2213