Player

This class provides a GUI interface for playing liquid videos, resembling a traditional web video player. It is the main entry point to the library.

Props

controls

Customize the player controls.

controls?: JSX.Element;

Example

You can extend the default controls like so:

import {Player} from "liqvid";

const controls = [(<>
  {Player.defaultControlsLeft}
  <MyCustomControl/>

  <div className="lv-controls-right">
    <AnotherCustomControl/>
    {Player.defaultControlsRight}
  </div>
</>);

Say you wanted to have your own volume control, have the time display on the right, and not have the Settings control. Then you would write

import {Controls, Player} from "liqvid";

const controls = (<>
  <Controls.PlayPause/>
  <MyVolumeControl/>

  <div className="lv-controls-right">
    <Controls.TimeDisplay/>
    <Controls.FullScreen/>
  </div>
</>);

info

At this time, it is not possible to provide your own scrubber bar. This will be corrected in a future release.

playback

The Playback to use. This prop isn't needed if you're using a Script.

playback?: Playback;

script

The Script to use.

script?: Script;

thumbs

Provide thumbnail previews for the scrubber bar. You can generate thumbnail sheets with liqvid thumbs.

• cols?: number = 5
  how many columns per sheet

• rows?: number = 5
  how many rows per sheet

• width?: number = 160
  the width of each thumbnail

• height?: number = 100
  the height of each thumbnail

• frequency?: number = 4
  how many seconds between thumbnails

• path: string
  pattern where the sheets are located. Must contain %s.

• highlights?: {time: number, title: string}[]
  points of interest in the video, these will be highlighted on the scrubber bar

Example

const highlights = [
  {title: "Horses", time: script.parseStart("horses/")},
  {title: "Cats", time: script.parseStart("cats/")}
];

const thumbs = {
  path: `./thumbs/%s.png`,
  highlights
};

<Player script={script} thumbs={thumbs}>

Static properties

Context

React Context containing a reference to the ambient player. If you are using Hooks, you can use usePlayer() instead.

static Context: React.Context<Player>;

defaultControlsLeft

The default controls appearing on the left: PlayPause, Volume, TimeDisplay.

defaultControlsRight

The default controls appearing on the right: Settings and FullScreen.

note

You need to wrap these in <div className="lv-controls-right"> for these to actually be right-aligned.

Properties

canPlay

Liqvid analogue of the canplay event. This can be used to wait for Audio or Video files to load. You can also use obstruct() to add custom loaders.

canPlay: Promise<void>;

canPlayThrough

Liqvid analogue of the canplaythrough event. This can be used to wait for Audio or Video files to load. You can also use obstruct() to add custom loaders.

canPlayThrough: Promise<void>;

canvas

The div where video content is attached (which is separate from the controls).

canvas: HTMLDivElement;

hub

An EventEmitter that your code can subscribe to. Emits the following events:

Name	Description
canplay	Fired when the video is ready to start playing, but may not be able to play to its end without having to stop for further buffering of content.
canplaythrough	Fired when the video is ready to start playing, and will be able to play up to its end without having to stop for further buffering of content.
canvasClick	Fired when a click happens anywhere on the canvas, which by default pauses/resumes the video. See Canvas clicks in the Authoring guide.

hub: StrictEventEmitter<EventEmitter, {
  "canplay": void;
  "canplaythrough": void;
  "canvasClick": void;
}>;

keymap

The Keymap instance attached to this player.

keymap: Keymap;

playback

The underlying Playback instance.

playback: Playback;

script

The underlying Script instance.

script: Script;

Methods

obstruct()

Add a Promise to the list of tasks needed for canPlay or canPlayThrough to resolve. Parameters:

• event: "canplay" | "canplaythrough"
  Which event type to obstruct

• task: Promise<void>
  Promise to append

obstruct(event: "canplay" | "canplaythrough", task: Promise<unknown>): void;

reparseTree()

Reparse a section of the document for during() and from(). Accepts the following parameters:

• node
  Element to reparse

reparseTree(node: HTMLElement | SVGElement): void;

resumeKeyCapture()

Resumes keyboard controls.

resumeKeyCapture(): void;

suspendKeyCapture()

Suspends keyboard controls so that components can receive keyboard input.

suspendKeyCapture(): void;