genus-player

Framework-agnostic media player with HTML5 video, audio, YouTube, and a custom element API.

Install

npm install genus-player

Import the packaged stylesheet when your app does not already bundle package CSS automatically.

import "genus-player/styles.css";

TypeScript Usage

import { createGenusPlayer } from "genus-player";

const root = document.getElementById("player-root");

if (root) {
  const player = createGenusPlayer(root, {
    source: {
      src: "https://www.youtube.com/watch?v=wDchsz8nmbo",
      type: "youtube",
      title: "Welcome video",
      subtitles: [
        {
          label: "English",
          srclang: "en",
          src: "https://example.com/subtitles.vtt",
          default: true,
        },
      ],
    },
    autoplay: false,
    bookmarks: [{ title: "Intro", second: 5 }],
    playbackRates: [0.75, 1, 1.25, 1.5],
  });

  player.addEventListener("genus-ready", (event) => {
    console.log("ready", event.detail.mediaType, event.detail.duration);
  });
}

Custom Element

Register the element yourself when you want to use declarative markup without first calling createGenusPlayer().

import { defineGenusPlayerElement } from "genus-player";

defineGenusPlayerElement();

<genus-player
  src="https://www.youtube.com/watch?v=wDchsz8nmbo"
  type="youtube"
  title="YouTube Example"
  autoplay="false"
  muted="false"
  loop="false"
></genus-player>

API

createGenusPlayer(container, config) appends and returns a GenusPlayerElement.

Config fields:

• source: { src, type?, mimeType?, poster?, title?, subtitles? }
• autoplay?, loop?, muted?
• showEndPopup?, showPlayButton?, pauseWhenHidden?
• aspectRatio?, startTime?, endTime?, introSource?
• bookmarks?: timed bookmark markers and pause points
• interactions?: CTA and checkpoint overlays
• playbackRates?: supported speed buttons

Element methods:

• configure(config)
• perform(action)

Control actions include:

• play, pause, togglePlayback, restart
• seek, seekPercent, rewind, forward
• mute, unmute, toggleMute, setVolume
• setPlaybackRate, toggleCaptions
• enterFullscreen, exitFullscreen, toggleFullscreen
• close

Events

The player emits bubbling custom events:

• genus-ready
• genus-play
• genus-pause
• genus-ended
• genus-timeupdate
• genus-seek
• genus-bookmark
• genus-interaction
• genus-fullscreenchange
• genus-action
• genus-error
• genus-close

Package Exports

• genus-player: main TypeScript and custom-element API
• genus-player/styles.css: packaged stylesheet export

Demo

npm run build
npm run demo:serve

Open http://127.0.0.1:4175/examples/.

Validate

npm run typecheck
npm run test
npm run build
NPM_CONFIG_CACHE=/tmp/genus-player-npm-cache npm pack --dry-run

Publish

This repo is configured for the public npm package genus-player.

npm publish

Notes

• The runtime does not depend on Ionic or plyr.
• HTML5 captions are package-managed by the package UI.
• YouTube playback uses the native IFrame API with a package-owned control layer.