@videojs/html 10.0.0-beta.30 → 10.0.0-beta.31

package/docs/reference/shaka-video.md

@@ -0,0 +1,588 @@
+# shaka-video
+
+Video element powered by Shaka Player for DASH, HLS, and progressive playback with DRM
+
+Video element powered by [Shaka Player](https://github.com/shaka-project/shaka-player). One element plays DASH, HLS, and progressive files, and it’s the media component to reach for when you need DRM.
+
+## 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/media/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`
+
+`Target["contentData"] | undefined`
+
+`—`
+
+▸
+
+Description
+
+Read-only.
+
+`engine`
+
+`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`
+
+`ErrorLike | null`
+
+`—`
+
+▸
+
+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`
+
+`ShakaSource | 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; }; ... 15 more ...; useNetworkInformation?: boolean; }`
+
+`abrFactory`
+
+`Factory`
+
+`accessibility`
+
+`object`
+
+▸
+
+Type
+
+`{ handleForcedSubtitlesAutomatically?: boolean; speechToText?: { enabled?: boolean; languagesToTranslate?: string[]; maxTextLength?: number; processLocally?: boolean; }; }`
+
+`adaptationSetCriteriaFactory`
+
+`Factory`
+
+`ads`
+
+`object`
+
+▸
+
+Type
+
+`{ allowPreloadOnDomElements?: boolean; allowStartInMiddleOfInterstitial?: boolean; customPlayheadTracker?: boolean; disableDASHInterstitial?: boolean; disableHLSInterstitial?: boolean; ... 6 more ...; supportsMultipleMediaElements?: boolean; }`
+
+`cmcd`
+
+`object`
+
+▸
+
+Type
+
+`{ contentId?: string; enabled?: boolean; eventTargets?: CmcdTarget[] | null; includeKeys?: string[]; rtpSafetyFactor?: number; sessionId?: string; useHeaders?: boolean; version?: number; }`
+
+`cmsd`
+
+`object`
+
+▸
+
+Type
+
+`{ applyMaximumSuggestedBitrate?: boolean; enabled?: boolean; estimatedThroughputWeightRatio?: number; }`
+
+`drm`
+
+`object`
+
+▸
+
+Type
+
+`{ advanced?: { [x: string]: { audioRobustness?: string[] | null; distinctiveIdentifierRequired?: boolean; headers?: { [x: string]: string | undefined; }; individualizationServer?: string; persistentStateRequired?: boolean; serverCertificate?: Uint8Array<...> | null; serverCertificateUri?: string; sessionType?: strin...`
+
+`ignoreHardwareResolution`
+
+`boolean`
+
+`lcevc`
+
+`object`
+
+▸
+
+Type
+
+`{ drawLogo?: boolean; dynamicPerformanceScaling?: boolean; enabled?: boolean; logLevel?: number; poster?: boolean; }`
+
+`manifest`
+
+`object`
+
+▸
+
+Type
+
+`{ availabilityWindowOverride?: number; continueLoadingWhenPaused?: boolean; dash?: { autoCorrectDrift?: boolean; clockSyncUri?: string; enableFastSwitching?: boolean; ignoreEmptyAdaptationSet?: boolean; ... 8 more ...; xlinkFailGracefully?: boolean; }; ... 15 more ...; updatePeriod?: number; }`
+
+`mediaSource`
+
+`function`
+
+▸
+
+Type
+
+`{ addExtraFeaturesToSourceBuffer?: (a: string) => string; codecSwitchingStrategy?: CodecSwitchingStrategy; correctEc3Enca?: boolean; dispatchAllEmsgBoxes?: boolean; ... 6 more ...; useSourceElements?: boolean; }`
+
+`networking`
+
+`object`
+
+▸
+
+Type
+
+`{ commonAccessTokenHeaderName?: string; forceHTTP?: boolean; forceHTTPS?: boolean; minBytesForProgressEvents?: number; }`
+
+`offline`
+
+`function`
+
+▸
+
+Type
+
+`{ downloadSizeCallback?: (a: number) => Promise<boolean>; numberOfParallelDownloads?: number; progressCallback?: (a: StoredContent, b: number) => any; trackSelectionCallback?: (a: TrackList) => Promise<...>; usePersistentLicense?: boolean; }`
+
+`playRangeEnd`
+
+`number`
+
+`playRangeStart`
+
+`number`
+
+`preferredAudio`
+
+`AudioPreference[]`
+
+`preferredDecodingAttributes`
+
+`string[]`
+
+`preferredText`
+
+`TextPreference[]`
+
+`preferredVideo`
+
+`VideoPreference[]`
+
+`queue`
+
+`object`
+
+▸
+
+Type
+
+`{ preloadNextUrlWindow?: number; preloadPrevItem?: boolean; repeatMode?: RepeatMode; }`
+
+`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; }`
+
+`streaming`
+
+`object`
+
+▸
+
+Type
+
+`{ allowMediaSourceRecoveries?: boolean; avoidEvictionOnQuotaExceededError?: boolean; bufferBehind?: number; bufferingGoal?: number; clampAppendWindowToDuration?: boolean; clearDecodingCache?: boolean; ... 40 more ...; vodDynamicPlaybackRateLowBufferRate?: number; }`
+
+`textDisplayer`
+
+`object`
+
+▸
+
+Type
+
+`{ fontScaleFactor?: number; positionArea?: PositionArea; subtitleDelay?: number; suspendRenderingWhenHidden?: boolean; }`
+
+`textDisplayFactory`
+
+`Factory`
+
+### 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 the live window duration changes. Read \`targetLiveWindow\` 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.