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

package/docs/reference/hlsjs-video.md

@@ -0,0 +1,726 @@
+# HlsJsVideo
+
+HLS video element powered by hls.js for adaptive bitrate streaming
+
+HLS video element powered by [hls.js](https://github.com/video-dev/hls.js/) for adaptive bitrate streaming. It’s the recommended choice for HLS playback: full feature support across every browser. For alternatives, see [NativeHlsVideo](/docs/framework/html/reference/native-hls-video/) (browser-native HLS) or [HlsVideo](/docs/framework/html/reference/hls-video/) (lightweight HLS).
+
+## Examples
+
+### Basic Usage
+
+App.tsx
+
+App.css
+
+```
+import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
+
+export default function BasicUsage() {
+  return <HlsJsVideo className="hlsjs-video" src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" autoPlay muted playsInline loop />;
+}
+```
+```
+.hlsjs-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`
+
+`PreloadType`
+
+`'metadata'`
+
+▸
+
+Description
+
+Preload type (`'none'` / `'metadata'` / `'auto'`).
+
+`source`
+
+`HlsSource | null`
+
+`null`
+
+▸
+
+Description
+
+Structured source: what to play (`src`, an optional `type`) plus how to play it (`preferPlayback`, `engine`). Assigning it derives `src`.
+
+Sources are compared structurally, so reassigning an equivalent object — an inline React prop, for instance — is a no-op. Only a change to the engine options (or to the resolved content type) recreates the playback engine.
+
+`src`
+
+`string`
+
+`''`
+
+▸
+
+Description
+
+Media source URL. Assigning it replaces the identity half of `source` and leaves `type` and the engine options intact, so changing the URL never disturbs engine configuration.
+
+`streamType`
+
+`StreamType`
+
+`'unknown'`
+
+▸
+
+Description
+
+Current stream type (`'on-demand'` / `'live'` / `'unknown'`).
+
+### Engine options
+
+#### `source.engine.hlsJs`
+
+Pass hls.js’s own configuration here. It’s handed to hls.js untouched, so every option in its [config reference](https://github.com/video-dev/hls.js/blob/master/docs/API.md#fine-tuning) works, spelled the way hls.js spells it. [Media Sources](../concepts/media-sources.md) covers how engine options fit into a structured source.
+
+The names and types below come from hls.js’s own type definitions, so they tell you what exists and what shape it takes. hls.js documents what each one does; the descriptions are theirs to write, and most are blank here because its types carry none.
+
+tsx
+
+```
+<HlsJsVideo
+  source={{
+    src: 'https://example.com/playlist.m3u8',
+    engine: { hlsJs: { maxBufferLength: 30, lowLatencyMode: true } },
+  }}
+/>
+```
+
+Option
+
+Type
+
+Details
+
+`abrBandWidthFactor`
+
+`number`
+
+`abrBandWidthUpFactor`
+
+`number`
+
+`abrController`
+
+`typeof AbrController`
+
+`abrEwmaDefaultEstimate`
+
+`number`
+
+▸
+
+Description
+
+Default bandwidth estimate in bits/s prior to collecting fragment bandwidth samples
+
+`abrEwmaDefaultEstimateMax`
+
+`number`
+
+`abrEwmaFastLive`
+
+`number`
+
+`abrEwmaFastVoD`
+
+`number`
+
+`abrEwmaSlowLive`
+
+`number`
+
+`abrEwmaSlowVoD`
+
+`number`
+
+`abrMaxWithRealBitrate`
+
+`boolean`
+
+`appendErrorMaxRetry`
+
+`number`
+
+`assetPlayerId`
+
+`string`
+
+`audioPreference`
+
+`AudioSelectionOption`
+
+`audioStreamController`
+
+`typeof AudioStreamController`
+
+`audioTrackController`
+
+`typeof AudioTrackController`
+
+`autoStartLoad`
+
+`boolean`
+
+`backBufferLength`
+
+`number`
+
+`bufferController`
+
+`typeof BufferController`
+
+`capLevelController`
+
+`typeof CapLevelController`
+
+`capLevelOnFPSDrop`
+
+`boolean`
+
+`capLevelToPlayerSize`
+
+`boolean`
+
+`captionsTextTrack1Label`
+
+`string`
+
+`captionsTextTrack1LanguageCode`
+
+`string`
+
+`captionsTextTrack2Label`
+
+`string`
+
+`captionsTextTrack2LanguageCode`
+
+`string`
+
+`captionsTextTrack3Label`
+
+`string`
+
+`captionsTextTrack3LanguageCode`
+
+`string`
+
+`captionsTextTrack4Label`
+
+`string`
+
+`captionsTextTrack4LanguageCode`
+
+`string`
+
+`certLoadPolicy`
+
+`LoadPolicy`
+
+`cmcd`
+
+`CMCDControllerConfig`
+
+`cmcdController`
+
+`typeof CMCDController`
+
+`contentSteeringController`
+
+`typeof ContentSteeringController`
+
+`cueHandler`
+
+`CuesInterface`
+
+`debug`
+
+`boolean | ILogger`
+
+`defaultAudioCodec`
+
+`string`
+
+`detectStallWithCurrentTimeMs`
+
+`number`
+
+`drmSystemOptions`
+
+`DRMSystemOptions | undefined`
+
+`drmSystems`
+
+`Partial<Record<KeySystems, DRMSystemC...`
+
+▸
+
+Type
+
+`Partial<Record<KeySystems, DRMSystemConfiguration>> | undefined`
+
+`emeController`
+
+`typeof EMEController`
+
+`emeEnabled`
+
+`boolean`
+
+`enableCEA708Captions`
+
+`boolean`
+
+`enableDateRangeMetadataCues`
+
+`boolean`
+
+`enableEmsgKLVMetadata`
+
+`boolean`
+
+`enableEmsgMetadataCues`
+
+`boolean`
+
+`enableID3MetadataCues`
+
+`boolean`
+
+`enableIMSC1`
+
+`boolean`
+
+`enableInterstitialPlayback`
+
+`boolean`
+
+`enableSoftwareAES`
+
+`boolean`
+
+`enableWebVTT`
+
+`boolean`
+
+`enableWorker`
+
+`boolean`
+
+`errorController`
+
+`typeof ErrorController`
+
+`fetchSetup`
+
+`function`
+
+▸
+
+Type
+
+`(context: LoaderContext, initParams: any) => Request | Promise<Request>`
+
+`fLoader`
+
+`FragmentLoaderConstructor`
+
+`forceKeyFrameOnDiscontinuity`
+
+`boolean`
+
+`fpsController`
+
+`typeof FPSController`
+
+`fpsDroppedMonitoringPeriod`
+
+`number`
+
+`fpsDroppedMonitoringThreshold`
+
+`number`
+
+`fragLoadingMaxRetry`
+
+`number`
+
+`fragLoadingMaxRetryTimeout`
+
+`number`
+
+`fragLoadingRetryDelay`
+
+`number`
+
+`fragLoadingTimeOut`
+
+`number`
+
+`fragLoadPolicy`
+
+`LoadPolicy`
+
+`frontBufferFlushThreshold`
+
+`number`
+
+`highBufferWatchdogPeriod`
+
+`number`
+
+`ignoreDevicePixelRatio`
+
+`boolean`
+
+`ignorePlaylistParsingErrors`
+
+`boolean`
+
+`initialLiveManifestSize`
+
+`number`
+
+`interstitialAppendInPlace`
+
+`boolean`
+
+`interstitialAssetListLoadPolicy`
+
+`LoadPolicy`
+
+`interstitialLiveLookAhead`
+
+`number`
+
+`interstitialsController`
+
+`typeof InterstitialsController`
+
+`keyLoadPolicy`
+
+`LoadPolicy`
+
+`levelLoadingMaxRetry`
+
+`number`
+
+`levelLoadingMaxRetryTimeout`
+
+`number`
+
+`levelLoadingRetryDelay`
+
+`number`
+
+`levelLoadingTimeOut`
+
+`number`
+
+`licenseResponseCallback`
+
+`function`
+
+▸
+
+Type
+
+`(this: Hls, xhr: XMLHttpRequest, url: string, keyContext: MediaKeySessionContext) => ArrayBuffer`
+
+`licenseXhrSetup`
+
+`function`
+
+▸
+
+Type
+
+`(this: Hls, xhr: XMLHttpRequest, url: string, keyContext: MediaKeySessionContext, licenseChallenge: Uint8Array<ArrayBufferLike>) => void | ... 1 more ... | Promise<...>`
+
+`liveBackBufferLength`
+
+`number | null`
+
+`liveDurationInfinity`
+
+`boolean`
+
+`liveMaxLatencyDuration`
+
+`number`
+
+`liveMaxLatencyDurationCount`
+
+`number`
+
+`liveSyncDuration`
+
+`number`
+
+`liveSyncDurationCount`
+
+`number`
+
+`liveSyncMode`
+
+`"buffered" | "edge"`
+
+`liveSyncOnStallIncrease`
+
+`number`
+
+`loader`
+
+`function`
+
+▸
+
+Type
+
+`new (confg: HlsConfig) => Loader<LoaderContext>`
+
+`lowLatencyMode`
+
+`boolean`
+
+`manifestLoadingMaxRetry`
+
+`number`
+
+`manifestLoadingMaxRetryTimeout`
+
+`number`
+
+`manifestLoadingRetryDelay`
+
+`number`
+
+`manifestLoadingTimeOut`
+
+`number`
+
+`manifestLoadPolicy`
+
+`LoadPolicy`
+
+`maxAudioFramesDrift`
+
+`number`
+
+`maxBufferHole`
+
+`number`
+
+`maxBufferLength`
+
+`number`
+
+`maxBufferSize`
+
+`number`
+
+`maxDevicePixelRatio`
+
+`number`
+
+`maxFragLookUpTolerance`
+
+`number`
+
+`maxLiveSyncPlaybackRate`
+
+`number`
+
+`maxLoadingDelay`
+
+`number`
+
+`maxMaxBufferLength`
+
+`number`
+
+`maxStarvationDelay`
+
+`number`
+
+`minAutoBitrate`
+
+`number`
+
+`nudgeMaxRetry`
+
+`number`
+
+`nudgeOffset`
+
+`number`
+
+`nudgeOnVideoHole`
+
+`boolean`
+
+`playlistLoadPolicy`
+
+`LoadPolicy`
+
+`pLoader`
+
+`PlaylistLoaderConstructor`
+
+`preferManagedMediaSource`
+
+`boolean`
+
+`preserveManualLevelOnError`
+
+`boolean`
+
+`primarySessionId`
+
+`string`
+
+`progressive`
+
+`boolean`
+
+`renderTextTracksNatively`
+
+`boolean`
+
+`requestMediaKeySystemAccessFunc`
+
+`MediaKeyFunc | null`
+
+`requireKeySystemAccessOnStart`
+
+`boolean`
+
+`startFragPrefetch`
+
+`boolean`
+
+`startLevel`
+
+`number`
+
+`startOnSegmentBoundary`
+
+`boolean`
+
+`startPosition`
+
+`number`
+
+`steeringManifestLoadPolicy`
+
+`LoadPolicy`
+
+`stretchShortVideoTrack`
+
+`boolean`
+
+`subtitlePreference`
+
+`SubtitleSelectionOption`
+
+`subtitleStreamController`
+
+`typeof SubtitleStreamController`
+
+`subtitleTrackController`
+
+`typeof SubtitleTrackController`
+
+`testBandwidth`
+
+`boolean`
+
+`timelineController`
+
+`typeof TimelineController`
+
+`timelineOffset`
+
+`number`
+
+`useMediaCapabilities`
+
+`boolean`
+
+`videoPreference`
+
+`VideoSelectionOption`
+
+`widevineLicenseUrl`
+
+`string`
+
+`workerPath`
+
+`string | null`
+
+`xhrSetup`
+
+`function`
+
+▸
+
+Type
+
+`(xhr: XMLHttpRequest, url: string) => void | Promise<void>`
+
+#### `source.engine.nativeHls`
+
+When playback falls back to the browser’s own HLS, hls.js isn’t involved and its options don’t apply. This configures that path instead.
+
+Option
+
+Type
+
+Details
+
+`drmSystems`
+
+`Partial<Record<KeySystem, DrmSystemCo...`
+
+▸
+
+Description
+
+License servers for protected content, keyed by EME key system id. An escape hatch for licensing native playback differently from every other path: naming it replaces `source.drm` here, and nowhere else.
+
+Type
+
+`Partial<Record<KeySystem, DrmSystemConfig>> | undefined`
+
+### 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/i18n-provider.md

@@ -0,0 +1,25 @@
+# I18nProvider
+
+React provider that resolves locale and supplies a typed translator to descendants
+
+`I18nProvider` resolves the active locale, lazy-loads built-in packs, merges registry and provider layers, and exposes a translator through context. Wrap it around a player or custom controls that should translate.
+
+Wrap custom controls or force a locale explicitly:
+
+tsx
+
+```
+import { I18nProvider } from '@videojs/react/i18n';
+
+<I18nProvider locale="de" translations={{ buttons: { play: 'Abspielen' } }}>
+  <MyControls />
+</I18nProvider>
+```
+
+Omit `locale` to inherit the nearest `lang` attribute (via `langRootRef` or `<html lang>`). English is the fallback when no non-English locale is active or no translation layer supplies a string. See [Internationalization](../concepts/i18n.md) for merge priority, browser translation fallback, and SSR guidance.
+
+## API Reference
+
+### Return Value
+
+`unknown`