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

package/docs/how-to/customize-skins.md

@@ -383,7 +383,6 @@ export interface VideoPlayerProps {
   style?: CSSProperties;
   className?: string;
   renderPoster?: Poster.Props['render'];
-  placeholder?: string | undefined;
 }
 
 /**
@@ -395,18 +394,10 @@ export interface VideoPlayerProps {
  * />
  * ```
  */
-export function VideoPlayer({ src, poster, className, renderPoster, placeholder, style, ...rest }: VideoPlayerProps): ReactNode {
-  const containerStyle = placeholder
-    ? ({ '--media-poster-placeholder': `url(${placeholder})`, ...style } as CSSProperties)
-    : style;
-
+export function VideoPlayer({ src, poster, className, renderPoster, style, ...rest }: VideoPlayerProps): ReactNode {
   return (
     <Player poster={poster}>
-      <Container
-        className={`media-default-skin media-default-skin--video ${className ?? ''}`}
-        style={containerStyle}
-        {...rest}
-      >
+      <Container className={`media-default-skin media-default-skin--video ${className ?? ''}`} style={style} {...rest}>
         <Video src={src} playsInline />
 
         <Poster render={renderPoster} />
@@ -1095,7 +1086,7 @@ export const { Player } = createPlayer({ features: videoFeatures });
 @media (prefers-reduced-motion: reduce) {
   .media-default-skin .media-button {
     scale: 1;
-    transition-property: background-color, color, outline-offset;
+    transition-property: background-color, color;
     will-change: auto;
   }
 }
@@ -1140,8 +1131,7 @@ export const { Player } = createPlayer({ features: videoFeatures });
   transition: opacity 0.25s;
 }
 .media-default-skin media-poster:not([data-visible]),
-.media-default-skin > img:not([data-visible]),
-.media-default-skin > img[data-visible]:not([data-loaded]) {
+.media-default-skin > img:not([data-visible]) {
   opacity: 0;
 }
 .media-default-skin media-poster ::slotted(img),
@@ -1160,30 +1150,6 @@ export const { Player } = createPlayer({ features: videoFeatures });
   border-radius: inherit;
 }
 
-/* Blurred placeholder: HTML path targets media-poster::before, React path targets the skin container::before */
-.media-default-skin media-poster::before,
-.media-default-skin::before {
-  position: absolute;
-  inset: 0;
-  pointer-events: none;
-  content: "";
-  background-image: var(--media-poster-placeholder, none);
-  background-repeat: no-repeat;
-  background-position: var(--media-object-position, center);
-  background-size: var(--media-object-fit, contain);
-  filter: blur(var(--media-poster-placeholder-blur, 20px));
-}
-
-/* React path: hidden by default, transitions in while poster loads */
-.media-default-skin::before {
-  opacity: 0;
-  transition: opacity 0.25s;
-}
-/* Show placeholder while the poster is visible but not yet loaded */
-.media-default-skin:has(img[data-visible]:not([data-loaded]))::before {
-  opacity: 1;
-}
-
 .media-default-skin:fullscreen media-poster ::slotted(img),
 .media-default-skin:fullscreen media-poster img,
 .media-default-skin:fullscreen > img {
@@ -1788,7 +1754,6 @@ export const { Player } = createPlayer({ features: videoFeatures });
     transition-timing-function: ease-out;
     transition-duration: var(--menu-transition-duration);
     transition-property: translate, filter;
-    will-change: translate, filter;
 
     &:where([data-starting-style], [data-ending-style]) {
       overflow: hidden;
@@ -1972,7 +1937,6 @@ export const { Player } = createPlayer({ features: videoFeatures });
       transition:
         translate var(--menu-transition-duration) ease-out,
         filter var(--menu-transition-duration) ease-out;
-      will-change: translate, filter;
     }
 
     &[data-submenu-expanded="true"] > :not([data-submenu]) {
@@ -2526,12 +2490,10 @@ export const { Player } = createPlayer({ features: videoFeatures });
 
       @media (pointer: fine) {
         transition-property: filter, opacity, scale, translate;
-        will-change: filter, opacity, scale, translate;
       }
 
       @media (pointer: coarse) {
         transition-property: opacity, scale, translate;
-        will-change: opacity, scale, translate;
       }
     }
 
@@ -2616,12 +2578,10 @@ export const { Player } = createPlayer({ features: videoFeatures });
 
   @media (pointer: fine) {
     transition-property: filter, opacity, scale, translate;
-    will-change: filter, opacity, scale, translate;
   }
 
   @media (pointer: coarse) {
     transition-property: opacity, scale, translate;
-    will-change: opacity, scale, translate;
   }
 
   @container media-root (width > 42rem) {
@@ -3302,7 +3262,7 @@ export const { Player } = createPlayer({ features: audioFeatures });
 @media (prefers-reduced-motion: reduce) {
   .media-default-skin .media-button {
     scale: 1;
-    transition-property: background-color, color, outline-offset;
+    transition-property: background-color, color;
     will-change: auto;
   }
 }
@@ -3874,7 +3834,6 @@ export const { Player } = createPlayer({ features: audioFeatures });
     transition-timing-function: ease-out;
     transition-duration: var(--menu-transition-duration);
     transition-property: translate, filter;
-    will-change: translate, filter;
 
     &:where([data-starting-style], [data-ending-style]) {
       overflow: hidden;
@@ -4058,7 +4017,6 @@ export const { Player } = createPlayer({ features: audioFeatures });
       transition:
         translate var(--menu-transition-duration) ease-out,
         filter var(--menu-transition-duration) ease-out;
-      will-change: translate, filter;
     }
 
     &[data-submenu-expanded="true"] > :not([data-submenu]) {
@@ -4457,7 +4415,6 @@ export interface VideoPlayerProps {
   style?: CSSProperties;
   className?: string;
   renderPoster?: Poster.Props['render'];
-  placeholder?: string | undefined;
 }
 
 /**
@@ -4469,18 +4426,10 @@ export interface VideoPlayerProps {
  * />
  * ```
  */
-export function VideoPlayer({ src, poster, className, renderPoster, placeholder, style, ...rest }: VideoPlayerProps): ReactNode {
-  const containerStyle = placeholder
-    ? ({ '--media-poster-placeholder': `url(${placeholder})`, ...style } as CSSProperties)
-    : style;
-
+export function VideoPlayer({ src, poster, className, renderPoster, style, ...rest }: VideoPlayerProps): ReactNode {
   return (
     <Player poster={poster}>
-      <Container
-        className={`media-minimal-skin media-minimal-skin--video ${className ?? ''}`}
-        style={containerStyle}
-        {...rest}
-      >
+      <Container className={`media-minimal-skin media-minimal-skin--video ${className ?? ''}`} style={style} {...rest}>
         <Video src={src} playsInline />
 
         <Poster render={renderPoster} />
@@ -5237,7 +5186,7 @@ export const { Player } = createPlayer({ features: videoFeatures });
 @media (prefers-reduced-motion: reduce) {
   .media-minimal-skin .media-button {
     scale: 1;
-    transition-property: background-color, outline-offset;
+    transition-property: background-color;
     will-change: auto;
   }
 }
@@ -5282,8 +5231,7 @@ export const { Player } = createPlayer({ features: videoFeatures });
   transition: opacity 0.25s;
 }
 .media-minimal-skin media-poster:not([data-visible]),
-.media-minimal-skin > img:not([data-visible]),
-.media-minimal-skin > img[data-visible]:not([data-loaded]) {
+.media-minimal-skin > img:not([data-visible]) {
   opacity: 0;
 }
 .media-minimal-skin media-poster ::slotted(img),
@@ -5302,30 +5250,6 @@ export const { Player } = createPlayer({ features: videoFeatures });
   border-radius: inherit;
 }
 
-/* Blurred placeholder: HTML path targets media-poster::before, React path targets the skin container::before */
-.media-minimal-skin media-poster::before,
-.media-minimal-skin::before {
-  position: absolute;
-  inset: 0;
-  pointer-events: none;
-  content: "";
-  background-image: var(--media-poster-placeholder, none);
-  background-repeat: no-repeat;
-  background-position: var(--media-object-position, center);
-  background-size: var(--media-object-fit, contain);
-  filter: blur(var(--media-poster-placeholder-blur, 20px));
-}
-
-/* React path: hidden by default, transitions in while poster loads */
-.media-minimal-skin::before {
-  opacity: 0;
-  transition: opacity 0.25s;
-}
-/* Show placeholder while the poster is visible but not yet loaded */
-.media-minimal-skin:has(img[data-visible]:not([data-loaded]))::before {
-  opacity: 1;
-}
-
 .media-minimal-skin:fullscreen media-poster ::slotted(img),
 .media-minimal-skin:fullscreen media-poster img,
 .media-minimal-skin:fullscreen > img {
@@ -5932,7 +5856,6 @@ export const { Player } = createPlayer({ features: videoFeatures });
     transition-timing-function: ease-out;
     transition-duration: var(--menu-transition-duration);
     transition-property: translate, filter;
-    will-change: translate, filter;
 
     &:where([data-starting-style], [data-ending-style]) {
       overflow: hidden;
@@ -6111,7 +6034,6 @@ export const { Player } = createPlayer({ features: videoFeatures });
       transition:
         translate var(--menu-transition-duration) ease-out,
         filter var(--menu-transition-duration) ease-out;
-      will-change: translate, filter;
     }
 
     &[data-submenu-expanded="true"] > :not([data-submenu]) {
@@ -6667,12 +6589,10 @@ export const { Player } = createPlayer({ features: videoFeatures });
 
   @media (pointer: fine) {
     transition-property: translate, filter, opacity;
-    will-change: translate, filter, opacity;
   }
 
   @media (pointer: coarse) {
     transition-property: translate, opacity;
-    will-change: translate, opacity;
   }
 
   &:not([data-visible]) {
@@ -7460,7 +7380,7 @@ export const { Player } = createPlayer({ features: audioFeatures });
 @media (prefers-reduced-motion: reduce) {
   .media-minimal-skin .media-button {
     scale: 1;
-    transition-property: background-color, outline-offset;
+    transition-property: background-color;
     will-change: auto;
   }
 }
@@ -8031,7 +7951,6 @@ export const { Player } = createPlayer({ features: audioFeatures });
     transition-timing-function: ease-out;
     transition-duration: var(--menu-transition-duration);
     transition-property: translate, filter;
-    will-change: translate, filter;
 
     &:where([data-starting-style], [data-ending-style]) {
       overflow: hidden;
@@ -8210,7 +8129,6 @@ export const { Player } = createPlayer({ features: audioFeatures });
       transition:
         translate var(--menu-transition-duration) ease-out,
         filter var(--menu-transition-duration) ease-out;
-      will-change: translate, filter;
     }
 
     &[data-submenu-expanded="true"] > :not([data-submenu]) {

package/docs/how-to/migrate-from-mux-player.md

@@ -243,17 +243,23 @@ The poster is a skin concern. Build an `image.mux.com` URL and hand it over:
 jsx
 
 ```
-<VideoSkin
-  poster="https://image.mux.com/EcHgOK9coz5K…/thumbnail.webp?time=2"
-  placeholder="data:image/webp;base64,…"
->
-  <MuxVideo source={{ playbackId: 'EcHgOK9coz5K…' }} />
-</VideoSkin>
+<VideoPlayer poster="https://image.mux.com/EcHgOK9coz5K…/thumbnail.webp?time=2">
+  <VideoSkin
+    renderPoster={
+      <img
+        alt=""
+        style={{ background: "url('data:image/webp;base64,…') center / contain no-repeat" }}
+      />
+    }
+  >
+    <MuxVideo source={{ playbackId: 'EcHgOK9coz5K…' }} />
+  </VideoSkin>
+</VideoPlayer>
 ```
 
-`placeholder` is the blurred stand-in shown while the real poster loads, Mux Player’s `placeholder`.
+`renderPoster` customizes the poster image, so its background can show Mux Player’s `placeholder` while the real poster loads.
 
-Mux serves the poster from its `thumbnail` endpoint, so every Mux Player poster attribute becomes a query parameter you append: `thumbnail-time` is `?time=`, and the size, crop, rotation, and format options work the same way. See the [Poster](../reference/poster.md) reference for the component itself.
+Mux serves the poster from its `thumbnail` endpoint, so every Mux Player poster attribute becomes a query parameter you append: `thumbnail-time` is `?time=`, and the size, crop, rotation, and format options work the same way. See [Add a poster placeholder](./add-a-poster-placeholder.md) for more examples or the [Poster](../reference/poster.md) reference for the component itself.
 
 ## Customize your player
 

package/docs/llms.txt

@@ -40,6 +40,7 @@ Understanding-oriented pages that explain how and why things work. Read these to
 Task-oriented guides with step-by-step instructions to achieve a specific outcome by applying one or more concepts. Each guide may assume you already understand the relevant concepts.
 
 - [Customize skins](./how-to/customize-skins.md): Learn how to customize Video.js v10 skins by copying and modifying them
+- [Add a poster placeholder](./how-to/add-a-poster-placeholder.md): Show a lightweight placeholder while the poster image loads
 - [Build your own UI component](./how-to/build-your-own-component.md): Create custom player controls that read state, dispatch actions, and stay accessible.
 ### Internationalization
 
@@ -84,6 +85,7 @@ API Reference for UI components for building media player interfaces.
 - [Thumbnail](./reference/thumbnail.md): Time-based thumbnail preview component for timeline scrubbing and hover previews
 - [Time](./reference/time.md): Time display components for showing current time, duration, and remaining time in a video player
 - [TimeSlider](./reference/time-slider.md): A slider component for seeking through media playback time
+- [Title](./reference/title.md): Displays the resolved content title for the current media
 - [Tooltip](./reference/tooltip.md): A tooltip component for displaying contextual labels on hover and focus
 - [VolumeSlider](./reference/volume-slider.md): A slider component for controlling media playback volume
 
@@ -110,6 +112,7 @@ API reference for the feature modules passed to createPlayer, which provide play
 - [Error](./reference/feature-error.md): Media error state and actions for the player store
 - [Fullscreen](./reference/feature-fullscreen.md): Fullscreen state and actions for the player store
 - [Live](./reference/feature-live.md): Live edge state for the player store
+- [Metadata](./reference/feature-metadata.md): Resolved title and poster values for the player store
 - [Orientation lock](./reference/feature-orientation-lock.md): Screen orientation locking while fullscreen is active
 - [Picture-in-picture](./reference/feature-pip.md): Picture-in-picture state and actions for the player store
 - [Playback](./reference/feature-playback.md): Play/pause state and actions for the player store

package/docs/reference/feature-fullscreen.md

@@ -97,15 +97,16 @@ function FullscreenButton() {
 
 Add [`features.orientationLock`](./feature-orientation-lock.md) to lock screen orientation while fullscreen is active. Unsupported browsers and rejected lock requests are ignored, so iOS Safari continues to use its normal fullscreen behavior.
 
-By default, the feature locks to `landscape`. Pass a Screen Orientation API type to customize it:
+The feature locks to `landscape` unless the provider sets another Screen Orientation API type.
 
-ts
+tsx
 
 ```
-import { createPlayer, features } from '@videojs/react';
-import { videoFeatures } from '@videojs/react/video';
+<Player orientationLockType="portrait">
+  <Container>
+    <video src="/video.mp4" />
+  </Container>
+</Player>
+```
 
-const { Player } = createPlayer({
-  features: [...videoFeatures, features.orientationLock({ type: 'portrait' })],
-});
-```
+See [Orientation lock](./feature-orientation-lock.md) for the player setup.

package/docs/reference/feature-metadata.md

@@ -0,0 +1,129 @@
+# Metadata
+
+Resolved title and poster values for the player store
+
+Resolves what is playing into two values your UI can render: `title` and `poster`.
+
+`title` and `poster` each resolve independently through the same two tiers: the value you set, then the value the media reports. The first tier that holds a value wins; when neither does, the resolved value is an empty string. Because the tiers stay separate, clearing the value you set reveals the media’s, and a source that reports a poster but no title contributes to one while leaving the other empty.
+
+An empty string counts as a value and stops the chain: set `title` to `''` and the resolved title is `''`. Pass `null` to clear your value.
+
+The metadata feature is included by the `videoFeatures`, `audioFeatures`, `liveVideoFeatures`, and `liveAudioFeatures` [presets](../concepts/presets.md); apps that build a custom preset can compose it in directly.
+
+## API Reference
+
+### Configuration
+
+Props the Player component accepts. They exist only while this feature is selected.
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`title`
+
+`undefined | null | string`
+
+`—`
+
+▸
+
+Description
+
+The title to display. Takes precedence over the title the media carries.
+
+`poster`
+
+`undefined | null | string`
+
+`—`
+
+▸
+
+Description
+
+The poster to display. Takes precedence over the poster the media carries.
+
+### State
+
+Property
+
+Type
+
+Details
+
+`title`
+
+`string`
+
+▸
+
+Description
+
+The resolved content title. Set it through the player, not through the store.
+
+`poster`
+
+`string`
+
+▸
+
+Description
+
+The resolved poster URL, independent of the media element's own `poster`. Set it through the player, not through the store.
+
+### Selector
+
+Pass `selectMetadata` to [`usePlayer`](./use-player.md) to subscribe to metadata state. Returns `undefined` if the metadata feature is not configured.
+
+ContentTitle.tsx
+
+```
+import { selectMetadata, usePlayer } from '@videojs/react';
+
+function ContentTitle() {
+  const metadata = usePlayer(selectMetadata);
+  if (!metadata?.title) return null;
+
+  return <h2 className="content-title">{metadata.title}</h2>;
+}
+```
+
+### Player inputs
+
+The store publishes the resolved values and takes no writes. A player input is the only way to set one.
+
+Every input is a prop on [`Player`](./player-provider.md). A player built without the metadata feature has none of them, and none is forwarded.
+
+App.tsx
+
+```
+import { Container, createPlayer } from '@videojs/react';
+import { videoFeatures } from '@videojs/react/video';
+
+const { Player } = createPlayer({ features: videoFeatures });
+
+function App({ episode }: { episode: { title: string | null; art: string | null } }) {
+  return (
+    <Player title={episode.title} poster={episode.art}>
+      <Container>
+        <video src="episode.mp4" />
+      </Container>
+    </Player>
+  );
+}
+```
+
+Passing `null` clears your value, so `title={null}` falls through to the title the media reports.
+
+### Media-reported values
+
+The media tier comes from media that reports content data and announces changes to it, and it covers `title` and `poster`. A media reports only the keys it can vouch for, so either may be absent while the other arrives. A key that never arrives means that tier never contributes, and the resolved value is whatever you set. Detaching the media clears its values; the values you set survive and apply to the next source.
+
+`poster` is the feature’s own resolved value, not the media element’s `poster` attribute. Setting one does not set the other.
+
+A low-resolution stand-in to show while the poster loads is not part of this feature. The [poster](./poster.md) renders an `<img>` you control, so give it a `background-image` and that shows until the poster itself paints over it.

package/docs/reference/feature-orientation-lock.md

@@ -6,14 +6,74 @@ Locks screen orientation while fullscreen is active. Add it explicitly to a feat
 
 ## API Reference
 
+### Configuration
+
+Props the Player component accepts. They exist only while this feature is selected.
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`orientationLockType`
+
+`undefined | null | 'any' | 'landscape' | 'landscape-primary' | 'landscape-secondary' | 'natural' | 'portrait' | 'portrait-primary' | 'portrait-secondary'`
+
+`'landscape'`
+
+▸
+
+Description
+
+Screen orientation type to lock while fullscreen is active.
+
+### State
+
+Property
+
+Type
+
+Details
+
+`orientationLockType`
+
+`'any' | 'landscape' | 'landscape-primary' | 'landscape-secondary' | 'natural' | 'portrait' | 'portrait-primary' | 'portrait-secondary'`
+
+▸
+
+Description
+
+Screen orientation type locked while fullscreen is active.
+
+### Actions
+
+Action
+
+Type
+
+Details
+
+`setOrientationLockType`
+
+`(value: undefined | null | 'any' | 'landscape' | 'landscape-primary' | 'landscape-secondary' | 'natural' | 'portrait' | 'portrait-primary' | 'portrait-secondary') => void`
+
+▸
+
+Description
+
+Sets the locked orientation type. Absent input — nullish, or the empty string a valueless HTML attribute produces — restores the default.
+
 ### Usage
 
-By default, the feature locks to `landscape`. Pass a Screen Orientation API type to customize it.
+Selecting the feature adds it to the player.
 
 player.tsx
 
 ```
-import { createPlayer, features } from '@videojs/react';
+import { Container, createPlayer, features } from '@videojs/react';
 import { videoFeatures } from '@videojs/react/video';
 
 export const { Player } = createPlayer({
@@ -21,15 +81,41 @@ export const { Player } = createPlayer({
 });
 ```
 
-portrait-player.tsx
+### Orientation type
+
+The feature locks to `landscape` unless the provider sets another Screen Orientation API type. The value can change while the player is running; if the screen is already locked, it re-locks to the new type.
+
+tsx
 
 ```
-import { createPlayer, features } from '@videojs/react';
-import { videoFeatures } from '@videojs/react/video';
+<Player orientationLockType="portrait">
+  <Container>
+    <video src="/video.mp4" />
+  </Container>
+</Player>
+```
 
-export const { Player } = createPlayer({
-  features: [...videoFeatures, features.orientationLock({ type: 'portrait' })],
-});
+Clearing the value restores `landscape`.
+
+### Selector
+
+Pass `selectOrientationLock` to [`usePlayer`](./use-player.md) to subscribe to the lock state. Returns `undefined` if the orientation lock feature is not configured.
+
+OrientationToggle.tsx
+
+```
+import { selectOrientationLock, usePlayer } from '@videojs/react';
+
+function OrientationToggle() {
+  const lock = usePlayer(selectOrientationLock);
+  if (!lock) return null;
+
+  return (
+    <button onClick={() => lock.setOrientationLockType('portrait')}>
+      Lock portrait
+    </button>
+  );
+}
 ```
 
 Unsupported browsers and rejected lock requests are ignored.

package/docs/reference/feature-text-tracks.md

@@ -46,6 +46,16 @@ Description
 
 The `<track>` element's `src` for resolving relative cue text URLs.
 
+`thumbnailTrackCrossOrigin`
+
+`null | 'anonymous' | 'use-credentials'`
+
+▸
+
+Description
+
+The media element's CORS mode, mapped through the CORS-settings-attribute rules, or `null` when it is not in CORS mode. Thumbnail UI fetches the sprite sheets the cues point at with this mode, since a cross-origin `<track>` only loads at all when the media element is CORS-enabled.
+
 `textTrackList`
 
 `MediaTextTrack<TextTrackKind>[]`

package/docs/reference/menu.md

@@ -442,7 +442,6 @@ export default function BasicUsage() {
   transition-timing-function: ease-in-out;
   transition-duration: var(--menu-transition-duration);
   transition-property: translate, filter;
-  will-change: translate;
 }
 
 .menu[data-submenu-expanded="true"] > :not([data-submenu]) {

package/docs/reference/thumbnail.md

@@ -227,6 +227,10 @@ Description
 
 CORS setting forwarded to the inner `<img>`.
 
+Left unset, this follows the media element: a cross-origin thumbnail `<track>` only loads when the media is CORS-enabled, so the sprite sheets its cues point at are fetched with that same mode. Pass `null` to opt out and fetch them without CORS. Thumbnails supplied directly never inherit, since they need not be related to the media element at all.
+
+`''` is a value like any other, read as Anonymous by the CORS-settings attribute rules — it does not opt out.
+
 Type
 
 `'anonymous' | 'use-credentials' | '' | null`