shaka-video

Beta

Video element powered by Shaka Player for DASH, HLS, and progressive playback with DRM

Choose Shaka Player when one media component needs to play DASH, HLS, and progressive files, or when playback requires DRM.

Import

pnpm add @videojs/html @videojs/shaka-video

import '@videojs/html/media/shaka-video';

Or load it from the CDN:

<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-beta.32/media/shaka-video.js"></script>

Load a source

src takes a manifest URL. DASH, HLS, and progressive files all go through the same property, and Shaka picks the parser from the URL.

<shaka-video src="https://example.com/manifest.mpd"></shaka-video>

When the URL carries no extension to go on, name the type with source.type. That’s what makes an extensionless manifest playable.

const video = document.querySelector('shaka-video');
video.source = { src: 'https://example.com/manifest', type: 'application/dash+xml' };

Protected content

source.drm names your license servers, keyed by EME key system id. Name every system you hold a license server for: which one gets negotiated is the browser’s choice.

<ShakaVideo
  source={{
    src: 'https://example.com/manifest.mpd',
    drm: {
      'com.widevine.alpha': { licenseUrl: 'https://example.com/widevine' },
      'com.apple.fps': {
        licenseUrl: 'https://example.com/fairplay',
        serverCertificateUrl: 'https://example.com/fairplay.cer',
      },
    },
  }}
/>

const video = document.querySelector('shaka-video');
video.source = {
  src: 'https://example.com/manifest.mpd',
  drm: {
    'com.widevine.alpha': { licenseUrl: 'https://example.com/widevine' },
    'com.apple.fps': {
      licenseUrl: 'https://example.com/fairplay',
      serverCertificateUrl: 'https://example.com/fairplay.cer',
    },
  },
};

FairPlay needs a serverCertificateUrl unless its CDM is pre-provisioned; Widevine and PlayReady ignore it. source.drm takes the same shape as hls.js’s own drmSystems, so one object describes DRM for either engine.

For the parts of Shaka’s DRM configuration this doesn’t cover, configure Shaka directly. A drm.servers under source.engine.shaka replaces source.drm rather than merging with it.

Behavior

Adaptation stays within renditions no larger than the element rendering them, through Shaka’s abr.restrictToElementSize. Override it under source.engine.shaka.
preload="none" defers the load until playback is asked for; autoplay or a play() counts as asking.
preload="metadata" loads, then holds Shaka’s buffering goals down to a second until preload rises to auto.
streamType is detected from the manifest, so a player skin renders live and on-demand content correctly without being told which it is.
Changing source.engine.shaka reconfigures the running player in place instead of recreating it.

Examples

Basic Usage

import { ShakaVideo } from '@videojs/react/media/shaka-video';

export default function BasicUsage() {
  return <ShakaVideo className="shaka-video" src="https://dash.akamaized.net/akamai/streamroot/050714/Spring_4Ktest.mpd" autoPlay muted playsInline loop />;
}

.shaka-video {
  width: 100%;
  aspect-ratio: 16 / 9;
}

<media-container class="media-container">
  <shaka-video src="https://dash.akamaized.net/akamai/streamroot/050714/Spring_4Ktest.mpd" autoplay muted playsinline loop></shaka-video>
</media-container>

.media-container {
  position: relative;
  display: block;
  width: 100%;
  aspect-ratio: 16 / 9;
}

import '@videojs/html/ui/container';
import '@videojs/html/media/shaka-video';

API Reference

Attributes

Forwards these standard media attributes to the internal <video>. See the MDN media element reference: autopictureinpictureautoplaycontrolscontrolslistcrossorigindisablepictureinpicturedisableremoteplaybackloadingloopmutedplaysinlineposterpreloadsrc

These Video.js-specific attributes configure media behavior:

Attribute	Type	Default	Details
`stream-type`	`MediaStreamType`	`"unknown"`

Properties

