Skip to main content

​
Introduction

The @hls-downloader/core package is the heart of HLS Downloader, containing all shared business logic and state management for downloading and processing HLS video streams. Built with TypeScript, Redux Toolkit, and Redux-Observable, it provides a clean separation between business logic and platform-specific implementations.

​
Package information

​
name
string
@hls-downloader/core
​
version
string
0.0.0
​
license
string
MIT

​
Architecture

The core package is organized into several key modules:

​
Use cases

Business logic functions that perform specific operations like downloading fragments, decrypting content, and managing file storage. Each use case is a factory function that accepts service dependencies and returns an executable function. See Use cases for detailed documentation.

​
Controllers (Epics)

Redux-Observable epics that orchestrate asynchronous workflows by listening to actions and coordinating use cases. These handle complex operations like download jobs, playlist management, and subtitle processing. See Controllers for detailed documentation.

​
Store

Redux store configuration using Redux Toolkit slices to manage application state including playlists, jobs, levels, and configuration. The store is the single source of truth for the extension’s state. See Store for detailed documentation.

​
Entities

Core data types and classes representing domain concepts:
  • Playlist: HLS master playlist representation
  • Level: Individual quality level or track (video, audio, subtitle)
  • Fragment: Individual media segment to download
  • Job: Download job containing fragments and metadata
  • Key: Encryption key information for decryption

​
Services

Abstract interfaces for platform-specific functionality that must be implemented by consuming packages: 
export interface ILoader {
  fetchText(uri: string, attempts: number): Promise<string>;
  fetchArrayBuffer(uri: string, attempts: number): Promise<ArrayBuffer>;
}

​
Dependencies

The core package relies on these key libraries:
  • @reduxjs/toolkit (1.9.3): Redux state management with modern patterns
  • redux-observable (2.0.0): RxJS-based middleware for handling async actions
  • rxjs (7.8.0): Reactive programming for complex async workflows
  • typesafe-actions (5.1.0): Type-safe Redux action creators

​
Data flow

  1. User action: UI dispatches a Redux action
  2. Epic listening: Corresponding epic filters and processes the action
  3. Use case execution: Epic calls use case factories with dependencies
  4. Service interaction: Use cases interact with services (loader, parser, fs, decryptor)
  5. State update: Epic dispatches new actions to update Redux store
  6. UI reaction: React components re-render based on state changes
The core package contains no platform-specific code. All browser APIs, file system operations, and network requests are abstracted behind service interfaces.

​
Usage example

import { createStore } from '@hls-downloader/core';
import { Dependencies } from '@hls-downloader/core';

// Implement service interfaces
const dependencies: Dependencies = {
  loader: myLoaderImplementation,
  parser: myParserImplementation,
  decryptor: myDecryptorImplementation,
  fs: myFileSystemImplementation,
};

// Create Redux store with dependencies
const store = createStore(dependencies);

// Dispatch actions to trigger workflows
store.dispatch(playlistsSlice.actions.addPlaylist({
  id: 'playlist-1',
  uri: 'https://example.com/master.m3u8',
  createdAt: Date.now(),
}));

​
Testing

The core package includes comprehensive unit tests using Vitest: 
pnpm test:core

​
Build output

Source TypeScript files in src/core/src/ compile to JavaScript in src/core/lib/. Never modify the lib/ directory directly.

Build docs developers (and LLMs) love

Get started for freeTalk to us