mirror of
https://github.com/videojs/video.js.git
synced 2026-11-22 09:03:20 +01:00
222 lines
8.3 KiB
TypeScript
222 lines
8.3 KiB
TypeScript
import type { MuxSource } from '@videojs/media/dom/mux';
|
|
import { escapeHtml } from '@videojs/utils/string';
|
|
|
|
import { applyCaptionTracks } from '../captions';
|
|
import { findMediaTag } from '../media-element';
|
|
import {
|
|
getDirection,
|
|
getInitialPlaybackOverrides,
|
|
onDirectionChange,
|
|
onSandboxStateChange,
|
|
type PlaybackOverrides,
|
|
readSandboxState,
|
|
type SandboxState,
|
|
} from '../sandbox-listener';
|
|
import { installSandboxMirror } from '../sandbox-mirror';
|
|
import { getChapters, getPlaceholderSrc, getPosterSrc, getStoryboardSrc, isLiveSource, SOURCES } from '../sources';
|
|
import { renderChapters } from './chapters';
|
|
import { bindSandboxHtmlLocaleChange, prepareSandboxHtmlLocale, wrapSandboxHtmlI18n } from './i18n';
|
|
import { defineNoSkin } from './no-skin';
|
|
import { loadHtmlSkinTag } from './skins';
|
|
import { renderStoryboard } from './storyboard';
|
|
|
|
/** Tag for markup literals. `String.raw`, so a template reads as the HTML it produces. */
|
|
export const html = String.raw;
|
|
|
|
/** The player a page mounts, which fixes its element, its skin family, and the frame around them. */
|
|
export type HtmlSandboxPlayer = 'video' | 'audio' | 'background';
|
|
|
|
/** A source assigned as an object, for what a `src` attribute cannot carry: tokens, license servers, engine options. */
|
|
export type HtmlSandboxSource = MuxSource | ({ src: string } & PlaybackOverrides);
|
|
|
|
/** What a template's markup can read: the shell's selections plus what the runtime derived from them. */
|
|
export interface HtmlSandboxContext {
|
|
readonly state: Readonly<SandboxState>;
|
|
/** The live player and skin variants are in use for this render. */
|
|
readonly live: boolean;
|
|
/** The player element for this render, such as `video-player` or `live-audio-player`. */
|
|
readonly playerTag: string;
|
|
/**
|
|
* The skin element the shell selected and the runtime registered, such as `video-skin` or `audio-neutral-skin`, or a
|
|
* bare frame when it selected none.
|
|
*/
|
|
readonly skinTag: string;
|
|
/** The source's poster URL, safe to interpolate into an attribute, or empty when it has none. */
|
|
readonly poster: string;
|
|
/** A tiny blurred rendition of the poster for a blur-up placeholder, attribute-safe, or empty when there is none. */
|
|
readonly placeholder: string;
|
|
/** The selected source's plain URL, or empty when it has none. */
|
|
readonly url: string;
|
|
/** ` src="…"` for the media component, or empty when the source has to be assigned as an object after render. */
|
|
readonly src: string;
|
|
/** The object to assign to the media component's `source` once rendered, when `src` is empty. */
|
|
readonly source: HtmlSandboxSource | undefined;
|
|
/** The attributes the settings menu controls: autoplay, muted, loop, and preload. */
|
|
readonly attrs: string;
|
|
/** Chapter tracks for the source, or empty. */
|
|
readonly chapters: string;
|
|
/** The storyboard track for the source, or empty. */
|
|
readonly storyboard: string;
|
|
}
|
|
|
|
export interface HtmlSandboxOptions {
|
|
readonly player: HtmlSandboxPlayer;
|
|
/** Switch to the live player and skin while the selected source is live. Leave off for media that cannot play one. */
|
|
readonly live?: boolean;
|
|
/**
|
|
* Fold the query-string playback overrides into the initial source. That forces the object form, so the engine is
|
|
* built with them rather than reconfigured afterwards.
|
|
*/
|
|
readonly playbackOverrides?: boolean;
|
|
/** The whole player as a consumer would write it: the player element, the skin, and the media inside it. */
|
|
readonly render: (context: HtmlSandboxContext) => string;
|
|
/** Runs once the markup is in the document, for what an attribute cannot carry: assigning `context.source`. */
|
|
readonly attach?: (context: HtmlSandboxContext) => void;
|
|
}
|
|
|
|
/** Render the user-controlled media attributes (autoplay/muted/loop/preload) as HTML attributes. */
|
|
export function renderMediaAttrs(state: SandboxState): string {
|
|
return [
|
|
state.autoplay ? 'autoplay' : '',
|
|
state.muted ? 'muted' : '',
|
|
state.loop ? 'loop' : '',
|
|
`preload="${state.preload}"`,
|
|
]
|
|
.filter(Boolean)
|
|
.join(' ');
|
|
}
|
|
|
|
export function createLatestLoader() {
|
|
let loadVersion = 0;
|
|
|
|
return async <Result>(load: () => Promise<Result>): Promise<Result | undefined> => {
|
|
const version = ++loadVersion;
|
|
|
|
try {
|
|
const result = await load();
|
|
|
|
return version === loadVersion ? result : undefined;
|
|
} catch (error) {
|
|
// Swallow load errors to avoid unhandled promise rejections in callers
|
|
// that do not await the returned promise. Callers can treat `undefined`
|
|
// as a signal that no valid result is available.
|
|
console.error('Failed to load latest result', error);
|
|
return undefined;
|
|
}
|
|
};
|
|
}
|
|
|
|
function loadSkinTag(player: HtmlSandboxPlayer, state: SandboxState, live: boolean): Promise<string> {
|
|
// The background skin is one element with no skin or styling variants, imported by the template.
|
|
if (player === 'background') return Promise.resolve('background-video-skin');
|
|
|
|
if (state.skinless) return Promise.resolve(defineNoSkin());
|
|
|
|
return loadHtmlSkinTag({ player, live, skin: state.skin, styling: state.styling, source: state.skins });
|
|
}
|
|
|
|
function describeSource(state: SandboxState, playbackOverrides: boolean) {
|
|
const { source, url = '' } = SOURCES[state.source];
|
|
const overrides = playbackOverrides ? getInitialPlaybackOverrides() : {};
|
|
const initial = source ?? (Object.keys(overrides).length > 0 ? { src: url } : undefined);
|
|
|
|
return {
|
|
url,
|
|
src: initial ? '' : ` src="${escapeHtml(url)}"`,
|
|
source: initial ? { ...initial, ...overrides } : undefined,
|
|
};
|
|
}
|
|
|
|
function playerTagFor(player: HtmlSandboxPlayer, live: boolean): string {
|
|
if (player === 'background') return 'background-video-player';
|
|
|
|
return live ? `live-${player}-player` : `${player}-player`;
|
|
}
|
|
|
|
function createContext(
|
|
options: HtmlSandboxOptions,
|
|
state: SandboxState,
|
|
live: boolean,
|
|
skinTag: string
|
|
): HtmlSandboxContext {
|
|
const { url, src, source } = describeSource(state, options.playbackOverrides === true);
|
|
|
|
return {
|
|
state,
|
|
live,
|
|
playerTag: playerTagFor(options.player, live),
|
|
skinTag,
|
|
url,
|
|
src,
|
|
source,
|
|
attrs: renderMediaAttrs(state),
|
|
chapters: renderChapters(getChapters(state.source)),
|
|
storyboard: renderStoryboard(getStoryboardSrc(state.source)),
|
|
poster: escapeHtml(getPosterSrc(state.source) ?? ''),
|
|
placeholder: escapeHtml(getPlaceholderSrc(state.source) ?? ''),
|
|
};
|
|
}
|
|
|
|
function getRoot(): HTMLElement {
|
|
const root = document.getElementById('root');
|
|
if (!root) throw new Error('The sandbox page has no #root element.');
|
|
|
|
return root;
|
|
}
|
|
|
|
/**
|
|
* Mount a preview page: read the shell's selections, load the skin they name, render the template's player markup with
|
|
* the tags and sources they resolve to, and render again as the shell streams changes. A locale change applies in place
|
|
* through `<media-i18n>` once the player is up; a direction change renders again, since the provider owns the pinned
|
|
* `dir`.
|
|
*/
|
|
export function createHtmlSandbox(options: HtmlSandboxOptions): void {
|
|
const state = readSandboxState('html');
|
|
const loadLatest = createLatestLoader();
|
|
const root = getRoot();
|
|
|
|
installSandboxMirror();
|
|
|
|
async function render(): Promise<void> {
|
|
await prepareSandboxHtmlLocale();
|
|
|
|
const live = options.live === true && isLiveSource(state.source);
|
|
const skinTag = await loadLatest(() => loadSkinTag(options.player, state, live));
|
|
if (!skinTag) return;
|
|
|
|
const context = createContext(options, state, live, skinTag);
|
|
|
|
const template = document.createElement('template');
|
|
|
|
template.innerHTML = wrapSandboxHtmlI18n(options.render(context));
|
|
|
|
// Subtitle tracks are the page's to add, so a template never has to spell them out. They go in while the markup is
|
|
// still inert: a media component reads its tracks when it upgrades, not when children arrive later.
|
|
const media = options.player === 'video' ? findMediaTag(template.content) : undefined;
|
|
|
|
if (media) applyCaptionTracks(media, state.captions);
|
|
|
|
root.replaceChildren(template.content);
|
|
options.attach?.(context);
|
|
}
|
|
|
|
void render();
|
|
|
|
onSandboxStateChange((change) => {
|
|
Object.assign(state, change);
|
|
void render();
|
|
});
|
|
|
|
// The shell repeats the direction after load, so only an actual change is worth a render.
|
|
let direction = getDirection();
|
|
|
|
onDirectionChange((next) => {
|
|
if (next === direction) return;
|
|
|
|
direction = next;
|
|
void render();
|
|
});
|
|
|
|
bindSandboxHtmlLocaleChange(render);
|
|
}
|