Property	Type	Default
`contentData`	`MediaContentData \| undefined`	`—`
Description Read-only.
`engine`	`shaka.Player \| null`	`—`
Description Read-only. Underlying playback engine — the Shaka `Player` instance, or `null` when the browser cannot run it. An advanced escape hatch for direct engine access; normal playback is driven through this element's own properties and methods.
`error`	`unknown`	`—`
Description Read-only. The last playback failure Shaka could not recover from, or `null`. Shaka loads asynchronously, so a manifest that cannot be played fails after `src` was assigned rather than at the assignment; the `error` event is when to read this. A Shaka failure says more about what went wrong than the media element's own `error` does, so it wins while there is one; anything the element failed on by itself still reads through.
`isFullscreen`	`boolean`	`—`
Description Read-only.
`isPictureInPicture`	`boolean`	`—`
Description Read-only.
`liveEdgeStart`	`number`	`—`
Description Read-only.
`preload`	`MediaPreloadType`	`'metadata'`
Description How much to fetch before playback is asked for, mirroring the media element's own `preload`. Shaka has no split between "know the source" and "buffer it", so this maps onto when and how `engine.load()` runs: `'auto'` — load immediately with the configured buffering goals. `'metadata'` — load immediately, holding buffering to about a segment; the configured goals come back on the first play intent. `'none'` / `''` — hold the load entirely until the first play intent. A play intent is a `play` event, a target that is already playing, or `autoplay` — which the spec lets override `preload` for good reason: with nothing fetched there is nothing whose readiness could ever fire it. Widening (`none` → `auto`) takes effect immediately; narrowing after a load began cannot un-fetch and leaves it alone.
`source`	`{ src?: string; type?: string; drm?: DrmSystemsConfig; engine?: ShakaEngineConfig } \| null`	`null`
Description Structured source: what to play (`src`, an optional `type`) plus how to play it (`drm`, `engine.shaka`). Replacing it re-derives `src`. Shaka takes configuration on a live player, so changing `engine.shaka` re-applies it in place instead of recreating the engine.
`src`	`string`	`''`
`streamType`	`MediaStreamType`	`"unknown"`
`targetLiveWindow`	`number`	`—`
Description Read-only.
`webkitCurrentPlaybackTargetIsWireless`	`boolean \| undefined`	`—`
Description Read-only.
`webkitPresentationMode`	`WebKitPresentationMode \| undefined`	`—`
Description Read-only.
`webkitSetPresentationMode`	`((mode: WebKitPresentationMode) => void) \| undefined`	`—`
Description Read-only.

Also exposes these properties from the native media API. See HTMLVideoElement for details: autoplaybufferedcontrolscrossOrigincurrentSrccurrentTimedefaultMuteddefaultPlaybackRatedisablePictureInPicturedisableRemotePlaybackdurationendedloopmutedpausedplaybackRateplayedplaysInlineposterreadyStateremoteseekableseekingtextTrackstitlevideoHeightvideoWidthvolume

Engine options

`source.engine.shaka`

Pass Shaka Player’s own configuration here. It’s handed to Shaka untouched, so every option in its configuration reference works, spelled the way Shaka spells it. Replacing the object resets any configuration applied before it. Media Sources covers how engine options fit into a structured source.

Each entry below is a group of Shaka settings rather than a single value, and Shaka documents what’s inside them. The names and types come from Shaka’s own type definitions.

const video = document.querySelector('shaka-video');
video.source = {
  src: 'https://example.com/manifest.mpd',
  engine: { shaka: { streaming: { bufferingGoal: 30 } } },
};

