Shaka Player Upgrade Guide
If you are upgrading from v1 or v2, these releases are no longer supported, and upgrade guides are no longer maintained. You can use these old upgrades guides to upgrade in stages:
Since v3.0, Shaka Player has been following semantic versioning. (The IE11 deprecation announced before v3.0 happened in v3.1, which technically breaks semantic versioning guarantees. It is the only intentional exception.)
Upgrading from any v3 release to a newer v3 release should be backward compatible. The same is true of all major version numbers (v4 => v4, etc).
Here is a summary of breaking changes that might require upgrades to your application:
v3.1
-
New dependencies:
- TextDecoder/TextEncoder platform support or polyfill required (affects Xbox One, but not evergreen browsers); we suggest the polyfill https://github.com/anonyco/FastestSmallestTextEncoderDecoder Fallback included by default in v4.2
-
Support removed:
- IE11 support removed
v4.0
-
Support removed:
- Older TVs and set-top boxes that do not support MediaSource sequence mode can no longer play HLS content (since we now use sequence mode for that)
- Support for iOS 12 and Safari 12 has been removed
-
Configuration changes:
manifest.dash.defaultPresentationDelay
has been replaced bymanifest.defaultPresentationDelay
(deprecated in v3.0.0)- Configuration of factories should be plain factory functions, not
constructors; these will not be invoked with
new
(deprecated in v3.1.0) drm.initDataTransform
now defaults to a no-opstreaming.smallGapLimit
andstreaming.jumpLargeGaps
have been removed; all gaps will now be jumpedmanifest.hls.useFullSegmentsForStartTime
has been removed; this setting is no longer necessary, as we no longer fetch segments for start times in the HLS parser
-
Player API changes:
shaka.Player.prototype.addTextTrack()
has been replaced byaddTextTrackAsync()
, which returns aPromise
(deprecated in v3.1.0)
-
UI API changes:
shaka.ui.TrackLabelFormat
has been renamed toshaka.ui.Overlay.TrackLabelFormat
(deprecated in v3.1.0)shaka.ui.FailReasonCode
has been renamed toshaka.ui.Overlay.FailReasonCode
(deprecated in v3.1.0)
-
Offline API changes:
shaka.offline.Storage.prototype.store()
returnsAbortableOperation
instead ofPromise
; callers should change.then()
to.promise.then()
andawait rv
toawait rv.promise
(deprecated in v3.0.0)shaka.offline.Storage.prototype.getStoreInProgress()
has been removed; concurrent operations are supported since v3, so callers don't need to check this (deprecated in v3.0.0)
-
Utility API changes:
shaka.util.Uint8ArrayUtils.equal
has been replaced byshaka.util.BufferUtils.equal
, which can handle multiple types of buffers (deprecated in v3.0.0)
-
Manifest API changes:
shaka.media.SegmentIndex.prototype.destroy()
has been replaced byrelease()
, which is synchronous (deprecated in v3.0.0)shaka.media.SegmentIterator.prototype.seek()
, which mutates the iterator, has been replaced byshaka.media.SegmentIndex.getIteratorForTime()
(deprecated in v3.1.0)shaka.media.SegmentIndex.prototype.merge()
has become private; usemergeAndEvict()
instead (deprecated in v3.2.0)
-
Plugin changes:
AbrManager
plugins must implement theplaybackRateChanged()
method (deprecated in v3.0.0)shaka.extern.Cue.prototype.spacer
has been replaced by the more clearly-namedlineBreak
(deprecated in v3.1.0)IUIElement
plugins must have arelease()
method (notdestroy()
) (deprecated in v3.0.0)
v5.0 (unreleased)
-
Configuration changes:
streaming.forceTransmuxTS
has been renamed tostreaming.forceTransmux
(deprecated in v4.3.0)manifest.dash.manifestPreprocessor
andmanifest.mss.manifestPreprocessor
have been replaced withmanifest.dash.manifestPreprocessorTXml
andmanifest.mss.manifestPreprocessorTXml
callbacks. This new callbacks now acceptshaka.externs.xml.Node
.getAttribute()
andtextContent
results must now be decoded if they might contain escape sequences. You can useshaka.util.StringUtils.htmlUnescape
for this purpose.streaming.useNativeHlsOnSafari
has removed. Now we have another config to do the same for FairPlaystreaming.useNativeHlsForFairPlay
or for HLS (any browser)streaming.preferNativeHls
.mediaSource.sourceBufferExtraFeatures
has been replaced withmediaSource.addExtraFeaturesToSourceBuffer
callback.streaming.liveSyncMinLatency
andstreaming.liveSyncMaxLatency
have been removed in favor ofstreaming.liveSync.targetLatency
. (deprecated in v4.10.0)- The following options on
streaming
have been removed:liveSync
,liveSyncTargetLatency
,liveSyncTargetLatencyTolerance
,liveSyncPlaybackRate
,liveSyncMinPlaybackRate
,liveSyncPanicMode
liveSyncPanicThreshold
.streaming.liveSync
is now an options object with the relevant options:enabled
,targetLatency
,targetLatencyTolerance
,maxPlaybackRate
,minPlaybackRate
,panicMode
panicThreshold
. (deprecated in v4.10.0) useSafariBehaviorForLive
has been removed.
-
Plugin changes:
TextDisplayer
plugins must implement theconfigure()
method.TextParser
plugins must implement thesetManifestType()
andsetSequenceMode()
methods.Transmuxer
plugins now has three new parameters intransmux()
method.
-
Player API Changes:
- The constructor no longer takes
mediaElement
as a parameter; use theattach
method to attach to a media element instead. (Deprecated in v4.6) - The
TimelineRegionInfo.eventElement
has been replaced withTimelineRegionInfo.eventNode
property, the new property type isshaka.externs.xml.Node
instead ofElement
- The constructor no longer takes