Skip to main content

Player

This class provides a GUI interface for playing ractives, 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 "ractive-player";
const controls = (<>
{Player.defaultControlsLeft}
<MyCustomControl/>
<div className="rp-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 "ractive-player";
const controls = (<>
<Controls.PlayPause/>
<MyVolumeControl/>
<div className="rp-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.

script#

The Script to use.

script: Script;

thumbs#

Provide thumbnail previews for the scrubber bar. You can generate thumbnail sheets with rp-master thumbs.

  • cols how many columns per sheet

  • rows how many rows per sheet

  • width the width of each thumbnail

  • height the height of each thumbnail

  • frequency how many seconds between thumbnails

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

  • highlights points of interest in the video, these will be highlighted on the scrubber bar

thumbs?: {
cols: number;
rows: number;
width: number;
height: number;
frequency: number;
path: string;
highlights?: {
time: number;
title: string;
}[];
}

Example#

const highlights = [
{title: "Horses", time: script.parseStart("horses/")},
{title: "Cats", time: script.parseStart("cats/")}
];
const thumbs = {
cols: 5,
rows: 5,
height: 100,
width: 160,
frequency: 4,
path: `./thumbs/%s.png`,
highlights
};

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 that you need to wrap these in <div className="rp-controls-right" for these to actually be right-aligned.

Static methods#

allowScroll()#

Prevents intercepting of scroll on mobile. See Scroll events in the Authoring guide.

static allowScroll(e: React.TouchEvent | TouchEvent): void;

preventCanvasClick()#

Prevents a click from pausing/playing the video. See Canvas clicks in the Authoring guide.

static preventCanvasClick(e: React.MouseEvent | MouseEvent): void;

Properties#

canPlay#

canPlay: Promise<void[]>;

canPlayThrough#

canPlayThrough: Promise<void[]>;

canvas#

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

canvas: HTMLDivElement;

hub#

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

NameDescription
canplayFired when the ractive is ready to start playing, but may not be able to play to its end without having to stop for further buffering of content.
canplaythroughFired when the ractive is ready to start playing, and will be able to play up to its end without having to stop for further buffering of content.
canvasClickFired 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()#

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

ready()#

Call this method when the ractive is ready to begin playing.

ready(): void;

resumeKeyCapture()#

Resumes keyboard controls. See Forms in the Authoring guide.

resumeKeyCapture(): void;

suspendKeyCapture()#

Suspends keyboard controls so that components can receive keyboard input. See Forms in the Authoring guide.

suspendKeyCapture(): void;