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

package/docs/concepts/presets.md

@@ -0,0 +1,229 @@
+# Presets
+
+Pre-packaged player configurations that bundle state management, skins, and media elements for specific use cases.
+
+A **preset** packages what you need for a specific player use case. It can include special [state management](./features.md), one or more [skins](./skins.md) for UI, and specific media elements. Instead of assembling these pieces individually, you pick a preset that matches what you’re building.
+
+For example, the `@videojs/react/background` preset includes a media element with autoplay, mute, and loop built in, a skin with no controls, and just the features needed to power them:
+
+App.tsx
+
+```
+import { BackgroundVideo, BackgroundVideoPlayer, BackgroundVideoSkin } from '@videojs/react/background';
+
+function Hero() {
+  return (
+    <BackgroundVideoPlayer>
+      <BackgroundVideoSkin>
+        <BackgroundVideo src="hero.mp4" />
+      </BackgroundVideoSkin>
+    </BackgroundVideoPlayer>
+  );
+}
+```
+
+## Available presets
+
+The default presets are `/video` and `/audio`. These cover the baseline controls you’d expect from the HTML `<video>` and `<audio>` tags. Beyond the defaults, presets target more specific use cases — the `/background` preset, for example, needs layout but not controls. Over time we’ll add more: short-form players, podcast players, TV streaming players, and others.
+
+Import
+
+Description
+
+Details
+
+`@videojs/react/video`
+
+General-purpose video player preset with full playback controls.
+
+▸
+
+Feature bundle
+
+`videoFeatures`
+
+Features
+
+[playback](../reference/feature-playback.md), [playbackRate](../reference/feature-playback-rate.md), [quality](../reference/feature-quality.md), [audioTrack](../reference/feature-audio-track.md), [volume](../reference/feature-volume.md), [time](../reference/feature-time.md), [source](../reference/feature-source.md), [buffer](../reference/feature-buffer.md), [fullscreen](../reference/feature-fullscreen.md), [pip](../reference/feature-pip.md), [remotePlayback](../reference/feature-remote-playback.md), [controls](../reference/feature-controls.md), [textTrack](../reference/feature-text-tracks.md), [error](../reference/feature-error.md), [metadata](../reference/feature-metadata.md)
+
+Skins
+
+`<MinimalVideoSkin>`
+
+`import '@videojs/react/video/minimal-skin.css';`
+
+`<VideoSkin>`
+
+`import '@videojs/react/video/skin.css';`
+
+Default media element
+
+`<Video>`
+
+`@videojs/react/audio`
+
+Audio-only player preset with playback and volume controls.
+
+▸
+
+Feature bundle
+
+`audioFeatures`
+
+Features
+
+[playback](../reference/feature-playback.md), [playbackRate](../reference/feature-playback-rate.md), [volume](../reference/feature-volume.md), [time](../reference/feature-time.md), [source](../reference/feature-source.md), [buffer](../reference/feature-buffer.md), [error](../reference/feature-error.md), [metadata](../reference/feature-metadata.md)
+
+Skins
+
+`<MinimalAudioSkin>`
+
+`import '@videojs/react/audio/minimal-skin.css';`
+
+`<AudioSkin>`
+
+`import '@videojs/react/audio/skin.css';`
+
+Default media element
+
+`<Audio>`
+
+`@videojs/react/background`
+
+Ambient background video preset with no user controls.
+
+▸
+
+Feature bundle
+
+`backgroundFeatures`
+
+Features
+
+–
+
+Skins
+
+`<BackgroundVideoSkin>`
+
+`import '@videojs/react/background/skin.css';`
+
+Default media element
+
+`<BackgroundVideo>`
+
+`@videojs/react/live-audio`
+
+Live audio player preset — same features as `audio` with a skin that omits duration / current-time displays.
+
+▸
+
+Feature bundle
+
+`liveAudioFeatures`
+
+Features
+
+[playback](../reference/feature-playback.md), [volume](../reference/feature-volume.md), [time](../reference/feature-time.md), [source](../reference/feature-source.md), [buffer](../reference/feature-buffer.md), [error](../reference/feature-error.md), [live](../reference/feature-live.md), [metadata](../reference/feature-metadata.md)
+
+Skins
+
+`<MinimalLiveAudioSkin>`
+
+`import '@videojs/react/live-audio/minimal-skin.css';`
+
+`<LiveAudioSkin>`
+
+`import '@videojs/react/live-audio/skin.css';`
+
+Default media element
+
+`<Audio>`
+
+`@videojs/react/live-video`
+
+Live video player preset — same features as `video` with a skin that omits duration / current-time displays.
+
+▸
+
+Feature bundle
+
+`liveVideoFeatures`
+
+Features
+
+[playback](../reference/feature-playback.md), [volume](../reference/feature-volume.md), [time](../reference/feature-time.md), [source](../reference/feature-source.md), [buffer](../reference/feature-buffer.md), [fullscreen](../reference/feature-fullscreen.md), [pip](../reference/feature-pip.md), [remotePlayback](../reference/feature-remote-playback.md), [controls](../reference/feature-controls.md), [textTrack](../reference/feature-text-tracks.md), [error](../reference/feature-error.md), [live](../reference/feature-live.md), [metadata](../reference/feature-metadata.md)
+
+Skins
+
+`<MinimalLiveVideoSkin>`
+
+`import '@videojs/react/live-video/minimal-skin.css';`
+
+`<LiveVideoSkin>`
+
+`import '@videojs/react/live-video/skin.css';`
+
+Default media element
+
+`<Video>`
+
+## What’s in a preset
+
+Each React preset exports a named, preconfigured player component and typed `usePlayer` hook, plus the building blocks needed to customize or eject from it:
+
+*   **Player** — A player component named for the preset, such as `VideoPlayer`, already configured with the preset’s feature bundle.
+*   **Typed hook** — A `usePlayer` hook whose state and actions match the preset.
+*   **Feature bundle** — An array of [features](./features.md) that define the player’s state and actions. For example, the video feature bundle includes playback, volume, time, fullscreen, and more.
+*   **Skins** — Pre-built UIs designed for that feature bundle. For example, a video skin renders fullscreen and PiP controls because the video feature bundle includes those features. An audio skin doesn’t.
+*   **Media element** — A media component suited to the use case. For example, the background video element bakes in autoplay, mute, and loop.
+
+These parts aren’t equally tied together. Skins depend tightly on their feature bundle — a skin expects specific features to exist. Media elements are more interchangeable — you can swap in an HLS or DASH provider without changing your skin or features.
+
+## Customizing a preset
+
+You can customize a preset in three ways: extend its feature bundle, eject its skin, or swap its media element.
+
+### Extend the feature bundle
+
+Add features to a preset’s feature bundle to enable new functionality. For example, adding playback controls to a background video:
+
+App.tsx
+
+```
+import { Container, createPlayer, playbackFeature } from '@videojs/react';
+import { backgroundFeatures, BackgroundVideo } from '@videojs/react/background';
+
+const { Player } = createPlayer({
+  features: [...backgroundFeatures, playbackFeature],
+});
+
+function Hero() {
+  return (
+    <Player>
+      <Container>
+        <BackgroundVideo src="hero.mp4" />
+        <PlayButton />
+      </Container>
+    </Player>
+  );
+}
+```
+
+### Eject the skin
+
+If a preset’s skin is close but not quite right, you can [eject it](../how-to/customize-skins.md) — copy its internal components into your project and customize from there.
+
+### Swap the media element
+
+A preset’s default media element is just the starting point. You can replace it with any compatible media provider. For example, using an HLS source with the video preset:
+
+tsx
+
+```
+<VideoPlayer>
+  <VideoSkin>
+    <HlsJsVideo src="https://example.com/stream.m3u8" />
+  </VideoSkin>
+</VideoPlayer>
+```

