Network and Buffering Configuration
Networking Configuration
Shaka Player has separate network retry settings for each of the different types of requests: manifest, license, and segment requests. For example, you may want a failed license request to be retried differently from a failed segment request.
The three separate retry settings are found under drm.retryParameters
(for
license requests), manifest.retryParameters
(for manifest requests), and
streaming.retryParameters
(for segment requests). All three structures are
identical:
retryParameters: {
timeout: 30000, // timeout in ms, after which we abort
stallTimeout: 5000, // stall timeout in ms, after which we abort
connectionTimeout: 10000, // connection timeout in ms, after which we abort
maxAttempts: 2, // the maximum number of requests before we fail
baseDelay: 1000, // the base delay in ms between retries
backoffFactor: 2, // the multiplicative backoff factor between retries
fuzzFactor: 0.5, // the fuzz factor to apply to each retry delay
}
Each time we retry, the backoff factor is applied to the delay between retries. So, for example, if the base delay is 1s, and the backoff factor is 2:
- initial request at time t = 0 seconds
- delay of 1, retry at t = (0 + 1) = 1
- delay of 2, retry at t = (1 + 2) = 3
- delay of 4, retry at t = (3 + 4) = 7
- delay of 8, retry at t = (7 + 8) = 15
and so on. To avoid many clients hammering a server at the same exact time, we also apply a fuzz factor. A fuzz factor of 0.5 means we fuzz the delay 50% in either direction. So if the ideal delay is 8, the actual delay will be randomly chosen between 4 and 12. To extend our earlier example:
- initial request
- delay of 1±50% (0.5 to 1.5), retry
- delay of 2±50% (1 to 3), retry
- delay of 4±50% (2 to 6), retry
- delay of 8±50% (4 to 12), retry
You should consider the default backoff and fuzz factors as a recommendation of best practice. The base delay, timeout, and maximum number of attempts should be customized for your application's requirements.
Buffering Configuration
Shaka Player's buffering system has three parameters, all of which are nested
under streaming
in the config object: bufferingGoal
, rebufferingGoal
, and
bufferBehind
. All are expressed in seconds.
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.
bufferBehind
is the amount of content we keep in buffer behind the playhead.
For example, if this is 30, we keep 30 seconds of content buffered behind the
video's currentTime
. When we have more than 30 seconds buffered behind,
content will be removed from the start of the buffer to save memory.
This is a minimum; if the stream's max segment size is longer than the
'bufferBehind', then that will be used instead.
NOTES:
rebufferingGoal
should always be less thanbufferingGoal
.- A DASH manifest's
minBufferTime
, if greater, overridesrebufferingGoal
. - You can ignore
minBufferTime
by setting themanifest.dash.ignoreMinBufferTime
configuration to true.
All of these settings should be customized for your application. The default values are very conservative.
Buffering and Adaptation
While we are playing, we will only buffer the currently chosen stream. We do
not download other bitrates until AbrManager tells us to switch. We also (by
default) do not clear the buffer when we adapt. This means that when we adapt
to a different bitrate, it may not be visible for a while because the old
buffer will still be used. There will be at most bufferingGoal
seconds left
of the old bitrate in the buffer.
Try it out
Use the code from Basic Usage and try configuring some of these
parameters in initPlayer()
to see how they affect playback.
Server Considerations
Shaka Player makes a number of requests to various servers while streaming. You need to make sure that Shaka has correct access to those resources. Browsers impose several restrictions on the content that a webpage has access to.
One restriction is CORS (Cross-Origin Resource Sharing). This requires
network requests to be made to the same origin, or for the server to explicitly
give access. An "origin" refers to the domain name (e.g., api.example.com
),
the scheme (e.g., https:
), and the port (e.g., 80). If you host your assets on
a different origin than your web app, then you'll need to set CORS headers on
the asset server to ensure we have access. For some content, this will also
require allowing the Range
header by sending the CORS header
Access-Control-Allow-Headers
.
Another restriction is called mixed-content. If your webpage is accessed using
https:
, then all resources that are loaded also need to be loaded using
https:
. This means that the manifest and all the media segments need to be
loaded using https:
. This can be most easily done by either having all the
URLs in your manifests always use https:
, or by having it not include the
scheme (e.g., //example.com/file.mp4
).