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

package/docs/reference/shaka-video.md

@@ -0,0 +1,359 @@
+# ShakaVideo
+
+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.
+
+tsx
+
+```
+<ShakaVideo src="https://example.com/manifest.mpd" />
+```
+
+When the URL carries no extension to go on, name the type with `source.type`. That’s what makes an extensionless manifest playable.
+
+tsx
+
+```
+<ShakaVideo 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.
+
+tsx
+
+```
+<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',
+      },
+    },
+  }}
+/>
+```
+
+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
+
+App.tsx
+
+App.css
+
+```
+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;
+}
+```
+
+## API Reference
+
+### Props
+
+Accepts the standard React props for a native `<video>`, plus these Video.js-specific props:
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`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'`
+
+### 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.
+
+tsx
+
+```
+<ShakaVideo
+  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`
+
+### Ref
+
+Forwards its ref to the rendered `<video>`. The ref is an [HTMLVideoElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) and exposes its complete native property and method API.
+
+### Events
+
+Handle standard media events with React event props such as `onPlay` and `onTimeUpdate`. For native events without a React prop, attach a listener through the ref with `addEventListener`.

package/docs/reference/spotify-audio.md

@@ -0,0 +1,188 @@
+# SpotifyAudio
+
+Audio component that plays Spotify tracks, episodes, playlists, and shows through the Spotify embed
+
+Audio component that plays Spotify content through the [Spotify embed](https://developer.spotify.com/documentation/embeds): tracks, episodes, albums, playlists, shows, and artists. Podcast episodes play in full for signed-out listeners; music plays as a preview until the listener logs in to Spotify.
+
+## Load a source
+
+`src` takes an `open.spotify.com` URL for any embeddable entity, including the localized (`/intl-de/`) and already-embedded (`/embed/`) forms, or a `spotify:<type>:<id>` URI. A `t` parameter sets the start position in seconds.
+
+tsx
+
+```
+<SpotifyAudio src="https://open.spotify.com/episode/7makk4oTQel546B0PZlDM5" controls />
+```
+
+## Controls
+
+Spotify’s own chrome is the only UI the embed offers, so `controls` decides whether the element is visible at all. With `controls`, it shows Spotify’s player. Without it, the element hides itself and plays as an invisible transport: a hidden iframe still loads and plays, so a [player skin](../concepts/skins.md)’s buttons drive playback while the embed takes no room on the page.
+
+## Behavior
+
+The Spotify embed exposes less than a native `<audio>` element:
+
+*   No volume and no mute: the embed takes neither command and reports neither value, so a player skin shows no volume controls at all.
+*   No playback rate and no text tracks.
+*   `loop` replays the entity from the top when it ends; without it, the embed continues into whatever Spotify queues next.
+
+## Examples
+
+### Basic Usage
+
+App.tsx
+
+App.css
+
+```
+import { SpotifyAudio } from '@videojs/react/media/spotify-audio';
+
+export default function BasicUsage() {
+  return (
+    <div className="spotify-audio">
+      <SpotifyAudio src="https://open.spotify.com/episode/7makk4oTQel546B0PZlDM5" controls />
+    </div>
+  );
+}
+```
+```
+.spotify-audio {
+  width: 100%;
+  height: 152px;
+}
+```
+
+## API Reference
+
+### Props
+
+Accepts these Video.js-specific props:
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`autoplay`
+
+`boolean`
+
+`false`
+
+`controls`
+
+`boolean`
+
+`false`
+
+`loop`
+
+`boolean`
+
+`false`
+
+`playsInline`
+
+`boolean`
+
+`true`
+
+`poster`
+
+`string`
+
+`''`
+
+`preload`
+
+`MediaPreloadType`
+
+`'metadata'`
+
+`source`
+
+`SpotifySource | null`
+
+`null`
+
+▸
+
+Description
+
+Spotify URL or URI in `src`, plus embed options under `engine.spotify`. Replacing it re-derives `src`.
+
+`src`
+
+`string`
+
+`''`
+
+### Engine options
+
+#### `source.engine.spotify`
+
+Pass [Spotify embed options](https://developer.spotify.com/documentation/embeds) under `source.engine.spotify`, spelled exactly as Spotify spells them, plus anything Spotify adds next. [Media Sources](../concepts/media-sources.md) covers how engine options fit into a structured source.
+
+tsx
+
+```
+<SpotifyAudio
+  source={{
+    src: 'https://open.spotify.com/episode/7makk4oTQel546B0PZlDM5',
+    engine: { spotify: { t: 90, theme: 0 } },
+  }}
+/>
+```
+
+Option
+
+Type
+
+Details
+
+`preferVideo`
+
+`boolean`
+
+▸
+
+Description
+
+Embed the video variant of an episode when it has one. Not a URL parameter: the video embed lives at its own path.
+
+`referrerPolicy`
+
+`ReferrerPolicy`
+
+▸
+
+Description
+
+`referrerpolicy` for the embed iframe. Not a Spotify embed parameter.
+
+`t`
+
+`number`
+
+▸
+
+Description
+
+Start position in seconds.
+
+`theme`
+
+`0`
+
+▸
+
+Description
+
+`0` renders the embed in its dark theme. Defaults to the light theme. Spotify documents no other value, and the embed goes by whether the parameter is there, so leaving it out is the only way to ask for the default.
+
+### Ref
+
+Forwards its ref to the rendered `<iframe>`. The ref is an [HTMLIFrameElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLIFrameElement). Control playback with the component props and player APIs rather than the iframe ref.