@videojs/react 10.0.0-beta.23 → 10.0.0-beta.24

package/docs/concepts/overview.md

@@ -0,0 +1,119 @@
+# Overview
+
+How Video.js players are structured — state, UI, and media
+
+Video.js v10 is built around a three-part architecture that separates concerns and maximizes flexibility. Each part is designed to work independently or together, allowing you to use as much or as little of Video.js as you need.
+
+For the reasoning behind this design, see [Why Video.js?](./why-videojs.md).
+
+## 1\. State management
+
+State is handled by a `Player.Provider`, which creates a central state store that all components can access. When you wrap your player in a `Player.Provider`, the components automatically connect to the state.
+
+tsx
+
+```
+{/* All components inside automatically connect to state */}
+<Player.Provider>
+  <VideoSkin>
+    <Video src="video.mp4" />
+  </VideoSkin>
+</Player.Provider>
+```
+
+You can access state and actions from anywhere within the provider with the [`usePlayer` hook](../reference/use-player.md).
+
+[Learn more about state and actions](./features.md)
+
+## 2\. User interface
+
+Use a prebuilt **skin** or build your own from the individual **UI components** .
+
+### Skins
+
+Skins are complete, pre-designed player UIs that package components and styles together:
+
+tsx
+
+```
+<Player.Provider>
+  <VideoSkin>
+    <Video src="video.mp4" />
+  </VideoSkin>
+</Player.Provider>
+```
+
+[Learn more about skins](./skins.md)
+
+### UI components
+
+If you want more control than skins offer you, you can build your own UI from our components.
+
+tsx
+
+```
+<Player.Provider>
+  <Player.Container>
+    <Video src="video.mp4" />
+    <MediaControls>
+      <PlayButton />
+      {/* ... */}
+    </MediaControls>
+  </Player.Container>
+</Player.Provider>
+```
+
+To get started with UI components, you might consider [ejecting a skin](../how-to/customize-skins.md) and using its pre-styled components as a foundation.
+
+[Learn more about UI components](./ui-components.md)
+
+[Build your own component](../how-to/build-your-own-component.md)
+
+## 3\. Media
+
+Media components are the components that actually display your media. They’re essentially “players with no UI”. They handle the video/audio rendering and expose a consistent API.
+
+Media components can be format specific (HLS, DASH), service specific (YouTube, Vimeo, Mux), or use case specific (background video).
+
+Note
+
+DASH, YouTube, Vimeo, Mux, and more media elements are currently under development.
+
+tsx
+
+```
+<Player.Provider>
+  <VideoSkin>
+    <HlsVideo src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" />
+  </VideoSkin>
+</Player.Provider>
+```
+
+## Presets
+
+**Presets** preconfigure these parts for a specific use case.
+
+The default presets are `@videojs/react/video` and `@videojs/react/audio`, covering the baseline set of controls you’d expect from the HTML `<video>` and `<audio>` tags.
+
+Beyond the defaults, presets target more specific use cases. For example, `/background` includes a media element with autoplay, mute, and loop built in, a skin with no controls, and just the features needed to power it:
+
+tsx
+
+```
+import { createPlayer } from '@videojs/react';
+import { backgroundFeatures, BackgroundVideo, BackgroundVideoSkin } from '@videojs/react/background';
+
+const Player = createPlayer({ features: backgroundFeatures });
+
+function Hero() {
+  return (
+    <Player.Provider>
+      <BackgroundVideoSkin>
+        <BackgroundVideo src="hero.mp4" />
+      </BackgroundVideoSkin>
+    </Player.Provider>
+  );
+}
+```
+
+[Learn more about presets](./presets.md)

package/docs/concepts/presets.md

@@ -0,0 +1,204 @@
+# 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 { createPlayer } from '@videojs/react';
+import { backgroundFeatures, BackgroundVideo, BackgroundVideoSkin } from '@videojs/react/background';
+
+const Player = createPlayer({ features: backgroundFeatures });
+
+function Hero() {
+  return (
+    <Player.Provider>
+      <BackgroundVideoSkin>
+        <BackgroundVideo src="hero.mp4" />
+      </BackgroundVideoSkin>
+    </Player.Provider>
+  );
+}
+```
+
+## 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), [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)
+
+Skins
+
+`<MinimalVideoSkin>`, `<VideoSkin>`
+
+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)
+
+Skins
+
+`<MinimalAudioSkin>`, `<AudioSkin>`
+
+Default media element
+
+`<Audio>`
+
+`@videojs/react/background`
+
+Ambient background video preset with no user controls.
+
+▸
+
+Feature bundle
+
+`backgroundFeatures`
+
+Features
+
+–
+
+Skins
+
+`<BackgroundVideoSkin>`
+
+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)
+
+Skins
+
+`<MinimalLiveAudioSkin>`, `<LiveAudioSkin>`
+
+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)
+
+Skins
+
+`<MinimalLiveVideoSkin>`, `<LiveVideoSkin>`
+
+Default media element
+
+`<Video>`
+
+## What’s in a preset
+
+Each preset exports up to three things:
+
+*   **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 { createPlayer, playbackFeature } from '@videojs/react';
+import { backgroundFeatures, BackgroundVideo } from '@videojs/react/background';
+
+const Player = createPlayer({
+  features: [...backgroundFeatures, playbackFeature],
+});
+
+function Hero() {
+  return (
+    <Player.Provider>
+      <Player.Container>
+        <BackgroundVideo src="hero.mp4" />
+        <PlayButton />
+      </Player.Container>
+    </Player.Provider>
+  );
+}
+```
+
+### 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
+
+```
+<Player.Provider>
+  <VideoSkin>
+    <HlsVideo src="https://example.com/stream.m3u8" />
+  </VideoSkin>
+</Player.Provider>
+```