@nofinite/media

v1.0.0

Published

14 days ago

Universal, framework-agnostic audio and video streaming media player suite powered by Vidstack and styled with NUICSS design tokens.

0High
0Medium
0Low

suyashdas

nofinite media video-player audio-player hls dash vidstack streaming react-video vanilla-media

Universal, enterprise-grade audio and video streaming media player suite powered by Vidstack and styled with NUICSS design tokens.

Highlights

Framework-Agnostic Core: Native W3C Custom Element engine (createMediaPlayer) with zero React dependencies or bundle penalty.
Next.js App Router & RSC Ready: React entrypoint preserves byte-0 'use client'; directives across both ESM and CJS bundles.
Adaptive Streaming Built-In: Native support for HLS (.m3u8), DASH (.mpd), MP4, WebM, MP3, WAV, AAC, and YouTube with lazy-loaded streaming decoders.
Glassmorphic OKLCH Theming: Fully harmonized with NUICSS design tokens (--color-primary, --bg-surface, --bg-subtle, --fg-default) supporting seamless light and dark mode cascading.
CDN CORS Resilience: Default crossOrigin="anonymous" handling prevents browser CORS rejections on external WebVTT subtitles, storyboard thumbnails, and audio streams.
Zero Memory Leaks: Automatic listener registry detachment and element teardown on player.destroy(), engineered for single-page applications.

Installation

# pnpm
pnpm add @nofinite/media @nofinite/nuicss

# npm
npm install @nofinite/media @nofinite/nuicss

# yarn
yarn add @nofinite/media @nofinite/nuicss

Styles Setup

Nofinite Media player layout chrome, scrubber timelines, responsive aspect ratios, and glassmorphic OKLCH design tokens are styled natively via NUICSS. Import the stylesheet once at your application root (e.g., layout.tsx, main.tsx, or _app.tsx):

import '@nofinite/nuicss/styles.css';

Note: For modular or bundle-isolated setups, NUICSS also exports a dedicated subpath stylesheet: @nofinite/nuicss/media.css.

Usage

1. React Video Player

import '@nofinite/nuicss/styles.css';
import { VideoPlayer } from '@nofinite/media/react';

export function MoviePlayer() {
  return (
    <VideoPlayer
      title="Sprite Fight Keynote"
      src="https://files.vidstack.io/sprite-fight/hls/stream.m3u8"
      poster="https://files.vidstack.io/sprite-fight/poster.webp"
      thumbnails="https://files.vidstack.io/sprite-fight/thumbnails.vtt"
      playbackRates={[0.5, 0.75, 1, 1.25, 1.5, 2]}
      seekStep={10}
      crossOrigin="anonymous"
      tracks={[
        {
          src: 'https://files.vidstack.io/sprite-fight/subs/english.vtt',
          label: 'English',
          language: 'en-US',
          kind: 'subtitles',
          default: true,
        },
        {
          src: 'https://files.vidstack.io/sprite-fight/subs/spanish.vtt',
          label: 'Spanish',
          language: 'es-ES',
          kind: 'subtitles',
        },
      ]}
      onPlay={() => console.log('Playback started')}
      onTimeUpdate={({ currentTime, duration }) => {
        console.log(`Progress: ${currentTime}/${duration}`);
      }}
    />
  );
}

2. React Audio Player

import { AudioPlayer } from '@nofinite/media/react';

export function PodcastPlayer() {
  return (
    <AudioPlayer
      title="Episode 42: Modern Web Architecture"
      artist="Nofinite Studio"
      artwork="https://images.unsplash.com/photo-1511671782779-c97d3d27a1d4?w=200"
      src="https://files.vidstack.io/audio/audio.mp3"
      playbackRates={[0.75, 1, 1.25, 1.5]}
      seekStep={15}
      theme="auto"
    />
  );
}

3. Vanilla JavaScript / Framework-Agnostic Core

import { createMediaPlayer } from '@nofinite/media';

const player = createMediaPlayer({
  src: 'https://files.vidstack.io/sprite-fight/720p.mp4',
  poster: 'https://files.vidstack.io/sprite-fight/poster.webp',
  title: 'Sprite Fight',
  autoplay: false,
  muted: false,
  controls: true,
  aspectRatio: '16/9',
  playbackRates: [0.5, 1, 1.5, 2],
  tracks: [
    {
      src: 'https://files.vidstack.io/sprite-fight/subs/english.vtt',
      label: 'English',
      language: 'en-US',
      kind: 'subtitles',
      default: true,
    },
  ],
});

// Append to DOM
document.getElementById('app')?.appendChild(player.element);

// Reactive event listeners
const unsubscribe = player.on('time-update', (detail) => {
  console.log('Current time:', detail.currentTime);
});

// Imperative controls
player.seek(45);
player.setVolume(0.8);
player.setPlaybackRate(1.25);

// Cleanup on unmount (SPA safe, detaches all listeners)
// player.destroy();

4. Zero-Build CDN (ESM)

For rapid prototyping or server-rendered HTML/HTMX environments without a build step:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <!-- NUICSS Design Tokens & Media Player Styles -->
    <link
      rel="stylesheet"
      href="https://cdn.jsdelivr.net/npm/@nofinite/nuicss/dist/styles.css"
    />
  </head>
  <body class="bg-surface p-6">
    <div id="player-container"></div>

    <script type="module">
      import { createMediaPlayer } from 'https://esm.sh/@nofinite/media';

      const player = createMediaPlayer({
        src: 'https://files.vidstack.io/sprite-fight/720p.mp4',
        poster: 'https://files.vidstack.io/sprite-fight/poster.webp',
        title: 'Sprite Fight',
      });

      document.getElementById('player-container').appendChild(player.element);
    </script>
  </body>
</html>

API Reference

`VideoPlayerProps`

`AudioPlayerProps`

`MediaPlayerInstance` (Core Engine Methods)

The imperative instance returned by createMediaPlayer (and forwarded by ref on React components):

Re-exported Vidstack Primitives

For developers building bespoke media interfaces, @nofinite/media/react re-exports the foundational Vidstack state hooks and compound components:

import {
  MediaPlayer,
  MediaProvider,
  Track,
  useMediaState,
  useMediaRemote,
  useActiveTextTrack,
  useVideoQualityOptions,
  useCaptionOptions,
  usePlaybackRateOptions,
  DefaultVideoLayout,
  DefaultAudioLayout,
} from '@nofinite/media/react';

Documentation

For full setup guides, component examples, and API references, read documentation.

License

This project is licensed under the Apache License, Version 2.0.

Feel free to use, modify, and share this project in your applications, products, and services. Attribution is welcome and appreciated, but never required.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme