Player — Vanilla JS

Installation

npm install @livepeer-frameworks/player-core

import "@livepeer-frameworks/player-core/player.css";

createPlayer()

The primary API for vanilla and headless usage. Returns a property-based facade with queries, mutations, and subscriptions.

import { createPlayer } from "@livepeer-frameworks/player-core";
import "@livepeer-frameworks/player-core/player.css";

const player = createPlayer({
  target: "#player",
  contentId: "my-stream",
  contentType: "live",
  theme: "dracula",
  autoplay: true,
  muted: true,
});

// Read state (queries)
player.state; // "playing"
player.volume; // 0.75
player.currentTime; // 12500 (ms)
player.live; // true
player.paused; // false

// Change state (mutations)
player.volume = 0.5;
player.play();
player.pause();
player.seek(30000);
player.theme = "tokyo-night";

// React to changes (subscriptions)
const unsub = player.subscribe.on("volume", (v) => console.log("Volume:", v));

// Cleanup
player.destroy();

By default, resolution runs through the official FrameWorks Gateway from the viewer’s browser or playback device. Set gatewayUrl only for a fully self-hosted control plane or local Gateway preview. If you are generating URLs on a backend or building a player that will not call Gateway from the viewer, use the dashboard playback DNS URL directly.

Queries (Read State)

Property	Type	Description
state	PlayerState	Current lifecycle state
streamState	StreamState | null	Upstream stream status
endpoints	ContentEndpoints | null	Resolved playback endpoints
metadata	object	Stream metadata from gateway
videoElement	HTMLVideoElement | null	Underlying video element
ready	boolean	Player initialized and ready
currentTime	number	Current position (milliseconds)
duration	number	Total duration in milliseconds (Infinity for live)
volume	number	Volume level (0-1)
muted	boolean	Whether muted
paused	boolean	Whether paused
playing	boolean	Whether actively playing
buffering	boolean	Whether buffering
started	boolean	Whether playback started at least once
playbackRate	number	Current speed
loop	boolean	Looping enabled
live	boolean	Whether live stream
nearLive	boolean	Whether near the live edge
fullscreen	boolean	Whether in fullscreen
pip	boolean	Whether in picture-in-picture
error	string | null	Current error message
quality	PlaybackQuality | null	Active quality level
abrMode	'auto' | 'resize' | 'bitrate' | 'manual'	ABR mode
theme	string	Current theme
size	{ width, height }	Container dimensions
capabilities	Capabilities	Runtime feature detection

Mutations (Change State)

Mutation	Signature	Description
volume	set volume(n)	Set volume (0-1)
muted	set muted(b)	Set mute state
playbackRate	set playbackRate(n)	Set playback speed
loop	set loop(b)	Enable/disable looping
abrMode	set abrMode(m)	Switch ABR mode
theme	set theme(t)	Switch theme preset
play()	() => Promise<void>	Start playback
pause()	() => void	Pause playback
seek(t)	(milliseconds) => void	Seek to time
seekBy(d)	(deltaMs) => void	Seek relative
jumpToLive()	() => void	Jump to live edge
skipForward(ms?)	(milliseconds?) => void	Skip forward (default 10000ms)
skipBack(ms?)	(milliseconds?) => void	Skip backward (default 10000ms)
togglePlay()	() => void	Toggle play/pause
toggleMute()	() => void	Toggle mute
toggleFullscreen()	() => Promise<void>	Toggle fullscreen
togglePiP()	() => Promise<void>	Toggle picture-in-picture
getQualities()	() => Quality[]	List available qualities
selectQuality(id)	(id) => void	Lock to specific quality
retry()	() => Promise<void>	Retry current connection
retryWithFallback()	() => Promise<boolean>	Retry with next endpoint
reload()	() => Promise<void>	Full reload
clearError()	() => void	Dismiss error
getStats()	() => Promise<unknown>	Playback statistics snapshot
setThemeOverrides(o)	(overrides) => void	Apply theme overrides
clearTheme()	() => void	Reset to default theme
destroy()	() => void	Tear down the player

Subscriptions — Events

