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

package/docs/how-to/go-fullscreen-and-lock-orientation.md

@@ -0,0 +1,153 @@
+# Go fullscreen and lock orientation
+
+Present the player fullscreen with custom controls intact, and lock screen orientation on mobile.
+
+Present the player fullscreen, with your custom controls intact, and optionally lock screen orientation while fullscreen on mobile.
+
+Note
+
+Using a pre-built [skin](../concepts/skins.md)? It already includes the controls shown here. You may still need the media or player setup in this guide. The component examples are for building your own player UI from individual [components](../concepts/ui-components.md).
+
+## Recommended approach
+
+Add a [FullscreenButton](../reference/fullscreen-button.md) inside the player container. It requests fullscreen on the container, so everything inside it — controls, captions, overlays — stays visible in the fullscreen presentation.
+
+App.tsx
+
+App.css
+
+```
+import { Container, createPlayer, FullscreenButton } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const { Player } = createPlayer({ features: videoFeatures });
+
+export default function BasicUsage() {
+  return (
+    <Player>
+      <Container className="media-container">
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
+        <FullscreenButton
+          className="media-fullscreen-button"
+          render={(props, state) => <button {...props}>{state.fullscreen ? 'Exit Fullscreen' : 'Fullscreen'}</button>}
+        />
+      </Container>
+    </Player>
+  );
+}
+```
+```
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.media-fullscreen-button {
+  position: absolute;
+  right: 10px;
+  bottom: 10px;
+  padding-block: 8px;
+  padding-inline: 20px;
+  color: black;
+  cursor: pointer;
+  background: rgba(255, 255, 255, 0.7);
+  border: 1px solid rgba(255, 255, 255, 0.3);
+  border-radius: 9999px;
+  backdrop-filter: blur(10px);
+}
+```
+
+## How it works
+
+The [fullscreen feature](../reference/feature-fullscreen.md) tracks fullscreen state and provides the actions:
+
+*   `fullscreen` is `true` while the player is fullscreen, from any path — your button, native controls, or the platform presentation.
+*   `fullscreenAvailability` is `'available'`, `'unavailable'`, or `'unsupported'`. It starts as `'unavailable'`, then settles to `'available'` or `'unsupported'` when the feature attaches to a media element.
+*   `requestFullscreen()`, `exitFullscreen()`, and `toggleFullscreen()` change the presentation. Requests target the player container when the Fullscreen API is available, falling back to the media element’s native presentation otherwise.
+
+Fullscreen and picture-in-picture are exclusive: requesting fullscreen exits an active picture-in-picture presentation first.
+
+Style fullscreen state through the container’s `:fullscreen` pseudo-class, or through the `fullscreen` state in components.
+
+## Availability and constraints
+
+*   Fullscreen requests must come from a user gesture; browsers reject requests outside one.
+*   iPhone Safari has no element Fullscreen API. The player falls back to the video’s native fullscreen presentation, which shows the system player UI instead of your custom controls. iPads support element fullscreen.
+*   Orientation locking requires the Screen Orientation API with lock support — in practice, Android browsers in fullscreen. iOS doesn’t support programmatic orientation lock.
+*   Inside iframes, fullscreen needs `allow="fullscreen"` on the embedding iframe.
+
+## Common variations
+
+### Lock orientation while fullscreen
+
+Add `orientationLockFeature` to lock screen orientation while the player is fullscreen. It isn’t part of `videoFeatures`, so the preset `VideoPlayer` doesn’t include it. It locks to `landscape` by default and unlocks on exit.
+
+Because the feature list changes, build the player yourself with [`createPlayer`](../reference/create-player.md) — the escape hatch for custom feature sets:
+
+tsx
+
+```
+import { Container, createPlayer, orientationLockFeature } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const { Player } = createPlayer({
+  features: [...videoFeatures, orientationLockFeature],
+});
+
+export default function App() {
+  return (
+    <Player>
+      <Container>
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsInline />
+      </Container>
+    </Player>
+  );
+}
+```
+
+To lock to something other than `landscape`, set `orientationLockType` on the player (the `orientation-lock-type` attribute in HTML). See the [orientation lock feature](../reference/feature-orientation-lock.md) reference for details.
+
+### Double-click to toggle
+
+Use the `Gesture` component — the default skins ship this exact binding. Keep the button as the accessible path; gestures are a pointer-only shortcut.
+
+tsx
+
+```
+import { Gesture } from '@videojs/react';
+
+<Gesture type="doubletap" action="toggleFullscreen" region="center" />
+```
+
+`region="center"` keeps the gesture off the left and right thirds, which the default skins reserve for double-tap seeking. See [Add keyboard shortcuts and gestures](./add-keyboard-shortcuts-and-gestures.md) for the full gesture surface.
+
+## Troubleshooting
+
+### The fullscreen request is rejected
+
+The request didn’t come from a user gesture, fullscreen is unsupported, or an embedding iframe lacks `allow="fullscreen"`.
+
+### Custom controls disappear in fullscreen on iPhone
+
+Expected: iPhone Safari uses the native video presentation, which replaces custom UI with system controls. Design mobile controls assuming this fallback.
+
+### Orientation doesn’t lock
+
+Orientation lock works in fullscreen on Android browsers; iOS doesn’t support it. Confirm `orientationLockFeature` is in your feature list.
+
+## Related components
+
+*   [Fullscreen button](../reference/fullscreen-button.md)
+*   [Player container](../reference/player-container.md)
+
+## Related API
+
+*   [Fullscreen feature](../reference/feature-fullscreen.md)
+*   [Orientation lock feature](../reference/feature-orientation-lock.md)
+
+## Related guides
+
+*   [Use picture-in-picture](./use-picture-in-picture.md)

