Packages

membrane_hls_plugin

3.0.10
3.0.10 3.0.9 3.0.8 3.0.7 3.0.6 3.0.5 3.0.4 3.0.3 3.0.2 3.0.1 3.0.0 2.1.9 2.1.8 2.1.7 2.1.6 2.1.5 2.1.4 2.1.3 2.1.2 2.1.1 2.1.0 2.0.16 2.0.15 2.0.14 2.0.13 2.0.12 2.0.11 2.0.10 2.0.9 2.0.8 2.0.7 2.0.6 2.0.5 2.0.4 2.0.3 2.0.2 2.0.1 2.0.0 1.1.12 1.1.11 1.1.10 1.1.9 1.1.8 1.1.7 1.1.6 1.1.5 1.1.4 1.1.3 1.1.2 1.1.1 1.1.0 1.0.0

Adaptive live streaming (HLS) plugin for the Membrane Framework.

HexDocs

Current section

Files

Jump to
Readme
52 Versions
9 Dependencies
Dependants
Files
Activity
membrane_hls_plugin README.md
Raw

README.md 

# Membrane HLS Plugin

![Hex.pm Version](https://img.shields.io/hexpm/v/membrane_hls_plugin)



Adaptive live streaming plugin (HLS) for the Membrane Framework, used in production.



## Features



### Source Elements

- `Membrane.HLS.Source` reads a single media playlist (VOD or live/event) and emits raw segment payloads

- `Membrane.HLS.SourceBin` reads a master playlist and exposes renditions as dynamic output pads

- Supports multiple renditions (video, audio, subtitles)

- Handles dynamic playlist updates for live streams

- Built-in storage abstraction for different backends



### Sink Element (SinkBin)

- **Multiple Container Formats**:

  - CMAF segments (default) - Modern fragmented MP4

  - MPEG-TS segments - Traditional transport stream

  - Packed AAC - Audio-only streams

  - **AAC over TS** - ⚠️ **Experimental**: Audio streams packed in Transport Stream containers

  - WebVTT - Subtitle tracks



- **Stream Types Supported**:

  - H.264 video encoding

  - AAC audio encoding  

  - Text subtitles (WebVTT format)



- **Operating Modes** (via `playlist_mode`):

  - `:vod` - segments are synced as soon as the next segment group is ready

  - `{:event, safety_delay}` - live event playlists synced on a target-duration cadence

  - `{:sliding, max_segments, safety_delay}` - live playlists with rolling window support



### Advanced Features

- **Codec Serialization**: Automatic codec string generation (avc1, hvc1, mp4a)

- **Automatic Master Metadata**: BANDWIDTH/AVERAGE-BANDWIDTH and CODECS are computed by SinkBin/Packager when possible

- **Deprecation Notice**: Manually setting `HLS.VariantStream.bandwidth` and `HLS.VariantStream.codecs` in `build_stream` is deprecated

- **Segment Management**: Configurable target segment durations

- **Multi-track Support**: Audio, video, and subtitle tracks in single pipeline



### Timing Contract and Policies

- **Upstream timestamps are authoritative**: SinkBin does not shift, trim, or synthesize PTS/DTS.

- **Alignment required**: Tracks that produce segments at a sync point must be time-aligned

  (minor AAC/H264 cut differences are tolerated by the packager).

- **RFC-compliant output**: discontinuities are inserted when needed; playlists remain spec compliant.

- **Error policy**:

  - `:vod` is strict and fails fast on packager errors.

  - `:event`/`:sliding` are tolerant to recoverable timing issues but fail fast on missing

    mandatory track segments to avoid silent stalls.



## Architecture



The plugin is built on the Membrane Framework and integrates with the `kim_hls` library for playlist management:



- `Membrane.HLS.SinkBin` - Main bin for processing input streams into HLS segments (accepts `manifest_uri`, `playlist_mode`, and `HLS.Storage`)

- `Membrane.HLS.Source` - Source element for a single media playlist

- `Membrane.HLS.SourceBin` - Bin wrapper that discovers renditions from a master playlist



### Source Behavior

- `Membrane.HLS.Source` is demand-driven for VOD playlists and polls live/event playlists for new segments.

- Segment payloads are forwarded as-is; callers provide `stream_format` to describe the container.

- `Membrane.HLS.SourceBin` handles master playlist discovery and spins up one `Membrane.HLS.Source`

  per rendition, emitting them via dynamic output pads.

- Various sink implementations for different container formats

- Automatic codec detection and stream format handling



## Dependencies



Key dependencies include:

- `membrane_core` - Core Membrane Framework

- `kim_hls` - HLS playlist and segment management

- `membrane_mp4_plugin` - MP4/CMAF container support

- `membrane_aac_plugin` - AAC audio processing

- `membrane_h26x_plugin` - H.264/H.265 video processing

- `membrane_mpeg_ts_plugin` - MPEG-TS container support



## Copyright and License

Copyright 2025, [KIM Keep In Mind GmbH](https://www.keepinmind.info/)

Licensed under the [Apache License, Version 2.0](LICENSE)