yk-player

A modern m3u8 (HLS) player built with Web Components — usable in every project, whatever the framework (or none at all).

Built on Lit and hls.js.

Features

• 🎛️ Full controller out of the box — play/pause, seek, volume, speed, fullscreen, auto-hiding controls
• 💬 Subtitles (WebVTT) — switch between subtitle tracks declared in the HLS manifest
• 🎚️ Bitrate switching — pick a quality level manually or let hls.js adapt automatically
• 📺 Native HLS fallback on Safari, where hls.js isn't needed
• 🌏 Built-in i18n (English, 日本語, 中文)
• 📦 Ships as a standard custom element — works with any framework or none

Streaming features like subtitles and adaptive bitrate come straight from hls.js — yk-player provides a clean controller UI on top of them.

Installation

npm install @biliblitz/yk-player hls.js lit

hls.js and lit are peer dependencies, so install them alongside the package.

Quick Start

Import the package once to register the <yk-player> custom element, then use it like a regular HTML tag:

import "@biliblitz/yk-player";

<yk-player src="/videos/index.m3u8" autoplay></yk-player>

The element fills its container, so give it a size:

yk-player {
  width: 800px;
  aspect-ratio: 16 / 9;
}

Attributes

| Attribute | Type | Default | Description | | ---------- | --------- | ------- | -------------------------------------------- | | src | string | "" | URL of the HLS manifest (.m3u8) | | autoplay | boolean | false | Start playback automatically | | lang | string | "en" | UI language: en, ja, or zh |

All attributes are reactive — updating src switches the source in place (playback state is preserved), and updating lang re-renders the UI in the new language.

Keyboard shortcuts

Click the player once to focus it, then:

| Key | Action | | --- | ------ | | Space / k | Play / pause | | f (or double-click) | Toggle fullscreen | | m | Toggle mute | | c | Toggle subtitles | | ← / → | Seek −5s / +5s | | j / l | Seek −10s / +10s | | ↑ / ↓ | Volume up / down | | 0–9 | Jump to 0%–90% | | Esc | Close the settings menu |

Acts like a <video> element

<yk-player> mirrors the HTMLMediaElement API, so you can treat it as a drop-in <video>:

• Methods: play() (returns a promise, like native) and pause()
• Properties: currentTime, duration, paused, ended, volume, muted, playbackRate
• Events: all standard playback events are re-dispatched on the element — play, pause, playing, waiting, seeking, seeked, timeupdate, durationchange, volumechange, ratechange, ended, error, loadedmetadata, canplay, and the rest. Fatal hls.js failures fire error too, matching what native playback would do.

import type { YkPlayer } from "@biliblitz/yk-player";

const player = document.querySelector<YkPlayer>("yk-player")!;
player.src = "/another/index.m3u8";
player.lang = "ja";

player.currentTime = 42;
player.volume = 0.5;
player.addEventListener("timeupdate", () => console.log(player.currentTime));
player.addEventListener("ended", () => console.log("done"));

Development

pnpm install
pnpm dev      # start the demo page (index.html) with Vite
pnpm build    # type-check and build the library to dist/
pnpm preview  # preview the production build

The demo page at the project root lets you switch between sample sources and UI languages. Place sample HLS streams under public/ (e.g. public/pv1.m3u8).