@videojs/html 10.0.0-rc.4 → 10.0.0-rc.5

package/docs/reference/api/preset-video.md

@@ -0,0 +1,123 @@
+# Video preset
+
+The general-purpose video preset — a player, feature bundle, skins, and media for on-demand video
+
+`@videojs/html/video` is the general-purpose preset for on-demand video. It bundles the `<video-player>` element, the `videoFeatures` bundle it is configured with, and two skins, and plays through the browser’s native `<video>`. See [Presets](../../guides/presets.md) for how presets fit together and how to customize one.
+
+## Import
+
+```ts
+import '@videojs/html/video/player';
+import '@videojs/html/video/skin';
+```
+
+Import `@videojs/html/video/neutral-skin` instead for the neutral skin. Or load one [CDN](../../guides/cdn.md) bundle that registers the player and a skin together:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.5/video.js"></script>
+```
+
+`video-neutral.js` registers the neutral skin instead, and `video-player.js` registers `<video-player>` alone.
+
+## Usage
+
+**index.html**
+
+```html
+<script type="module">
+  import '@videojs/html/video/player';
+  import '@videojs/html/video/skin';
+</script>
+
+<video-player>
+  <video-skin>
+    <video src="video.mp4"></video>
+  </video-skin>
+</video-player>
+```
+
+## Player
+
+`@videojs/html/video/player` registers `<video-player>`, whose class is `VideoPlayerElement`. It is a [player](../components/player.md) element created by [`createPlayer`](./html-create-player.md) with `videoFeatures`. It owns the player store but no layout. Put a skin or a [`<media-container>`](../components/player-container.md) inside it.
+
+| Attribute | Property | Description |
+| --- | --- | --- |
+| `content-title` | `contentTitle` | The title to display. Takes precedence over the title the media reports. |
+| `poster` | `poster` | The poster to display. Takes precedence over the poster the media reports. |
+| `keep-alive` | — | Keeps the player and its store alive when the element leaves the DOM. Call `destroy()` when you’re done with it. |
+
+`content-title` and `poster` come from the [metadata feature](./feature-metadata.md#player-inputs). The element’s read-only `store` property returns its player store.
+
+The preset root also exports a `PlayerController` bound to the video player’s store. Use it from any custom element inside `<video-player>`; see [`PlayerController`](./player-controller.md).
+
+## Feature bundle
+
+`videoFeatures` is the array of [features](../../guides/features.md) the player is configured with:
+
+| Feature | Description |
+| --- | --- |
+| [`playbackFeature`](./feature-playback.md) | Play/pause state and actions for the player store |
+| [`playbackRateFeature`](./feature-playback-rate.md) | Playback speed state and actions for the player store |
+| [`qualityFeature`](./feature-quality.md) | Video rendition state and actions for the player store |
+| [`audioTrackFeature`](./feature-audio-track.md) | Audio track state and actions for the player store |
+| [`volumeFeature`](./feature-volume.md) | Volume level and mute state for the player store |
+| [`timeFeature`](./feature-time.md) | Playback position and duration state for the player store |
+| [`sourceFeature`](./feature-source.md) | Media source state and actions for the player store |
+| [`bufferFeature`](./feature-buffer.md) | Buffered and seekable time range state for the player store |
+| [`fullscreenFeature`](./feature-fullscreen.md) | Fullscreen state and actions for the player store |
+| [`pipFeature`](./feature-pip.md) | Picture-in-picture state and actions for the player store |
+| [`remotePlaybackFeature`](./feature-remote-playback.md) | Remote playback state and actions for the player store |
+| [`controlsFeature`](./feature-controls.md) | User activity and controls visibility state for the player store |
+| [`textTrackFeature`](./feature-text-tracks.md) | Subtitles, captions, and chapter track state for the player store |
+| [`errorFeature`](./feature-error.md) | Media error state and actions for the player store |
+| [`metadataFeature`](./feature-metadata.md) | Resolved title and poster values for the player store |
+
+Its type, `VideoFeatures`, is the tuple of those features in order. Import it from the package root:
+
+```ts
+import type { VideoFeatures } from '@videojs/html';
+```
+
+To add or remove a feature, pass your own array to `createPlayer`. The skins expect the features they render controls for.
+
+```ts
+import { createPlayer, orientationLockFeature } from '@videojs/html';
+import { videoFeatures } from '@videojs/html/video';
+
+const { PlayerElement } = createPlayer({
+  features: [...videoFeatures, orientationLockFeature],
+});
+
+customElements.define('my-video-player', PlayerElement);
+```
+
+## Skins
+
+- [VideoSkin](../components/video-skin.md) — the default skin, with the modern, frosted look.
+- [NeutralVideoSkin](../components/video-neutral-skin.md) — the visually lighter variant, closer to a classic control bar.
+
+## Media
+
+The preset plays through a native [`<video>`](../components/video.md), so it registers no media element of its own. Swap it for any compatible [media element](../../guides/media-sources.md), such as [`<hlsjs-video>`](../components/hlsjs-video.md) for HLS.
+
+## Exports
+
+The preset root, `@videojs/html/video`, has no side effects. Importing it never registers an element:
+
+| Export | Description |
+| --- | --- |
+| `VideoPlayerElement` | The [player](#player) element class. |
+| `PlayerController` | The player controller, bound to the video player’s store. |
+| `videoFeatures` | The [feature bundle](#feature-bundle). |
+| `VideoSkinElement` | The default [skin](#skins) element class. |
+| `NeutralVideoSkinElement` | The neutral [skin](#skins) element class. |
+
+Registration entry points are side-effect-only:
+
+| Entry point | Registers |
+| --- | --- |
+| `@videojs/html/video/player` | `<video-player>` |
+| `@videojs/html/video/skin` | `<video-skin>`, `<media-container>`, and the UI elements the skin composes |
+| `@videojs/html/video/neutral-skin` | `<video-neutral-skin>`, `<media-container>`, and the UI elements the neutral skin composes |
+| `@videojs/html/video/ui` | `<media-container>` and the UI elements of the default skin, without the skin, for a layout you write yourself |
+| `@videojs/html/video/neutral-ui` | `<media-container>` and the UI elements of the neutral skin, without the skin |

package/docs/reference/api/register-i18n.md

@@ -23,6 +23,19 @@ registerI18n('es', {
 });
 ```
 
