HlsDownloader

The main facade class for downloading HLS streams. Imported from @hls-downloader/core.

Constructor

new HlsDownloader({
  adapter,
  option?,
  onEvent?,
})

Parameter	Type	Description
adapter	WasmAdapter | RustAdapter	The adapter to use
option	object	Default fetch options (e.g. headers) plus adapter-specific options. Merged with each parseHls / download call
onEvent	(event, payload?) => void	Event callback for tracking progress and errors

Properties

isInit

get isInit(): boolean

Whether the adapter has been initialized. Returns true after init() resolves.

Methods

init()

async init(): Promise<void>

Initialize the adapter. For the WASM adapter this loads FFmpeg; for the Rust adapter it prepares the native module. Must be called before download(). Calling download() automatically triggers init() if not yet initialized.

setOption()

setOption(option): void

Update the default options (per-call url is not stored here). Accepts the same shape as the constructor option. Options set here are merged with each parseHls / download call.

parseHls()

async parseHls(option: HlsDownloaderFetchOption): Promise<ParseHlsResult>

Parse an HLS playlist without downloading segments. Returns a ParseHlsResult:

• { type: 'playlist', data: Playlist[] } — master playlist with variant streams
• { type: 'segment', data: Segment[] } — media playlist with segments
• { type: 'error', message: string } — parse error

download()

async download(
  option: HlsDownloaderFetchOption & HlsDownloaderDownloadOption
): Promise<DownloadResult>

Parse, download all segments, and merge them into a single file. Returns { blobURL, totalSegments } on success, or void on failure.

Option	Type	Description
url	string	HLS playlist URL
headers	Record<string, string>	Request headers
filename	string	Output filename
maxRetry	number	Max retry attempts per segment
downloadConcurrency	number	Concurrent segment downloads

getPosterUrl()

async getPosterUrl(
  option: HlsDownloaderFetchOption
): Promise<string | undefined>

Attempt to extract a poster/thumbnail image URL from the stream. Returns the URL string if found, otherwise undefined.