package/docs/how-to/handle-playback-errors.md

@@ -0,0 +1,92 @@
+# Handle playback errors
+
+Surface terminal playback errors and give users a useful next step.
+
+Surface terminal playback errors instead of leaving a dead player, and give users a useful next step.
+
+Note
+
+Using a pre-built [skin](../concepts/skins.md)? It already includes the controls shown here. You may still need the media or player setup in this guide. The component examples are for building your own player UI from individual [components](../concepts/ui-components.md).
+
+## Recommended approach
+
+Render an [ErrorDialog](../reference/error-dialog.md) inside the player container. It reads error state, presents the failure, and dismisses cleanly. The prebuilt skins include one.
+
+tsx
+
+```
+import { Container, ErrorDialog } from '@videojs/react';
+import { Video, VideoPlayer } from '@videojs/react/video';
+
+export default function App() {
+  return (
+    <VideoPlayer>
+      <Container>
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsInline />
+
+        <ErrorDialog.Root>
+          <ErrorDialog.Popup className="media-error">
+            <ErrorDialog.Title />
+            <ErrorDialog.Description />
+            <ErrorDialog.Close>Dismiss</ErrorDialog.Close>
+          </ErrorDialog.Popup>
+        </ErrorDialog.Root>
+      </Container>
+    </VideoPlayer>
+  );
+}
+```
+
+## How it works
+
+The [error feature](../reference/feature-error.md) mirrors the media element’s error into player state:
+
+*   `error` holds the media’s `MediaError` — `code`, `message` — or `null` when there is none.
+*   `dismissError()` clears the error from player state (the media element keeps its own error until a new load).
+*   Loading a new source resets `error` to `null` automatically.
+
+The dialog owns presentation, not recovery. Decide the next step in your application: let the user dismiss the message, choose another item, refresh an expired URL, or contact support.
+
+## Availability and constraints
+
+*   A media error is terminal for the current load: playback won’t resume without loading a source again.
+*   `MediaError.code` distinguishes broad classes — aborted, network, decode, and source-not-supported — not root causes. Check the network panel for the real story (404, CORS, codec).
+*   Streaming engines handle recoverable segment and network failures before surfacing a terminal error. Do not layer a generic same-source retry loop on top of the engine.
+*   Once the player attaches to the media element, errors land in state even before any UI renders (bad URL at mount); make sure your error surface renders regardless of playback state.
+
+## Common variations
+
+### Offer an application-specific next step
+
+Use the error code and your product context to choose the action. A live event can link to its status page, an authenticated app can refresh an expired playback URL, and a playlist can offer the next item. Keep that action outside `ErrorDialog`; the dialog can close after your application has handled it.
+
+### Report errors to monitoring
+
+Subscribe to error state and forward it to your error tracker with the source URL and `error.code`; media errors are invisible in JavaScript error monitoring unless you send them.
+
+## Troubleshooting
+
+### The player is black and silent with no error
+
+Not every dead player is a media error — autoplay blocking and an unset source produce no error. Check `error`, `source`, and `paused` in player state to tell them apart.
+
+### Error code says the source isn’t supported
+
+The browser can’t play the format through this media element. HLS in a plain video element outside Safari is the classic case; use the matching streaming media element. See [Media sources](../concepts/media-sources.md).
+
+### Reopening the source produces the same error
+
+The failure is probably permanent for that source, such as a 404, revoked token, unsupported codec, or CORS response. Fix or replace the source instead of repeatedly loading the same URL.
+
+## Related components
+
+*   [Buffering indicator](../reference/buffering-indicator.md)
+
+## Related API
+
+*   [Error feature](../reference/feature-error.md)
+
+## Related guides
+
+*   [Media sources](../concepts/media-sources.md)
+*   [Autoplay](./autoplay.md)

