hls-engine

A Rust HLS media engine with a shared native and WebAssembly core. It handles selected VOD and Live/EVENT inputs, resource and sample decryption, timeline ranges, multiple audio tracks, WebVTT cue muxing and MP4 output.

Transport, playlist refresh, rendition selection, key acquisition and WebVTT parsing belong to the application. The engine does not transcode media.

Install

[dependencies]
hls-engine = "1.4"

Disable default-source with default-features = false to provide your own Source without the built-in reqwest dependency. WASM builds use this option.

Feature	Purpose
default-source (default)	Native reqwest HTTP source
serde	Lossless playlist, report and checkpoint serialization
experimental-gcm	Fixed HLS draft-22 AES-256-GCM resource profile; runtime opt-in also required

Start a session

1. Parse each selected media playlist into a PlaylistSnapshot with a stable InputId.
2. Construct EngineInputs, a KeySession and EngineOptions.
3. Submit snapshots through EngineHandle, and end each finite input independently.
4. Run into_bytes, write_to, write_to_file or a split-output provider.

The executable example uses a synthetic TS resource and needs no network access:

cargo run --locked --example engine_demo

use hls_engine::{EngineInputs, EngineOptions, EngineSession, OutputFormat};
use hls_engine::crypto::key::KeySession;
use hls_engine::playlist::PlaylistSnapshot;

async fn collect(
    inputs: EngineInputs,
    keys: KeySession,
    snapshot: PlaylistSnapshot,
) -> Result<Vec<u8>, Box<dyn std::error::Error>> {
    let id = snapshot.context().input_id().clone();
    let session = EngineSession::new(inputs, keys, EngineOptions::default())?;
    session.handle().accept_snapshot(&id, &snapshot)?;
    session.handle().end_input(&id)?;
    let (bytes, _) = session
        .into_bytes(64 * 1024 * 1024, OutputFormat::FragmentedMp4)
        .await?;
    Ok(bytes)
}

For multiple inputs, supply the host waiter and clock-alignment evidence described in the Engine guide. A rendition sequence number is not a shared presentation clock. Admission is atomic: retry WouldBlock after capacity becomes available. stop drains accepted work; cancel aborts it.

Media and output

• MPEG-TS: AVC/HEVC video and AAC-LC audio.
• Fragmented MP4: supported AVC/HEVC/AAC-LC tracks with validated sample timing.
• Packed AAC: ID3 transport timestamps and validated ADTS frames.
• Decryption: AES-128 resources, TS SAMPLE-AES, supported fMP4 cbcs/cenc, and the explicitly enabled experimental GCM profile.
• Fixed multi-track sessions: selected AAC audio tracks and application-supplied WebVTT cues, with explicit epoch, range, gap and configuration-change policies.
• Fragmented MP4 output supports bounded recording. Native classic MP4 uses disk staging and a sample index whose size grows with the recording.

Native write_to_file and write_to_files default to FileFinalizationStrategy::Copy. Opt into FileFinalizationStrategy::InPlace to finalize the same temporary file: it reserves header space and, if necessary, moves media within that file so the result always remains faststart MP4. This avoids a second full media file but does not guarantee faster finalization. WASM output is unchanged. See Native file finalization for the options, scope and usage examples, and measurements for the performance comparison.

Container support and player support are separate decisions. Consult capabilities and player limits before enabling a combination. DRM/CDM, license exchange, LL-HLS partial segments, dynamic track replacement and transcoding are outside the supported profile.

Recovery and ownership

Native write_recoverable_to_file emits EngineCheckpoint values through an independent fallible callback: schema 2 for media-only output, schema 3 for joint fixed-file subtitle recovery. Persist them atomically. Restoration verifies resource identities, key versions, committed file prefixes and completed split children before appending. A fresh output never overwrites a competing file.

RecoveryOptions also supports opt-in InPlace classic finalization. Downloading remains recoverable, but once the persistent finalization marker is created, incomplete checkpoints are refused. Copy remains the default with full finalization recovery. See in-place recovery output.

Flush and SyncAll describe file durability. The caller still owns checkpoint and directory persistence, source/provider reconstruction and bounded replay of queued resources and cues. Runtime events and reports are not checkpoints. See recovery for the complete contract.

Borrowed writers are flushed and remain caller-owned. Their close/shutdown must finish before the application reports completion. Collected byte output requires an explicit capacity. Native file recovery is not exposed for WASM borrowed writers.

Documentation

The documentation index covers Engine sessions, encryption, playlists, WASM bridges, memory limits and compatibility APIs. The root Engine* API is the only execution path. See the 1.1 migration guide. Strict sessions preserve Engine checkpoint schemas 2/3; AAC repair uses schema 4. Schema 1 is unsupported.

Development

cargo test --locked --features serde,experimental-gcm
cargo fmt --all -- --check
cargo clippy --locked --all-targets --all-features -- -D warnings
python3 -m unittest discover -s scripts -p 'test_verify_*.py'

CI runs the feature matrix on Linux, macOS and Windows, real Node/Chrome WASM contracts, independent FFmpeg inspection, recovery and package checks. Repository scripts support that workflow and manual benchmarks; they are excluded from the published crate. The compressed crate has a 1 MiB CI budget. Full media/encryption corpora, integration tests, exporters and benchmarks stay in Git; the crate includes public examples and the small fixture subset needed by its unit tests.

中文说明

本项目提供共用的 Rust/native/WASM HLS 处理核心，支持有限和持续输入、解密、 时间范围、多音轨、字幕 cue 合流、MP4 输出及 native 文件恢复。应用负责网络传输、 清单刷新、选轨、密钥获取和 WebVTT 解析。接入使用 EngineSession，完整契约见 接入指南与支持范围。

License

MIT.