Document ABR and Streaming Behavior

[robwalch]

I'm looking for answers to these questions to better understand playback start time and adaptive bitrate switching in shaka. I've made a few assumptions from the configuration docs. Can you confirm these and provide some answers to the unknowns?

1. How much is buffered before playback starts (minimum time or size buffered)?
   Answer: Approximately 2-30 seconds; between the streaming rebufferingGoal* and bufferingGoal.
   *A DASH manifest's minBufferTime, if greater, overrides rebufferingGoal
2. What conditions trigger an adaptive up or down switch?
   Answer: (logic is the same for up and down)
   1. Bandwidth estimator has a good estimate (at least 128kB of media has been loaded - https://github.com/google/shaka-player/blob/master/lib/abr/ewma_bandwidth_estimator.js#L69)
   2. At least 8 seconds has past since the last switch (or playback start?)
   3. Another video quality's min and max bitrate requirements better match the current estimate.
      Note: in the case of multiple audio qualities, the middle quality is always selected.
3. How far ahead of the current playhead are new qualities requested and appended?
   Don't know. How much previously buffered media replaced - as much or as little as possible?
4. Can an adaptive bitrate/quality change occur before playback begins?
   Don't know. Revise answers to last two questions.
5. What changes in v2.0.1 where made to improve playback start and ABR performance?
   Answer: Bandwidth estimator sampling rate increased... (need more specifics on timing and bytes evaluated)
6. What configuration options can be used to modify ABR behavior?
   Answer: These are the defaults

 abr: {
   defaultBandwidthEstimate: 500000,
   enabled: true, // True when "Auto" level is selected in JW Player
   manager: SimpleAbrManager,
 },
 streaming: {
   bufferBehind: 30,
   bufferingGoal: 30, // Changed to 10 in v2.0.1
   ignoreTextStreamFailures: false,
   rebufferingGoal: 2,
   retryParameters: {
     maxAttempts: 2,
     baseDelay: 1E3,
     backoffFactor: 2,
     fuzzFactor: .5,
     timeout: 0,
   }
 }

See:
http://shaka-player-demo.appspot.com/docs/api/tutorial-config.html
http://shaka-player-demo.appspot.com/docs/api/shakaExtern.html#AbrConfiguration

defaultBandwidthEstimate number The default bandwidth estimate to use if there is not enough data, in bit/sec.

http://shaka-player-demo.appspot.com/docs/api/tutorial-network-and-buffering-config.html

bufferingGoal is the amount of content we try to buffer. For example, if this is set to 30, we fetch segments until we have at least 30 seconds buffered.

rebufferingGoal is the amount of content we have to have buffered before we can play. For example, if this is 15, we stay in a buffering state until we have at least 15 seconds buffered. This affects both buffering at startup and rebuffering later during playback.

NOTE: A DASH manifest's minBufferTime, if greater, overrides rebufferingGoal.

http://shaka-player-demo.appspot.com/docs/api/lib_abr_simple_abr_manager.js.html#line69

SimpleAbrManager.SWITCH_INTERVAL_MS = 8000
The minimum amount of time that must pass between switches, in milliseconds.
This keeps us from changing too often and annoying the user.

SimpleAbrManager.BANDWIDTH_UPGRADE_TARGET_ = 0.85
The fraction of the estimated bandwidth which we should try to use when upgrading.

SimpleAbrManager.BANDWIDTH_DOWNGRADE_TARGET_ = 0.95
The largest fraction of the estimated bandwidth we should use. We should downgrade to avoid this.

Thank you!

[joeyparrish]

How far ahead of the current playhead are new qualities requested and appended?
Don't know. How much previously buffered media replaced - as much or as little as possible?

ABR will never cause content already in buffer to be replaced. We used to remove data ahead of the playhead to make ABR decisions visible sooner, but this created a bad user experience on some platforms.

Can an adaptive bitrate/quality change occur before playback begins?
Don't know. Revise answers to last two questions.

Yes. If autoplay is disabled, playback will not begin until the user clicks play. During buffering, the bandwidth estimate is built, and can trigger an ABR decision. As stated above, that decision will not cause anything to be removed. So the first segment at least will be at the initial resolution.

@TheModMaker is working on additions and changes to our docs to help explain ABR better. Thanks!

[TheModMaker]

I just pushed a change that adds more docs to help. Here are the answers to your questions:

How much is buffered before playback starts (minimum time or size buffered)?

rebufferingGoal or MPD@minBufferTime, whichever is larger.

What conditions trigger an adaptive up or down switch?

When a segment is downloaded, SimpleAbrManager will decide if a better (higher bitrate) stream is playable based on the current network bandwidth estimate. It will wait some time between switches to avoid switching back and forth a lot.

This also changed recently to support HLS. Before audio and video were selected separately. Now, there are audio/video pairs called variants. AbrManager will select the best variant it thinks can be played.

How far ahead of the current playhead are new qualities requested and appended?

As Joey said, we don't fetch other streams, only the one that is currently playing. Once AbrManager decides we need to switch, we will start downloading that quality. However, since we don't clear the buffer, the old content will play until the playhead gets to the new content. This will be less than bufferingGoal seconds long.

What configuration options can be used to modify ABR behavior?

There aren't many options to affect ABR directly. In v2.1, you can pass a restrictions object to restrict decisions by AbrManager based on video size, bandwidth, etc.. You can also specifiy the defaultBandwidthEstimate to tell AbrManager what initial streams it should choose.

There are several streaming parameters that affect buffering. bufferingGoal specifies how much we will buffer ahead of the playhead (and indirectly affects how much of the old bitrate we will play). rebufferingGoal specifies how much to buffer if we enter a buffering state (or at startup).

[TheModMaker]

@robwalch Does this answer all your questions? Is there anything else we can do?

[robwalch]

Yes thanks @TheModMaker!

[raskri]

Is there a way to make bufferingGoal override the manifests minBufferTime? In my manifest it is set to minBufferTime = 10 sec. Which always makes my player wait for about 10 sec, and then it plays. But I get the first "image" of the stream right away.

[TheModMaker]

@raskri It is best to start a new issue, not to resurrect old threads. Also questions may be better suited in the mailing list.

But to answer your question, there is no way to override the minBufferTime. If the manifest specifies that it needs 10 seconds to play smoothly, then we will keep 10 seconds buffered. Requiring 10 seconds of buffer doesn't mean that playback will be delayed by 10 seconds, only that we will wait until we have downloaded 10 seconds of content before starting.

[joeyparrish]

@TheModMaker, that's not entirely accurate. You can override the manifest's minBufferTime, but only with a larger value. We will buffer at least the manifest's minBufferTime or the configured value of streaming.rebufferingGoal, whichever is larger.