@videojs/react 10.0.0-beta.8 → 10.0.0-rc.1

package/docs/reference/hlsjs-video.md

@@ -0,0 +1,766 @@
+# 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, with full feature support across every browser. It’s more compatible than the default [HlsVideo](/docs/framework/html/reference/hls-video/), which is smaller and covers most HLS playback. For browser-native playback, see [NativeHlsVideo](/docs/framework/html/reference/native-hls-video/).
+
+## Import
+
+bash
+
+```
+pnpm add @videojs/hlsjs-video
+```
+
+tsx
+
+```
+import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
+```
+
+## 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
+
+`disableRemotePlayback`
+
+`unknown`
+
+`false`
+
+▸
+
+Description
+
+Whether remote playback (AirPlay, Google Cast) is disabled for this media.
+
+`preload`
+
+`MediaPreloadType`
+
+`'metadata'`
+
+▸
+
+Description
+
+Preload type (`'none'` / `'metadata'` / `'auto'`).
+
+`source`
+
+`{ src?: string; type?: SourceType; preferPlayback?: PlaybackType; drm?: DrmSystemsConfig; maxAutoResolution?: MediaResolution; capRenditionToPlayerSize?: boolean; minAutoResolution?: MediaResolution; engine?: HlsEngineConfig } | 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`
+
+`MediaStreamType`
+
+`"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 | undefined`
+
+`abrBandWidthUpFactor`
+
+`number | undefined`
+
+`abrController`
+
+`typeof AbrController | undefined`
+
+`abrEwmaDefaultEstimate`
+
+`number | undefined`
+
+▸
+
+Description
+
+Default bandwidth estimate in bits/s prior to collecting fragment bandwidth samples
+
+`abrEwmaDefaultEstimateMax`
+
+`number | undefined`
+
+`abrEwmaFastLive`
+
+`number | undefined`
+
+`abrEwmaFastVoD`
+
+`number | undefined`
+
+`abrEwmaSlowLive`
+
+`number | undefined`
+
+`abrEwmaSlowVoD`
+
+`number | undefined`
+
+`abrMaxWithRealBitrate`
+
+`boolean | undefined`
+
+`appendErrorMaxRetry`
+
+`number | undefined`
+
+`assetPlayerId`
+
+`string | undefined`
+
+`audioPreference`
+
+`AudioSelectionOption | undefined`
+
+`audioStreamController`
+
+`typeof AudioStreamController | undefined`
+
+`audioTrackController`
+
+`typeof AudioTrackController | undefined`
+
+`autoStartLoad`
+
+`boolean | undefined`
+
+`backBufferLength`
+
+`number | undefined`
+
+`bufferController`
+
+`typeof BufferController | undefined`
+
+`capLevelController`
+
+`typeof CapLevelController | undefined`
+
+`capLevelOnFPSDrop`
+
+`boolean | undefined`
+
+`capLevelToPlayerSize`
+
+`boolean | undefined`
+
+`captionsTextTrack1Label`
+
+`string | undefined`
+
+`captionsTextTrack1LanguageCode`
+
+`string | undefined`
+
+`captionsTextTrack2Label`
+
+`string | undefined`
+
+`captionsTextTrack2LanguageCode`
+
+`string | undefined`
+
+`captionsTextTrack3Label`
+
+`string | undefined`
+
+`captionsTextTrack3LanguageCode`
+
+`string | undefined`
+
+`captionsTextTrack4Label`
+
+`string | undefined`
+
+`captionsTextTrack4LanguageCode`
+
+`string | undefined`
+
+`certLoadPolicy`
+
+`LoadPolicy | undefined`
+
+`cmcd`
+
+`CMCDControllerConfig | undefined`
+
+`cmcdController`
+
+`typeof CMCDController | undefined`
+
+`contentSteeringController`
+
+`typeof ContentSteeringController | un...`
+
+▸
+
+Type
+
+`typeof ContentSteeringController | undefined`
+
+`cueHandler`
+
+`CuesInterface | undefined`
+
+`debug`
+
+`boolean | ILogger | undefined`
+
+`defaultAudioCodec`
+
+`string | undefined`
+
+`detectStallWithCurrentTimeMs`
+
+`number | undefined`
+
+`drmSystemOptions`
+
+`DRMSystemOptions | undefined`
+
+`drmSystems`
+
+`DRMSystemsConfiguration | undefined`
+
+`emeController`
+
+`typeof EMEController | undefined`
+
+`emeEnabled`
+
+`boolean | undefined`
+
+`enableCEA708Captions`
+
+`boolean | undefined`
+
+`enableDateRangeMetadataCues`
+
+`boolean | undefined`
+
+`enableEmsgKLVMetadata`
+
+`boolean | undefined`
+
+`enableEmsgMetadataCues`
+
+`boolean | undefined`
+
+`enableID3MetadataCues`
+
+`boolean | undefined`
+
+`enableIMSC1`
+
+`boolean | undefined`
+
+`enableInterstitialPlayback`
+
+`boolean | undefined`
+
+`enableSoftwareAES`
+
+`boolean | undefined`
+
+`enableWebVTT`
+
+`boolean | undefined`
+
+`enableWorker`
+
+`boolean | undefined`
+
+`errorController`
+
+`typeof ErrorController | undefined`
+
+`fetchSetup`
+
+`Request) | undefined | function`
+
+▸
+
+Type
+
+`((context: LoaderContext, initParams: any) => Promise<Request> | Request) | undefined`
+
+`fLoader`
+
+`FragmentLoaderConstructor | undefined`
+
+`forceKeyFrameOnDiscontinuity`
+
+`boolean | undefined`
+
+`fpsController`
+
+`typeof FPSController | undefined`
+
+`fpsDroppedMonitoringPeriod`
+
+`number | undefined`
+
+`fpsDroppedMonitoringThreshold`
+
+`number | undefined`
+
+`fragLoadingMaxRetry`
+
+`number | undefined`
+
+`fragLoadingMaxRetryTimeout`
+
+`number | undefined`
+
+`fragLoadingRetryDelay`
+
+`number | undefined`
+
+`fragLoadingTimeOut`
+
+`number | undefined`
+
+`fragLoadPolicy`
+
+`LoadPolicy | undefined`
+
+`frontBufferFlushThreshold`
+
+`number | undefined`
+
+`highBufferWatchdogPeriod`
+
+`number | undefined`
+
+`ignoreDevicePixelRatio`
+
+`boolean | undefined`
+
+`ignorePlaylistParsingErrors`
+
+`boolean | undefined`
+
+`initialLiveManifestSize`
+
+`number | undefined`
+
+`interstitialAppendInPlace`
+
+`boolean | undefined`
+
+`interstitialAssetListLoadPolicy`
+
+`LoadPolicy | undefined`
+
+`interstitialLiveLookAhead`
+
+`number | undefined`
+
+`interstitialsController`
+
+`typeof InterstitialsController | unde...`
+
+▸
+
+Type
+
+`typeof InterstitialsController | undefined`
+
+`keyLoadPolicy`
+
+`LoadPolicy | undefined`
+
+`levelLoadingMaxRetry`
+
+`number | undefined`
+
+`levelLoadingMaxRetryTimeout`
+
+`number | undefined`
+
+`levelLoadingRetryDelay`
+
+`number | undefined`
+
+`levelLoadingTimeOut`
+
+`number | undefined`
+
+`licenseResponseCallback`
+
+`undefined | function`
+
+▸
+
+Type
+
+`((this: Hls, xhr: XMLHttpRequest, url: string, keyContext: MediaKeySessionContext) => ArrayBuffer) | undefined`
+
+`licenseXhrSetup`
+
+`Uint8Array | Promise<Uint8Array | void>) | undefined | function`
+
+▸
+
+Type
+
+`((this: Hls, xhr: XMLHttpRequest, url: string, keyContext: MediaKeySessionContext, licenseChallenge: Uint8Array) => void | Uint8Array | Promise<Uint8Array | void>) | undefined`
+
+`liveBackBufferLength`
+
+`number | null | undefined`
+
+`liveDurationInfinity`
+
+`boolean | undefined`
+
+`liveMaxLatencyDuration`
+
+`number | undefined`
+
+`liveMaxLatencyDurationCount`
+
+`number | undefined`
+
+`liveSyncDuration`
+
+`number | undefined`
+
+`liveSyncDurationCount`
+
+`number | undefined`
+
+`liveSyncMode`
+
+`'edge' | 'buffered' | undefined`
+
+`liveSyncOnStallIncrease`
+
+`number | undefined`
+
+`loader`
+
+`object`
+
+▸
+
+Type
+
+`{ new (confg: HlsConfig): Loader<LoaderContext>; } | undefined`
+
+`lowLatencyMode`
+
+`boolean | undefined`
+
+`manifestLoadingMaxRetry`
+
+`number | undefined`
+
+`manifestLoadingMaxRetryTimeout`
+
+`number | undefined`
+
+`manifestLoadingRetryDelay`
+
+`number | undefined`
+
+`manifestLoadingTimeOut`
+
+`number | undefined`
+
+`manifestLoadPolicy`
+
+`LoadPolicy | undefined`
+
+`maxAudioFramesDrift`
+
+`number | undefined`
+
+`maxBufferHole`
+
+`number | undefined`
+
+`maxBufferLength`
+
+`number | undefined`
+
+`maxBufferSize`
+
+`number | undefined`
+
+`maxDevicePixelRatio`
+
+`number | undefined`
+
+`maxFragLookUpTolerance`
+
+`number | undefined`
+
+`maxLiveSyncPlaybackRate`
+
+`number | undefined`
+
+`maxLoadingDelay`
+
+`number | undefined`
+
+`maxMaxBufferLength`
+
+`number | undefined`
+
+`maxStarvationDelay`
+
+`number | undefined`
+
+`minAutoBitrate`
+
+`number | undefined`
+
+`nudgeMaxRetry`
+
+`number | undefined`
+
+`nudgeOffset`
+
+`number | undefined`
+
+`nudgeOnVideoHole`
+
+`boolean | undefined`
+
+`playlistLoadPolicy`
+
+`LoadPolicy | undefined`
+
+`pLoader`
+
+`PlaylistLoaderConstructor | undefined`
+
+`preferManagedMediaSource`
+
+`boolean | undefined`
+
+`preserveManualLevelOnError`
+
+`boolean | undefined`
+
+`primarySessionId`
+
+`string | undefined`
+
+`progressive`
+
+`boolean | undefined`
+
+`renderTextTracksNatively`
+
+`boolean | undefined`
+
+`requestMediaKeySystemAccessFunc`
+
+`MediaKeyFunc | null | undefined`
+
+`requireKeySystemAccessOnStart`
+
+`boolean | undefined`
+
+`startFragPrefetch`
+
+`boolean | undefined`
+
+`startLevel`
+
+`number | undefined`
+
+`startOnSegmentBoundary`
+
+`boolean | undefined`
+
+`startPosition`
+
+`number | undefined`
+
+`steeringManifestLoadPolicy`
+
+`LoadPolicy | undefined`
+
+`stretchShortVideoTrack`
+
+`boolean | undefined`
+
+`subtitlePreference`
+
+`SubtitleSelectionOption | undefined`
+
+`subtitleStreamController`
+
+`typeof SubtitleStreamController | und...`
+
+▸
+
+Type
+
+`typeof SubtitleStreamController | undefined`
+
+`subtitleTrackController`
+
+`typeof SubtitleTrackController | unde...`
+
+▸
+
+Type
+
+`typeof SubtitleTrackController | undefined`
+
+`testBandwidth`
+
+`boolean | undefined`
+
+`timelineController`
+
+`typeof TimelineController | undefined`
+
+`timelineOffset`
+
+`number | undefined`
+
+`useMediaCapabilities`
+
+`boolean | undefined`
+
+`videoPreference`
+
+`VideoSelectionOption | undefined`
+
+`widevineLicenseUrl`
+
+`string | undefined`
+
+`workerPath`
+
+`string | null | undefined`
+
+`xhrSetup`
+
+`void) | undefined | function`
+
+▸
+
+Type
+
+`((xhr: XMLHttpRequest, url: string) => Promise<void> | void) | undefined`
+
+#### `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`
+
+`DrmSystemsConfig | undefined`
+
+▸
+
+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.
+
+### 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`.