v10/packages/html/html-media-elements/README.md

@vjs-10/html-media-elements

Web Component media elements and utilities

Status: Early Development

⚠️ PROTOTYPE - SUBJECT TO CHANGE

This package is in early prototype phase. Expect significant changes including:

• Package restructuring and naming
• Breaking API changes
• Major architectural updates
• Incomplete or experimental features

Not recommended for production use.

Overview

@vjs-10/html-media-elements provides Web Component implementations of media elements, offering enhanced functionality beyond native <video> and <audio> elements. These components integrate with the Video.js state management system and support advanced streaming protocols.

Key Features

• Web Components - Standard custom elements for media
• Enhanced Media Elements - Extended functionality beyond native elements
• State Integration - Built-in media store connectivity via Context Protocol
• Streaming Support - HLS, DASH support via playback engines
• Framework Agnostic - Works with vanilla JS or any framework

Installation

npm install @vjs-10/html-media-elements

Quick Start

Basic Video Element

import '@vjs-10/html-media-elements';

// Use in HTML
const html = `
  <vjs-video src="video.mp4" controls>
    Your browser doesn't support video.
  </vjs-video>
`;

With JavaScript

import { VideoElement } from '@vjs-10/html-media-elements';

// Create video element
const video = new VideoElement();
video.src = 'https://example.com/video.mp4';
video.controls = true;
document.body.appendChild(video);

// Listen to events
video.addEventListener('play', () => {
  console.log('Video started playing');
});

HLS Streaming

<!-- HLS source automatically uses playback engine -->
<vjs-video src="https://example.com/stream.m3u8" controls> </vjs-video>

Components

VideoElement (<vjs-video>)

Enhanced video element with streaming support:

<vjs-video src="video.mp4" poster="poster.jpg" controls autoplay muted loop preload="metadata"> </vjs-video>

Attributes:

• All standard <video> attributes
• src - Media source (supports HLS .m3u8 files)
• poster - Poster image URL
• controls - Show native controls
• autoplay - Auto-play on load
• muted - Start muted
• loop - Loop playback
• preload - Preload strategy

AudioElement (<vjs-audio>)

Enhanced audio element:

<vjs-audio src="audio.mp3" controls preload="auto"> </vjs-audio>

State Integration

Components automatically integrate with @vjs-10/media-store:

import { VideoElement } from '@vjs-10/html-media-elements';
import { createMediaStore } from '@vjs-10/media-store';

// Create media store
const store = createMediaStore();

// Create video element
const video = new VideoElement();
video.store = store; // Connect to store

// Store automatically updates with media state
store.currentTime.subscribe((time) => {
  console.log('Current time:', time);
});

store.paused.subscribe((paused) => {
  console.log('Is paused:', paused);
});

Context Protocol Integration

Uses @open-wc/context-protocol for state sharing:

<!-- Provider shares store with descendants -->
<vjs-media-provider>
  <vjs-video src="video.mp4"></vjs-video>
  <!-- Other components can access the same store -->
  <vjs-play-button></vjs-play-button>
  <vjs-time-slider></vjs-time-slider>
</vjs-media-provider>

Advanced Usage

Playback Engine Configuration

import { VideoElement } from '@vjs-10/html-media-elements';
import { HlsJSPlaybackEngine } from '@vjs-10/playback-engine';

const video = new VideoElement();

// Configure HLS engine
video.engineConfig = {
  debug: false,
  enableWorker: true,
  lowLatencyMode: true,
};

video.src = 'stream.m3u8';

Source Switching

const video = new VideoElement();
video.src = 'video1.mp4';

// Switch to different source
setTimeout(() => {
  video.src = 'video2.mp4';
  video.load(); // Reload with new source
}, 5000);

// Switch to HLS stream
setTimeout(() => {
  video.src = 'stream.m3u8'; // Automatically uses HLS engine
}, 10000);

Event Handling

const video = new VideoElement();

// Standard media events
video.addEventListener('loadedmetadata', () => {
  console.log('Duration:', video.duration);
});

video.addEventListener('timeupdate', () => {
  console.log('Current time:', video.currentTime);
});

video.addEventListener('ended', () => {
  console.log('Playback ended');
});

// Error handling
video.addEventListener('error', (e) => {
  console.error('Media error:', e);
});

Programmatic Control

const video = new VideoElement();
video.src = 'video.mp4';

// Playback control
await video.play();
video.pause();

// Seeking
video.currentTime = 30; // Seek to 30 seconds

// Volume
video.volume = 0.5; // 50%
video.muted = true;

// Playback rate
video.playbackRate = 1.5; // 1.5x speed

API Reference

Properties

interface VideoElement extends HTMLElement {
  // Source
  src: string;
  currentSrc: string;

  // Playback state
  paused: boolean;
  ended: boolean;
  seeking: boolean;

  // Time
  currentTime: number;
  duration: number;

  // Volume
  volume: number;
  muted: boolean;

  // Playback
  playbackRate: number;
  autoplay: boolean;
  loop: boolean;
  controls: boolean;

  // Loading
  preload: 'none' | 'metadata' | 'auto';
  readyState: number;

  // Media store integration
  store?: MediaStore;
  engineConfig?: EngineConfig;
}

Methods

interface VideoElementMethods {
  // Playback
  play(): Promise<void>
  pause(): void
  load(): void

  // Seeking
  fastSeek(time: number): void

  // Fullscreen
  requestFullscreen(): Promise<void>
  exitFullscreen(): Promise<void>
}

Browser Compatibility

Web Components support:

• Chrome 54+
• Firefox 63+
• Safari 10.1+
• Edge 79+

HLS streaming support:

• All modern browsers via HLS.js

Package Dependencies

• Dependencies:
  • @vjs-10/media-store - State management
  • @open-wc/context-protocol - State sharing
• Used by: @vjs-10/html - Complete HTML player

Development

# Build the package
pnpm build

# Watch mode for development
pnpm dev

# Run tests
pnpm test

# Clean build artifacts
pnpm clean

Related Packages

• @vjs-10/media-store - State management
• @vjs-10/html-media-store - HTML store integration
• @vjs-10/html - Complete HTML player
• @vjs-10/react-media-elements - React alternative

License

Apache-2.0