+## Built-in locale packs
+
+Each shipped pack is a module named after its locale tag. Its default export is the pack’s `Translations` map. Pass it to `registerI18n` when you load a pack yourself, for example right before switching to that locale:
+
+```ts
+import { registerI18n } from '@videojs/html/i18n';
+import ja from '@videojs/html/i18n/locales/ja';
+
+registerI18n('ja', ja);
+```
+
+A side-effect import of the pack’s `/register` subpath, such as `import '@videojs/html/i18n/locales/ja/register'`, does the same.
+
 ## API Reference
 
 `registerI18n(locale, translations): void`

package/docs/reference/api/resolve-adapter-type.md

@@ -0,0 +1,98 @@
+# resolveAdapterType
+
+Resolve which type of adapter plays a source URL, from its host, MIME type, or file extension
+
+## Import
+
+```ts
+import { resolveAdapterType } from '@videojs/html';
+```
+
+`resolveAdapterType` reads a source URL and returns the type of adapter that plays it, so an app that plays sources from a catalog or from user input can pick the matching [media component](../../guides/media-sources.md). It returns `null` for sources it doesn’t recognize.
+
+Resolution is a pure string check. It doesn’t fetch the source, load an engine, or touch the DOM. It doesn’t rewrite the source either: every source it recognizes, [shorthands](#shorthands) included, is one the matching media component accepts as its `src`.
+
+## Usage
+
+Look up the media element for the result and give it the same `src`:
+
+```ts
+import { resolveAdapterType } from '@videojs/html';
+import '@videojs/html/media/hlsjs-video';
+import '@videojs/html/media/vimeo-video';
+import '@videojs/html/media/youtube-video';
+
+const TAGS = { youtube: 'youtube-video', vimeo: 'vimeo-video', hls: 'hlsjs-video', video: 'video' } as const;
+
+function createMedia(src: string) {
+  const type = resolveAdapterType(src);
+  const tag = type && type in TAGS ? TAGS[type as keyof typeof TAGS] : null;
+  if (!tag) return null;
+
+  const media = document.createElement(tag);
+  media.setAttribute('src', src);
+  return media;
+}
+```
+
+Each media module you import adds its engine to your bundle, so import the rarely used ones dynamically.
+
+### Adapter types
+
+| Adapter type | Recognized sources | Media element |
+| --- | --- | --- |
+| `youtube` | `youtube.com`, `youtu.be`, and `youtube-nocookie.com` video and playlist URLs | `<youtube-video>` |
+| `vimeo` | `vimeo.com` and `player.vimeo.com` URLs | `<vimeo-video>` |
+| `wistia` | `wistia.com`, `wistia.net`, and `wi.st` URLs, and pages with a `wvideo` parameter | `<wistia-video>` |
+| `mux` | `stream.mux.com` stream URLs, with or without `.m3u8` | `<mux-video>` or `<mux-audio>` |
+| `cloudflare` | `cloudflarestream.com` and `videodelivery.net` URLs | `<cloudflare-video>` |
+| `spotify` | `open.spotify.com` URLs and `spotify:` URIs | `<spotify-audio>` |
+| `tiktok` | `tiktok.com` video URLs | `<tiktok-video>` |
+| `twitch` | `twitch.tv` video and channel URLs | `<twitch-video>` |
+| `hls` | `.m3u8` files and HLS MIME types | `<hls-video>`, `<hlsjs-video>`, or `<native-hls-video>` |
+| `dash` | `.mpd` files and `application/dash+xml` | `<dash-video>` or `<shaka-video>` |
+| `video` | `.mp4`, `.webm`, `.mov`, and `.ogv` files, and `video/*` MIME types | `<video>` |
+| `audio` | `.mp3`, `.m4a`, `.wav`, `.ogg`, `.flac`, and `.aac` files, and `audio/*` MIME types | `<audio>` |
+
+`hls` covers every HLS adapter and `dash` every DASH adapter, so an HLS stream comes back as `hls` whichever one you play it with; see [Media sources](../../guides/media-sources.md) to choose one. Mux streams served from a custom domain are recognized as plain `hls`.
+
+### MIME types
+
+Pass a MIME type as the second argument when the URL doesn’t end in a file extension, such as an extensionless manifest or a `blob:` URL. The MIME type takes precedence over the extension; service URLs, such as YouTube or Mux, resolve the same either way.
+
+```ts
+resolveAdapterType('https://example.com/manifest', 'application/vnd.apple.mpegurl'); // 'hls'
+```
+
+To get the MIME type a file extension implies, use [`resolveMimeType`](./resolve-mime-type.md).
+
+### Bare ids
+
+A bare id returns `null`. An 11-character YouTube id and a 10-character Wistia id look alike, so services are only recognized from URLs, `spotify:` URIs, and [shorthands](#shorthands). If you already know the service, pass the id to its media component directly.
+
+### Shorthands
+
+`resolveAdapterType` recognizes these shorthands, and the YouTube and Vimeo media accept them as `src`:
+
+| Shorthand | Plays |
+| --- | --- |
+| `youtube/<id>`, `youtube/shorts/<id>` | The YouTube video, from the privacy-enhanced `youtube-nocookie.com` host |
+| `vimeo/<id>` | The Vimeo video |
+| `vimeo/<id>?hash=<hash>`, `vimeo/<id>?h=<hash>`, `vimeo/<id>/<hash>` | The unlisted Vimeo video |
+
+## API Reference
+
+`resolveAdapterType(src, type?): AdapterType | null`
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `src` (required) | `string` | — | The source URL, or a `youtube/<id>` or `vimeo/<id>` shorthand. |
+| `type` | `string` | — | The source's MIME type, when known. It takes precedence over the file extension, so manifests and files without one can still be resolved. Parameters such as `codecs` are ignored. |
+
+### Return Value
+
+| Type |
+| --- |
+| `'youtube' \| 'vimeo' \| 'wistia' \| 'mux' \| 'cloudflare' \| 'spotify' \| 'tiktok' \| 'twitch' \| 'hls' \| 'dash' \| 'video' \| 'audio' \| null` |

package/docs/reference/api/resolve-mime-type.md

@@ -0,0 +1,48 @@
+# resolveMimeType
+
+Resolve a source's MIME type from its file extension
+
+## Import
+
+```ts
+import { resolveMimeType } from '@videojs/html';
+```
+
+`resolveMimeType` returns the MIME type a source URL’s file extension implies, ignoring the query string and hash. It returns `null` when the URL has no extension or one it doesn’t recognize.
+
+```ts
+resolveMimeType('https://example.com/live/stream.m3u8?token=abc'); // 'application/x-mpegurl'
+resolveMimeType('/media/podcast.mp3'); // 'audio/mpeg'
+resolveMimeType('https://youtu.be/_cMxraX_5RE'); // null
+```
+
+| Extension | MIME type |
+| --- | --- |
+| `.m3u8` | `application/x-mpegurl` |
+| `.mpd` | `application/dash+xml` |
+| `.mp4` | `video/mp4` |
+| `.webm` | `video/webm` |
+| `.mov` | `video/quicktime` |
+| `.ogv` | `video/ogg` |
+| `.mp3` | `audio/mpeg` |
+| `.m4a` | `audio/mp4` |
+| `.wav` | `audio/wav` |
+| `.ogg` | `audio/ogg` |
+| `.flac` | `audio/flac` |
+| `.aac` | `audio/aac` |
+
+To find which media component plays a source, use [`resolveAdapterType`](./resolve-adapter-type.md).
+
+## API Reference
+
+`resolveMimeType(src): string | null`
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `src` (required) | `string` | — | The source URL. |
+
+### Return Value
+
+`string | null`

package/docs/reference/api/resolve-translation.md

@@ -0,0 +1,36 @@
+# resolveTranslation
+
+Translate a key with the params its English default requires
+
+## Import
+
+```ts
+import { resolveTranslation } from "@videojs/html/i18n";
+```
+
+`resolveTranslation` calls a translator from [`createTranslator`](./create-translator.md) with a key and its params. Unlike calling the translator directly with a variable key, its type requires the params that key’s English default interpolates, such as `seconds` for `seek.forward`.
+
+```ts
+import { createTranslator, getI18nTranslations, resolveTranslation } from '@videojs/html/i18n';
+
+const t = createTranslator(getI18nTranslations('fr'), 'fr');
+
+resolveTranslation(t, 'buttons.play');
+resolveTranslation(t, 'seek.forward', { seconds: 10 });
+```
+
+## API Reference
+
+`resolveTranslation<Key extends string>(translator, key, ...args): string`
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `translator` (required) | `{ <Key extends string>(key: Key, ...args: Key extends TranslationKey ? TranslationParams[Key] extends never ? [params?: TranslationOptions] : [params: TranslationParams[Key] & TranslationOptions] : [params?: TextParams & TranslationOptions]): string; (text: Text, params?: TextParams): string }` | — | Translator from `createTranslator`. |
+| `key` (required) | `Key` | — | Translation key, such as `seek.forward`. |
+| `args` | `Key extends TranslationKey ? TranslationParams[Key] extends never ? [params?: TranslationOptions] : [params: TranslationParams[Key] & TranslationOptions] : [params?: Record<string, string \| number> & TranslationOptions]` | — | The key's template params, plus an optional `default` string. |
+
+### Return Value
+
+`string`

package/docs/reference/api/translate-text.md

@@ -0,0 +1,56 @@
+# translateText
+
+Translate a text descriptor, or fall back to its English default
+
+## Import
+
+```ts
+import { translateText } from "@videojs/html/i18n";
+```
+
+`translateText` translates a text descriptor with a translator from [`createTranslator`](./create-translator.md). Without one, it fills the descriptor’s English default with the params. A plain string is returned as is, so a label can be either.
+
+```ts
+import { createTranslator, getI18nTranslations, translateText } from '@videojs/html/i18n';
+import { forwardText } from '@videojs/html/i18n/text/seek';
+
+translateText(forwardText, { seconds: 10 }); // 'Seek forward 10 seconds'
+
+const t = createTranslator(getI18nTranslations('fr'), 'fr');
+translateText(forwardText, t, { seconds: 10 });
+```
+
+## API Reference
+
+### Overload 1
+
+`translateText(text, params?): string`
+
+Translate a text descriptor with a translator, or interpolate its English default without one. A plain string is returned as is.
+
+#### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `text` (required) | `{ key: string; text: string } \| string` | — | Text descriptor, or a string returned unchanged. |
+| `params` | `Record<string, string \| number>` | — | Values for the text's `{placeholders}`. |
+
+#### Return Value
+
+`string`
+
+### Overload 2
+
+`translateText(text, translator, params?): string`
+
+#### Parameters
+
+| Parameter | Type | Default |
+| --- | --- | --- |
+| `text` (required) | `{ key: string; text: string } \| string` | — |
+| `translator` (required) | `{ <Key extends string>(key: Key, ...args: Key extends TranslationKey ? TranslationParams[Key] extends never ? [params?: TranslationOptions] : [params: TranslationParams[Key] & TranslationOptions] : [params?: TextParams & TranslationOptions]): string; (text: Text, params?: TextParams): string } \| undefined` | — |
+| `params` | `Record<string, string \| number>` | — |
+
+#### Return Value
+
+`string`

package/docs/reference/api/translation-phrases.md

@@ -6,6 +6,19 @@ Video.js uses opaque semantic keys so English copy can change without breaking t
 
 Locale packs and provider overrides use nested objects, so `buttons.play` is authored as `{ buttons: { play: '…' } }`. Translators and the `<media-text token>` attribute use the dotted form.
 
+## Text descriptors
+
+Each key also ships as a text descriptor: an object with the `key` and its English default `text`. Descriptors are grouped by the key’s first segment and named after the rest, so `buttons.play` is `playText` in the `buttons` module and `container.label` is `labelText` in `container`. Pass one to a translator, or to [`translateText`](./translate-text.md), to get the active locale’s copy with English as the fallback.
+
+```ts
+import { createTranslator, getI18nTranslations } from '@videojs/html/i18n';
+import { playText } from '@videojs/html/i18n/text/buttons';
+
+const t = createTranslator(getI18nTranslations('fr'), 'fr');
+
+t(playText); // 'Lecture' once French is registered, else 'Play'
+```
+
 ## Playback controls
 
 | Key | English default | Used by |