or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-xgplayer-hls-js

xgplayer plugin for HTTP Live Streaming (HLS) video playback via hls.js integration

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/xgplayer-hls.js@3.0.x

To install, run

npx @tessl/cli install tessl/npm-xgplayer-hls-js@3.0.0

index.mddocs/

xgplayer-hls.js

xgplayer-hls.js is a plugin that integrates hls.js into the xgplayer video player framework, enabling HTTP Live Streaming (HLS) video playback capabilities. It provides a seamless integration layer between the popular hls.js library and xgplayer's plugin architecture.

Package Information

  • Package Name: xgplayer-hls.js
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install xgplayer-hls.js xgplayer

Core Imports

import HlsJsPlugin from 'xgplayer-hls.js';

For CommonJS:

const HlsJsPlugin = require('xgplayer-hls.js');

For CDN/UMD:

// Available as window.HlsJsPlugin

Basic Usage

import Player from 'xgplayer';
import 'xgplayer/dist/xgplayer.min.css';
import HlsJsPlugin from 'xgplayer-hls.js';

const player = new Player({
  id: 'video-container',
  url: 'https://example.com/video.m3u8',
  plugins: [HlsJsPlugin],
  hlsJsPlugin: {
    hlsOpts: {
      // hls.js configuration options
      startPosition: 0,
      maxBufferLength: 30,
      maxMaxBufferLength: 600
    }
  }
});

Architecture

The plugin follows xgplayer's standard plugin architecture pattern:

  • Plugin Class: HlsJsPlugin extends BasePlugin from xgplayer
  • HLS Integration: Uses hls.js library for HLS stream processing
  • Event System: Bridges hls.js events to xgplayer's event system
  • Error Handling: Automatic recovery for network and media errors
  • Statistics: Real-time playback statistics and media information

Capabilities

Plugin Class

The main plugin class that integrates hls.js with xgplayer.

class HlsJsPlugin extends BasePlugin {
  constructor(args);
  static get pluginName(): string;
  static get defaultConfig(): HlsPluginConfig;
  static get isSupported(): boolean;
  afterCreate(): void;
  beforePlayerInit(): void;
  destroy(): void;
  register(url: string): void;
}

Static Properties

Plugin metadata and configuration.

/**
 * Plugin name identifier
 */
static get pluginName(): string; // Returns 'HlsJsPlugin'

/**
 * Default plugin configuration
 */
static get defaultConfig(): HlsPluginConfig;

/**
 * Browser HLS support check via hls.js
 */
static get isSupported(): boolean;

Constructor

Creates new plugin instance and initializes internal properties.

/**
 * Creates a new HlsJsPlugin instance
 * @param {object} args - Plugin configuration from xgplayer
 */
constructor(args);

Internal Properties:

  • this.browser - Browser version string from getBrowserVersion()
  • this.hls - hls.js instance (null until initialized)
  • this.hlsOpts - Processed hls.js configuration options

Lifecycle Methods

Plugin lifecycle management methods called by xgplayer.

/**
 * Called after plugin creation - sets up URL change handling and player properties
 * Sets up URL_CHANGE event listener to automatically re-register new HLS sources
 */
afterCreate(): void;

/**
 * Called before player initialization - registers initial HLS source
 */
beforePlayerInit(): void;

/**
 * Cleanup method - destroys hls.js instance and restores player state
 */
destroy(): void;

HLS Source Management

Methods for managing HLS sources and automatic URL change handling.

/**
 * Registers HLS source with the player
 * Creates new hls.js instance, attaches to media element, and loads the source
 * @param {string} url - HLS manifest URL (.m3u8)
 */
register(url: string): void;

Automatic URL Change Handling: The plugin automatically listens for URL_CHANGE events from xgplayer and calls register() with the new URL, enabling seamless source switching during playback.

Configuration Options

Plugin configuration through xgplayer's hlsJsPlugin option.

interface HlsPluginConfig {
  /** Configuration options passed directly to hls.js */
  hlsOpts?: HlsConfig;
}

