@lumra/core

Headless media player engine for Lumra. Wraps the native <video> element with HLS adaptive streaming, a plugin system, quality switching, and a typed event emitter.

Install

npm install @lumra/core

Basic usage

import { createPlayer } from '@lumra/core'

const player = createPlayer({
  target: '#my-video',          // CSS selector or HTMLVideoElement
  src: 'https://example.com/stream.m3u8',
  autoplay: false,
  muted: false,
})

player.on('play',        () => console.log('playing'))
player.on('pause',       () => console.log('paused'))
player.on('timeupdate',  ({ currentTime, duration }) => console.log(currentTime, duration))
player.on('ended',       () => console.log('ended'))
player.on('error',       ({ code, message }) => console.error(code, message))

// Playback control
await player.play()
player.pause()
player.seek(30)           // seek to 30 seconds
player.setVolume(0.8)     // 0–1
player.mute()
player.unmute()

// Source switching
player.setSrc('https://example.com/other.m3u8')

// Cleanup
player.destroy()

HLS & adaptive streaming

HLS streams (.m3u8) are detected automatically and loaded via hls.js. Safari uses native HLS.

const player = createPlayer({
  target: '#video',
  src: 'https://example.com/stream.m3u8',
  hlsConfig: { maxBufferLength: 30 },   // pass any hls.js config here
})

Quality switching

// Get available quality levels (populated after the HLS manifest loads)
const levels = player.getQualityLevels()
// [{ index: -1, label: 'Auto' }, { index: 0, label: '1080p', bitrate: 5000000 }, ...]

// Set quality — index -1 = ABR auto
player.setQuality(0)    // lock to first level
player.setQuality(-1)   // back to auto

player.on('qualitychange', ({ level, auto }) => console.log(level, auto))
player.on('levelchange',   ({ level }) => console.log(level))

// Live stream detection
console.log(player.isLive)    // true for live HLS
console.log(player.isHls)     // true when hls.js is active

Plugin system

import { createPlayer } from '@lumra/core'
import type { Plugin, PlayerInstance } from '@lumra/core'

const myPlugin: Plugin = {
  name: 'my-plugin',
  init(player: PlayerInstance) {
    player.on('play', () => console.log('plugin saw play'))
  },
  destroy() {
    // cleanup — called when player.destroy() is called
  },
}

player.use(myPlugin)

Events reference

| Event | Payload | |---|---| | play | — | | pause | — | | ended | — | | timeupdate | { currentTime, duration } | | volumechange | { volume, muted } | | seeking | { time } | | seeked | { time } | | buffering | — | | ready | — | | error | { code, message } | | qualitychange | { level, auto } | | levelchange | { level } | | destroy | — |

© 2026 Reel Foundry AU. All rights reserved.
MIT License — see LICENSE