const unsub = player.on("stateChange", ({ state }) => {
  console.log("State:", state);
});
unsub();

Event	Payload	Description
stateChange	{ state, context? }	State transition
timeUpdate	{ currentTime, duration }	Position changed
volumeChange	{ volume, muted }	Volume/mute changed
qualityChanged	{ fromLevel?, toLevel }	Quality level changed
fullscreenChange	{ isFullscreen }	Fullscreen state changed
pipChange	{ isPiP }	PiP state changed
error	{ error, code? }	Playback error
streamStateChange	{ state }	Upstream status changed
metadataUpdate	{ currentTime, duration, bufferedAhead, ... }	Metadata updated

Subscriptions — Reactive State

Per-property subscriptions with immediate invocation via player.subscribe:

const unsub = player.subscribe.on("volume", (v) => {
  volumeSlider.value = v;
});

const unsub2 = player.subscribe.on("playing", (isPlaying) => {
  playBtn.textContent = isPlaying ? "Pause" : "Play";
});

// Synchronous read
const vol = player.subscribe.get("volume");

Available reactive properties: paused, playing, currentTime, duration, volume, muted, playbackRate, loop, buffering, fullscreen, pip, tracks, streamState, error, loading, ended, seeking.

FrameWorksPlayer Class

Constructor-based alternative for class-oriented code:

import { FrameWorksPlayer } from "@livepeer-frameworks/player-core/vanilla";
import "@livepeer-frameworks/player-core/player.css";

const player = new FrameWorksPlayer("#player", {
  contentId: "<YOUR_PLAYBACK_ID>",
  contentType: "live",
  autoplay: true,
  muted: true,
  onStateChange: (state) => console.log("State:", state),
  onReady: (videoElement) => console.log("Ready!"),
});

player.play();
player.pause();
player.seek(30000);
player.setVolume(0.5);
player.jumpToLive();
player.destroy();

Vue Example

<template>
  <div ref="container" style="width: 100%; aspect-ratio: 16/9;" />
</template>

<script setup lang="ts">
import { ref, onMounted, onUnmounted } from "vue";
import type { FrameWorksPlayer as FWP } from "@livepeer-frameworks/player-core/vanilla";

const container = ref<HTMLDivElement>();
let player: FWP | null = null;

onMounted(async () => {
  const { FrameWorksPlayer } = await import("@livepeer-frameworks/player-core/vanilla");
  await import("@livepeer-frameworks/player-core/player.css");
  if (container.value) {
    player = new FrameWorksPlayer(container.value, {
      contentId: "<YOUR_PLAYBACK_ID>",
      contentType: "live",
      autoplay: true,
      muted: true,
    });
  }
});

onUnmounted(() => player?.destroy());
</script>

Capabilities

The capabilities object reports runtime feature support:

if (player.capabilities.pip) player.togglePiP();
if (player.capabilities.qualitySelection) player.selectQuality("720p");

Property	Type	Description
fullscreen	boolean	Fullscreen API available
pip	boolean	Picture-in-picture available
seeking	boolean	Arbitrary seeking supported
playbackRate	boolean	Speed control supported
audio	boolean	Audio track selection
qualitySelection	boolean	Manual quality selection
textTracks	boolean	Subtitle/caption support

Options

Option	Type	Default	Description
target	string | HTMLElement	—	Container
contentId	string	—	Playback ID
contentType	string	"live"	Content type
gatewayUrl	string	Official	Gateway GraphQL endpoint override
mistUrl	string	—	Direct MistServer URL
endpoints	ContentEndpoints	—	Pre-resolved endpoints
autoplay	boolean	true	Auto-start
muted	boolean	false	Start muted
controls	boolean	true	Show built-in controls
poster	string	—	Poster image before playback
animatePreroll	boolean	false	Cycle thumbnail sprite tiles as a preroll animation before playback
theme	string	"default"	Theme preset
themeOverrides	object	—	Per-token theme overrides
locale	string	"en"	UI language
playbackMode	string	"auto"	Protocol preference
skin	string | SkinDefinition | false	"default"	Skin for blueprint rendering (see Advanced)
debug	boolean	false	Debug logging