package/docs/concepts/security.md

@@ -0,0 +1,32 @@
+# Security
+
+How to configure Content Security Policy for your video player
+
+Content Security Policy (CSP) limits which resources a page can load. Video.js uses the URLs you configure for media, posters, thumbnails, and captions. Some HLS renderers also create blob URLs or web workers, so your policy must allow those resources too.
+
+## Allow player resources
+
+*   `media-src` must allow your media URLs.
+*   `img-src` must allow any poster or thumbnail image URLs.
+*   `connect-src` must allow HLS manifests, playlists, captions, and segment requests when using HLS playback.
+*   `media-src blob:` is required when using the HLS player variants, which use MSE-backed playback.
+*   `worker-src blob:` is required when using the `hls.js` player variants.
+*   `style-src 'unsafe-inline'` is required for some player UI and HTML player styling behavior.
+
+## Example
+
+http
+
+```
+Content-Security-Policy:
+  script-src 'self';
+  style-src 'self' 'unsafe-inline';
+  img-src 'self' https: data: blob:;
+  media-src 'self' https: blob:;
+  connect-src 'self' https:;
+  worker-src 'self' blob:;
+```
+
+This policy assumes you bundle Video.js with your application or serve it from your own origin. If you load the player from a CDN, add that CDN’s origin to `script-src`.
+
+Replace broad sources such as `https:` with the exact origins your player uses. Remove sources your deployment does not need, and keep `blob:` only where your selected HLS renderer requires it.