Core Player API

/**
 * Creates a new Hls instance with optional configuration
 * @param userConfig - Optional configuration overrides
 */
constructor(userConfig?: Partial<HlsConfig>): Hls;

import Hls from "hls.js";

// Default configuration
const hls = new Hls();

// Custom configuration
const hlsCustom = new Hls({
  maxBufferLength: 60,
  maxBufferSize: 60 * 1000 * 1000,
  startLevel: -1, // Auto-select start level
  debug: false
});

/**
 * Attach the player to an HTML media element
 * @param media - HTML video element or media attachment data
 */
attachMedia(media: HTMLMediaElement | MediaAttachingData): void;

/**
 * Detach from the current media element
 */
detachMedia(): void;

/**
 * Transfer media attachment data for reattachment to another instance
 * @returns Attachment data or null if no media attached
 */
transferMedia(): AttachMediaSourceData | null;

const video = document.getElementById("video") as HTMLVideoElement;
const hls = new Hls();

// Basic attachment
hls.attachMedia(video);

// Listen for attachment completion
hls.on(Hls.Events.MEDIA_ATTACHED, () => {
  console.log("Media element attached successfully");
});

// Detach when done
hls.detachMedia();

/**
 * Set the HLS manifest URL to load
 * @param url - URL of the HLS manifest (.m3u8)
 */
loadSource(url: string): void;

/**
 * Start loading data at specified position
 * @param startPosition - Start position in seconds (optional)
 * @param skipSeekToStartPosition - Skip seeking to start position
 */
startLoad(startPosition?: number, skipSeekToStartPosition?: boolean): void;

/**
 * Stop loading data and clear buffers
 */
stopLoad(): void;

/**
 * Pause segment loading while keeping current buffers
 */
pauseBuffering(): void;

/**
 * Resume segment loading after pause
 */
resumeBuffering(): void;

const hls = new Hls();
hls.attachMedia(video);

// Load manifest
hls.loadSource("https://example.com/stream.m3u8");

// Start loading from beginning
hls.startLoad(0);

// Start loading at 30 seconds
hls.startLoad(30);

// Pause buffering (e.g., when tab is hidden)
hls.pauseBuffering();

// Resume buffering
hls.resumeBuffering();

// Stop loading completely
hls.stopLoad();

/**
 * Destroy the player instance and clean up resources
 */
destroy(): void;

/**
 * Remove a quality level from the levels array
 * @param levelIndex - Index of the level to remove
 */
removeLevel(levelIndex: number): void;

/**
 * Attempt to recover from media errors
 */
recoverMediaError(): void;

/**
 * Swap audio codec and try to recover from media error
 */
swapAudioCodec(): void;

const hls = new Hls();

// Use the player...

// Try to recover from media error
hls.recoverMediaError();

// Try swapping audio codec for recovery
hls.swapAudioCodec();

// Remove a quality level
hls.removeLevel(2);

// Clean up when done
hls.destroy();

interface Hls {
  /** Runtime configuration (read-only) */
  readonly config: HlsConfig;
  
  /** User-provided configuration (read-only) */
  readonly userConfig: Partial<HlsConfig>;
  
  /** Logger functions (read-only) */
  readonly logger: ILogger;
  
  /** Currently attached media element (read-only) */
  readonly media: HTMLMediaElement | null;
  
  /** Current source URL (read-only) */
  readonly url: string | null;
  
  /** Unique session identifier (read-only) */
  readonly sessionId: string;
  
  /** Whether all buffers are filled to the end (read-only) */
  readonly bufferedToEnd: boolean;
  
  /** Whether startLoad was called before manifest parsed (read-only) */
  readonly forceStartLoad: boolean;
  
  /** Whether loading is enabled (read-only) */
  readonly loadingEnabled: boolean;
  
  /** Whether buffering is enabled (read-only) */
  readonly bufferingEnabled: boolean;
  
  /** Whether player has enough data to start playback (read-only) */
  readonly hasEnoughToStart: boolean;
  
  /** Start position set on startLoad or autostart (read-only) */
  readonly startPosition: number;
  
  /** Latest level details for the current level (read-only) */
  readonly latestLevelDetails: LevelDetails | null;
  
  /** Current load level object (read-only) */
  readonly loadLevelObj: Level | null;
  
  /** Main forward buffer info (read-only) */
  readonly mainForwardBufferInfo: BufferInfo | null;
  
  /** Maximum buffer length in seconds (read-only) */
  readonly maxBufferLength: number;
  
  /** Available content delivery network pathways (read-only) */
  readonly pathways: string[];
  
  /** Pathway priority order */
  pathwayPriority: string[] | null;
}

const hls = new Hls({ debug: true });

// Access configuration
console.log("Max buffer length:", hls.config.maxBufferLength);
console.log("Debug enabled:", hls.userConfig.debug);

// Check current state
console.log("Current source:", hls.url);
console.log("Session ID:", hls.sessionId);
console.log("Media attached:", hls.media !== null);
console.log("Buffered to end:", hls.bufferedToEnd);

interface MediaAttachingData {
  media: HTMLMediaElement;
}

interface AttachMediaSourceData {
  media: HTMLMediaElement;
  mediaSource: MediaSource;
}

interface ILogger {
  trace: (...args: any[]) => void;
  debug: (...args: any[]) => void;
  log: (...args: any[]) => void;
  warn: (...args: any[]) => void;
  info: (...args: any[]) => void;
  error: (...args: any[]) => void;
}

interface BufferInfo {
  /** Buffer start time in seconds */
  start: number;
  
  /** Buffer end time in seconds */
  end: number;
  
  /** Buffer length in seconds */
  len: number;
}

interface LevelDetails {
  /** Whether this is a live stream */
  live: boolean;
  
  /** Playlist sequence number start */
  startSN: number;
  
  /** Playlist sequence number end */
  endSN: number;
  
  /** Total duration of the playlist */
  totalduration: number;
  
  /** Target duration for segments */
  targetduration: number;
  
  /** Media fragments in this level */
  fragments: Fragment[];
  
  /** Program date time */
  programDateTime: number | null;
  
  /** Whether playlist has ended */
  endlist: boolean;
}

interface Fragment {
  /** Fragment URL */
  url: string;
  
  /** Fragment duration in seconds */
  duration: number;
  
  /** Fragment sequence number */
  sn: number;
  
  /** Level index */
  level: number;
  
  /** Fragment start time */
  start: number;
  
  /** Fragment type */
  type: string;
}