Option	Type	Details
`abr`	`object`
Type { advanced?: { droppedFramesBanDuration?: number; droppedFramesInterval?: number; droppedFramesThreshold?: number; fastHalfLife?: number; minBytes?: number; minTotalBytes?: number; slowHalfLife?: number }; bandwidthDowngradeTarget?: number; bandwidthUpgradeTarget?: number; cacheLoadThreshold?: number; clearBufferSwitch?: boolean; defaultBandwidthEstimate?: number; droppedFrames?: boolean; enabled?: boolean; ignoreDevicePixelRatio?: boolean; minTimeToSwitch?: number; preferNetworkInformationBandwidth?: boolean; restrictToElementSize?: boolean; restrictToScreenSize?: boolean; restrictions?: { maxBandwidth?: number; maxChannelsCount?: number; maxFrameRate?: number; maxHeight?: number; maxPixels?: number; maxWidth?: number; minBandwidth?: number; minChannelsCount?: number; minFrameRate?: number; minHeight?: number; minPixels?: number; minWidth?: number }; safeMarginSwitch?: number; switchInterval?: number; useNetworkInformation?: boolean } \| undefined
`abrFactory`	`undefined \| function`
Type `(() => shaka.extern.AbrManager) \| undefined`
`accessibility`	`object`
Type `{ handleForcedSubtitlesAutomatically?: boolean; speechToText?: { enabled?: boolean; languagesToTranslate?: string[]; maxTextLength?: number; processLocally?: boolean } } \| undefined`
`adaptationSetCriteriaFactory`	`undefined \| function`
Type `(() => shaka.extern.AdaptationSetCriteria) \| undefined`
`ads`	`object`
Type `{ allowPreloadOnDomElements?: boolean; allowStartInMiddleOfInterstitial?: boolean; customPlayheadTracker?: boolean; disableDASHInterstitial?: boolean; disableHLSInterstitial?: boolean; disablePlayedLinearAdSkip?: boolean; disableSnapback?: boolean; disableTrackingEvents?: boolean; disableTrackingForPlayedLinearAds?: boolean; interstitialPreloadAheadTime?: number; skipPlayDetection?: boolean; supportsMultipleMediaElements?: boolean } \| undefined`
`cmcd`	`object`
Type `{ contentId?: string; enabled?: boolean; eventTargets?: shaka.extern.CmcdTarget[] \| null; includeKeys?: string[]; rtpSafetyFactor?: number; sessionId?: string; useHeaders?: boolean; version?: number } \| undefined`
`cmsd`	`object`
Type `{ applyMaximumSuggestedBitrate?: boolean; enabled?: boolean; estimatedThroughputWeightRatio?: number } \| undefined`
`drm`	`object`
Type { advanced?: object \| null; clearKeys?: object; defaultAudioRobustnessForWidevine?: string; defaultVideoRobustnessForWidevine?: string; delayLicenseRequestUntilPlayed?: boolean; failureCallback?: ((a: shaka.util.Error) => any); ignoreDuplicateInitData?: boolean; initDataTransform?: ((a: Uint8Array, b: string, c: shaka.extern.DrmInfo \| null) => Uint8Array); keySystemsMapping?: object; logLicenseExchange?: boolean; minHdcpVersion?: string; parseInbandPsshEnabled?: boolean; persistentSessionOnlinePlayback?: boolean; persistentSessionsMetadata?: shaka.extern.PersistentSessionMetadata[]; preferredKeySystems?: string[]; renewalIntervalSec?: number; retryParameters?: { backoffFactor?: number; baseDelay?: number; connectionTimeout?: number; fuzzFactor?: number; maxAttempts?: number; stallTimeout?: number; timeout?: number }; servers?: object; updateExpirationTime?: number } \| undefined
`ignoreHardwareResolution`	`boolean \| undefined`
`lcevc`	`object`
Type `{ drawLogo?: boolean; dynamicPerformanceScaling?: boolean; enabled?: boolean; logLevel?: number; poster?: boolean } \| undefined`
`manifest`	`object`
Type { availabilityWindowOverride?: number; continueLoadingWhenPaused?: boolean; dash?: { autoCorrectDrift?: boolean; clockSyncUri?: string; enableFastSwitching?: boolean; ignoreEmptyAdaptationSet?: boolean; ignoreMaxSegmentDuration?: boolean; ignoreMinBufferTime?: boolean; ignoreSuggestedPresentationDelay?: boolean; initialSegmentLimit?: number; keySystemsByURI?: object; manifestPreprocessorTXml?: ((a: shaka.extern.xml.Node) => any); sequenceMode?: boolean; useStreamOnceInPeriodFlattening?: boolean; xlinkFailGracefully?: boolean }; defaultPresentationDelay?: number; disableAudio?: boolean; disableChapters?: boolean; disableIFrames?: boolean; disableText?: boolean; disableThumbnails?: boolean; disableVideo?: boolean; enableAudioGroups?: boolean; hls?: { allowLowLatencyByteRangeOptimization?: boolean; allowRangeRequestsToGuessMimeType?: boolean; chaptersUri?: string; defaultAudioCodec?: string; defaultVideoCodec?: string; disableClosedCaptionsDetection?: boolean; disableCodecGuessing?: boolean; ignoreImageStreamFailures?: boolean; ignoreManifestProgramDateTime?: boolean; ignoreManifestProgramDateTimeForTypes?: string[]; ignoreManifestTimestampsInSegmentsMode?: boolean; ignoreTextStreamFailures?: boolean; liveSegmentsDelay?: number; mediaPlaylistFullMimeType?: string; sequenceMode?: boolean }; ignoreDrmInfo?: boolean; ignoreSupplementalCodecs?: boolean; msf?: { authorizationToken?: string; catalogPreprocessor?: ((a: any) => any); fingerprintUri?: string; namespaces?: string[]; subscribeFilterType?: shaka.config.MsfFilterType; useFetchCatalog?: boolean; version?: shaka.config.MsfVersion }; raiseFatalErrorOnManifestUpdateRequestFailure?: boolean; retryParameters?: { backoffFactor?: number; baseDelay?: number; connectionTimeout?: number; fuzzFactor?: number; maxAttempts?: number; stallTimeout?: number; timeout?: number }; segmentRelativeVttTiming?: boolean; updatePeriod?: number } \| undefined
`mediaSource`	`object`
Type `{ addExtraFeaturesToSourceBuffer?: ((a: string) => string); codecSwitchingStrategy?: shaka.config.CodecSwitchingStrategy; correctEc3Enca?: boolean; dispatchAllEmsgBoxes?: boolean; durationReductionEmitsUpdateEnd?: boolean; forceTransmux?: boolean; insertFakeEncryptionInInit?: boolean; modifyCueCallback?: ((a: shaka.text.Cue, b: string \| null, c: shaka.extern.TextParser.TimeContext) => any); repairIFrames?: boolean; transmuxWorkerUrl?: string; useSourceElements?: boolean } \| undefined`
`networking`	`object`
Type `{ commonAccessTokenHeaderName?: string; forceHTTP?: boolean; forceHTTPS?: boolean; minBytesForProgressEvents?: number } \| undefined`
`offline`	`object`
Type `{ downloadSizeCallback?: ((a: number) => Promise<boolean>); numberOfParallelDownloads?: number; progressCallback?: ((a: shaka.extern.StoredContent, b: number) => any); trackSelectionCallback?: ((a: shaka.extern.TrackList) => Promise<shaka.extern.TrackList>); usePersistentLicense?: boolean } \| undefined`
`playRangeEnd`	`number \| undefined`
`playRangeStart`	`number \| undefined`
`preferredAudio`	`shaka.extern.AudioPreference[] \| unde...`
Type `shaka.extern.AudioPreference[] \| undefined`
`preferredDecodingAttributes`	`string[] \| undefined`
`preferredText`	`shaka.extern.TextPreference[] \| undef...`
Type `shaka.extern.TextPreference[] \| undefined`
`preferredVideo`	`shaka.extern.VideoPreference[] \| unde...`
Type `shaka.extern.VideoPreference[] \| undefined`
`queue`	`object`
Type `{ preloadNextUrlWindow?: number; preloadPrevItem?: boolean; repeatMode?: shaka.config.RepeatMode } \| undefined`
`restrictions`	`object`
Type `{ maxBandwidth?: number; maxChannelsCount?: number; maxFrameRate?: number; maxHeight?: number; maxPixels?: number; maxWidth?: number; minBandwidth?: number; minChannelsCount?: number; minFrameRate?: number; minHeight?: number; minPixels?: number; minWidth?: number } \| undefined`
`streaming`	`object`
Type { allowMediaSourceRecoveries?: boolean; avoidEvictionOnQuotaExceededError?: boolean; bufferBehind?: number; bufferingGoal?: number; clampAppendWindowToDuration?: boolean; clearDecodingCache?: boolean; crossBoundaryStrategy?: shaka.config.CrossBoundaryStrategy; disableAudioPrefetch?: boolean; disableTextPrefetch?: boolean; disableVideoPrefetch?: boolean; dontChooseCodecs?: boolean; durationBackoff?: number; evictionGoal?: number; failureCallback?: ((a: shaka.util.Error) => any); gapDetectionThreshold?: number; gapJumpTimerTime?: number; gapPadding?: number; ignoreTextStreamFailures?: boolean; inaccurateManifestTolerance?: number; liveSync?: { dynamicTargetLatency?: { enabled?: boolean; maxAttempts?: number; maxLatency?: number; minLatency?: number; rebufferIncrement?: number; stabilityThreshold?: number }; enabled?: boolean; maxPlaybackRate?: number; minPlaybackRate?: number; panicMode?: boolean; panicThreshold?: number; targetLatency?: number; targetLatencyTolerance?: number }; loadTimeout?: number; lowLatencyMode?: boolean; maxDisabledTime?: number; minTimeBetweenRecoveries?: number; observeQualityChanges?: boolean; preferNativeDash?: boolean; preferNativeHls?: boolean; prefetchAudioLanguages?: string[]; preloadNextUrlWindow?: number; processSrcEqualMetadata?: boolean; rebufferingGoal?: number; retryParameters?: { backoffFactor?: number; baseDelay?: number; connectionTimeout?: number; fuzzFactor?: number; maxAttempts?: number; stallTimeout?: number; timeout?: number }; returnToEndOfLiveWindowWhenOutside?: boolean; safeSeekEndOffset?: number; safeSeekOffset?: number; segmentPrefetchLimit?: number; shouldFixTimestampOffset?: boolean; stallEnabled?: boolean; stallSkip?: number; stallThreshold?: number; startAtSegmentBoundary?: boolean; stopFetchingOnPause?: boolean; updateIntervalSeconds?: number; useNativeHlsForFairPlay?: boolean; vodDynamicPlaybackRate?: boolean; vodDynamicPlaybackRateBufferRatio?: number; vodDynamicPlaybackRateLowBufferRate?: number } \| undefined
`textDisplayer`	`object`
Type `{ fontScaleFactor?: number; positionArea?: shaka.config.PositionArea; subtitleDelay?: number; suspendRenderingWhenHidden?: boolean } \| undefined`
`textDisplayFactory`	`undefined \| function`
Type `((a: shaka.Player) => shaka.extern.TextDisplayer) \| undefined`

