@videojs/html 10.0.0-rc.2 → 10.0.0-rc.4

package/docs/reference/shaka-video.md

@@ -1,642 +0,0 @@
-# shaka-video
-
-Beta
-
-Video element powered by Shaka Player for DASH, HLS, and progressive playback with DRM
-
-Choose [Shaka Player](https://github.com/shaka-project/shaka-player) when one media component needs to play DASH, HLS, and progressive files, or when playback requires DRM.
-
-## Import
-
-bash
-
-```
-pnpm add @videojs/shaka-video
-```
-
-ts
-
-```
-import '@videojs/html/media/shaka-video';
-```
-
-Or load it from the [CDN](../concepts/cdn.md):
-
-html
-
-```
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.2/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.
-
-html
-
-```
-<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.
-
-ts
-
-```
-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](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/requestMediaKeySystemAccess). Name every system you hold a license server for: which one gets negotiated is the browser’s choice.
-
-ts
-
-```
-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
-
-index.html
-
-index.css
-
-index.ts
-
-```
-<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](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video): `autopictureinpicture``autoplay``controls``controlslist``crossorigin``disablepictureinpicture``disableremoteplayback``loading``loop``muted``playsinline``poster``preload``src`
-
-These Video.js-specific attributes configure media behavior:
-
-Attribute
-
-Type
-
-Default
-
-Details
-
-`stream-type`
-
-`MediaStreamType`
-
-`"unknown"`
-
-### Properties
-
-Property
-
-Type
-
-Default
-
-Details
-
-`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](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) for details: `autoplay``buffered``controls``crossOrigin``currentSrc``currentTime``defaultMuted``defaultPlaybackRate``disablePictureInPicture``disableRemotePlayback``duration``ended``loop``muted``paused``playbackRate``played``playsInline``poster``readyState``remote``seekable``seeking``textTracks``title``videoHeight``videoWidth``volume`
-
-### 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](https://shaka-player-demo.appspot.com/docs/api/tutorial-config.html) works, spelled the way Shaka spells it. Replacing the object resets any configuration applied before it. [Media Sources](../concepts/media-sources.md) 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.
-
-ts
-
-```
-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](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) for details: `addTextTrack``canPlayType``exitFullscreen``exitPictureInPicture``load``pause``play``requestFullscreen``requestPictureInPicture`
-
-### Events
-
-Re-dispatches these standard media events from the internal media element: `abort``addtrack``canplay``canplaythrough``change``contentdatachange``durationchange``emptied``ended``enterpictureinpicture``leavepictureinpicture``loadeddata``loadedmetadata``loadstart``pause``play``playing``progress``ratechange``removetrack``resize``seeked``seeking``stalled``suspend``timeupdate``volumechange``waiting`
-
-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.