package/docs/how-to/installation.md

@@ -20,18 +20,20 @@ npx @videojs/cli docs how-to/installation \
   --framework <html|react> \
   --preset <video|audio|live-video|live-audio|background-video> \
   --skin <default|minimal|none> \
-  --media <html5-video|html5-audio|hls|dash|mux-video|mux-audio|vimeo|background-video> \
+  --media <html5-video|html5-audio|hls|dash|mux-video|mux-audio|vimeo|youtube|cloudflare|tiktok|twitch|spotify|background-video> \
   --source-url <url> \
   --install-method <cdn|npm|pnpm|yarn|bun>
 ```
 
+The CLI does not currently detect non-interactive stdin. In automation, agents, and CI, include `--framework` and all five installation flags so no prompt starts. Pass `--source-url ''` to use the built-in demo without prompting.
+
 Here’s what the flags mean:
 
 *   *Framework*: Pick whether you’re working in React or if you’d like to use HTML custom elements. (More to come!)
 *   *Preset*: Pick a pre-built player. The default presets work well for general website playback; the live presets add a Live button and drop the on-demand time displays.
 *   *Skin*: Pick what your player looks like
 *   *Media*: Pick what kind of media you have. The `live-video` preset supports HLS and Mux video; `live-audio` supports Mux audio.
-*   *Source URL*: Define where your media comes from (or omit for a sample URL)
+*   *Source URL*: Define where your media comes from. In an interactive terminal, omit it to choose a sample URL. In automation, pass an empty value to choose the sample without prompting.
 *   *Install method*: How do you want to install your package? (CDN is HTML-only.)
 
 If you’re an agent, interview your user and offer to run the CLI for them, or offer them a precomposed CLI command.
@@ -121,26 +123,66 @@ export const HomePage = () => {
 
 <!-- /cli:replace installation -->
 
-## See also
+That’s it! You now have a working Video.js player.
+
+## Choose what to do next
 
 [
 
-Skins
+Customize skins
 
-Some skins expose CSS custom properties
+Customize a packaged skin or eject it for full control
 
-](../concepts/skins.md)
+](./customize-skins.md)
 
 [
 
-Security
+UI components
 
-Configure Content Security Policy for your player
+Explore the building blocks used by skins and custom controls
 
-](../concepts/security.md)
+](../concepts/overview.md)
+
+[
+
+Build your own component
+
+Connect custom UI to player state and actions
+
+](./build-your-own-component.md)
+
+## Prepare for production
+
+[
+
+Browser support
+
+Check supported browsers and rendering environments
+
+](../concepts/browser-support.md)
 
-* * *
+[
+
+TypeScript
+
+Configure TypeScript for Video.js packages
+
+](../concepts/typescript.md)
+
+[
+
+Bundlers
+
+Check bundler compatibility
 
-That’s it! You now have a fully functional Video.js player. Go forth and play.
+](../concepts/bundlers.md)
+
+[
+
+Content Security Policy
+
+Configure Content Security Policy for your player
+
+](../concepts/security.md)
 
 Something not quite right? You can [submit an issue](https://github.com/videojs/v10/issues) and ask for help, or explore [other support options](/html5-video-support).