Methods

Supports these media methods. See HTMLVideoElement for details: addTextTrackcanPlayTypeexitFullscreenexitPictureInPictureloadpauseplayrequestFullscreenrequestPictureInPicture

Events

Re-dispatches these standard media events from the internal media element: abortaddtrackcanplaycanplaythroughchangecontentdatachangedurationchangeemptiedendedenterpictureinpictureleavepictureinpictureloadeddataloadedmetadataloadstartpauseplayplayingprogressratechangeremovetrackresizeseekedseekingstalledsuspendtimeupdatevolumechangewaiting

Also emits these Video.js-specific events:

Event	Description
`error`	Fired when playback fails in a way Shaka could not recover from. Read `error` for the failure.
`sourcechange`	Fired when `source` changes, either directly or by resolving a new `src`. Read `source` for the new value.
`streamtypechange`	Fired when the detected stream type changes. Read `streamType` for the new value.
`targetlivewindowchange`	Fired when `targetLiveWindow` changes. Read it for the new value.

CSS custom properties

Variable	Details
`--media-video-border-radius`
Description Border radius of the video element.
`--media-object-fit`
Description Object fit for the video.
`--media-object-position`
Description Object position for the video.
`--media-caption-track-duration`
Description Duration of the caption track transition.
`--media-caption-track-delay`
Description Delay before the caption track transition.
`--media-caption-track-y`
Description Vertical offset of the caption track.