interface HlsConfig {
  /** Start position in seconds */
  startPosition?: number;
  /** Maximum buffer length in seconds */
  maxBufferLength?: number;
  /** Maximum buffer size limit */
  maxMaxBufferLength?: number;
  /** Enable/disable debug logging */
  debug?: boolean;
  /** Fragment loading timeout */
  fragLoadingTimeOut?: number;
  /** Manifest loading timeout */
  manifestLoadingTimeOut?: number;
  /** Additional hls.js configuration options */
  [key: string]: any;
}

Events

Events emitted by the plugin through xgplayer's event system.

/**
 * HLS-specific error event with detailed error information
 * @event HLS_ERROR
 * @type {object}
 * @property {string} errorType - Error type from hls.js (NETWORK_ERROR, MEDIA_ERROR, etc.)
 * @property {string} errorDetails - Specific error details from hls.js
 * @property {boolean} errorFatal - Whether the error is fatal and requires recovery
 */

/**
 * Generic error event for fatal errors that cannot be recovered
 * @event error
 * @type {object}
 * @property {string} type - Error type from hls.js
 * @property {string} details - Error details from hls.js
 * @property {boolean} fatal - Always true for this event
 */

/**
 * Media information event with stream metadata
 * @event media_info
 * @type {MediaInfo}
 */

/**
 * Statistics information event (emitted every second during playback)
 * @event statistics_info
 * @type {StatsInfo}
 */

Event Data Types

Data structures for events emitted by the plugin.

interface MediaInfo {
  /** Video data rate in kbps */
  videoDataRate: number;
  /** Audio data rate in kbps */
  audioDataRate: number;
  /** Frames per second */
  fps?: number;
  /** Whether stream has audio track */
  hasAudio: boolean;
  /** Whether stream has video track */
  hasVideo: boolean;
  /** Audio channel count */
  audioChannelCount: number;
  /** Audio codec information */
  audioCodec: string;
  /** Video codec information */
  videoCodec: string;
  /** Video width in pixels */  
  width: number;
  /** Video height in pixels */
  height: number;
  /** Stream duration */
  duration: number;
  /** HLS quality level */
  level: number;
  /** MIME type with codecs */
  mimeType: string;
}

interface StatsInfo {
  /** Current download speed in KB/s */
  speed: number;
  /** Player type identifier */
  playerType: string; // Always 'HlsPlayer'
}

Utilities

Internal utility functions used by the plugin.

/**
 * Browser version detection utility
 * @returns {string} Browser name and version (e.g., "Chrome 95", "Firefox 94", "Unknown")
 */
function getBrowserVersion(): string;

Browser Support

The plugin requires HLS support via hls.js (checked via HlsJsPlugin.isSupported). Browser detection is handled internally for statistics purposes using the getBrowserVersion() utility.

Error Handling

The plugin automatically handles common HLS errors:

  • Network Errors: Attempts to restart loading (except for 404 errors)
  • Media Errors: Attempts media error recovery via hls.js
  • Fatal Errors: Emits error event to xgplayer

Dependencies

Required peer and direct dependencies:

// Peer dependencies (must be installed separately)
"xgplayer": ">=3.0.13"
"core-js": ">=3.12.1"

// Direct dependencies (installed automatically)
"hls.js": "^1.5.6"
"deepmerge": "2.0.1" 
"event-emitter": "^0.3.5"

Types

Configuration Types

interface HlsPluginConfig {
  hlsOpts?: HlsConfig;
}

interface HlsConfig {
  startPosition?: number;
  maxBufferLength?: number;
  maxMaxBufferLength?: number;
  debug?: boolean;
  fragLoadingTimeOut?: number;
  manifestLoadingTimeOut?: number;
  [key: string]: any;
}

Event Data Types

interface MediaInfo {
  videoDataRate: number;
  audioDataRate: number;
  fps?: number;
  hasAudio: boolean;
  hasVideo: boolean;
  audioChannelCount: number;
  audioCodec: string;
  videoCodec: string;
  width: number;
  height: number;
  duration: number;
  level: number;
  mimeType: string;
}

interface StatsInfo {
  speed: number;
  playerType: string;
}