HLS Receiver¶

MediaX can play an HTTP Live Streaming (HLS, RFC 8216) stream. mediax::hls::HlsDepayloader downloads the playlist and the MPEG-2 transport stream segments, demultiplexes the video, wraps each access unit in RTP (RFC 6184) and hands it to the H.264 decoder. It is a drop-in mediax::rtp::RtpDepayloader, so frames are received exactly as for the RTSP and SRT receivers.

Requirements¶

• BUILD_HLS=ON (the default). Not available on Windows.
• libcurl (libcurl4-openssl-dev), see Installation.
• OpenSSL (libssl-dev) to play AES-128 encrypted streams, such as the ABC TV feed.
• An H.264 decoder backend. The OpenH264 software decoder (BUILD_OPENH264=ON) is used by default.
• Optional, to receive audio as PCM: BUILD_HLS_AUDIO_DECODE=ON and FFmpeg libavcodec-dev libavutil-dev.

Features¶

Usage¶

#include <iostream>
#include "hls/hls_depayloader.h"

int main() {
  mediax::hls::HlsClientConfig config;
  config.preferred_height = 576;  // Closest variant, 0 selects the highest bandwidth

  mediax::hls::HlsDepayloader rx;
  rx.SetClientConfig(config);
  rx.SetUrl("https://example.com/live/stream.m3u8");

  if (!rx.Open()) {
    std::cerr << rx.GetLastError() << "\n";
    return 1;
  }
  rx.Start();

  mediax::rtp::RtpFrameData frame;
  while (rx.Receive(&frame, 5000)) {
    std::cout << frame.resolution.width << "x" << frame.resolution.height << "\n";
  }
  rx.Close();
  return 0;
}

Register frame and error callbacks before calling Open(). Errors may be reported from a worker thread.

Audio¶

Audio muxed into the transport stream segments is passed to a callback. MediaX does not play it: the application owns the speaker output and sends the data to its audio device (ALSA, PulseAudio, SDL, Qt Multimedia, ...).

rx.RegisterAudioCallback([](const mediax::hls::HlsAudioFrame& audio) {
  if (audio.format == mediax::hls::HlsAudioFormat::kPcmS16) {
    // audio.pcm: interleaved 16 bit samples, audio.channels per sample time, at audio.sample_rate Hz
    PlayPcm(audio.pcm.data(), audio.SamplesPerChannel(), audio.channels, audio.sample_rate);
  } else {
    // audio.encoded: AAC (ADTS or LATM), MPEG audio, AC-3 or E-AC-3 exactly as in the stream
    DecodeAndPlay(audio.format, audio.encoded);
  }
});
rx.Open();  // Register the callback first

Check HasBuiltInAudioDecoder() to see whether the library has the libavcodec decoder. A custom decoder derives from mediax::hls::HlsAudioDecoder:

rx.SetAudioDecoderFactory([](mediax::hls::HlsAudioFormat format) -> std::unique_ptr<mediax::hls::HlsAudioDecoder> {
  if (format != mediax::hls::HlsAudioFormat::kAacAdts) return nullptr;  // nullptr delivers this audio encoded
  return std::make_unique<MyAacDecoder>();
});

The factory is called on the download thread when the first audio of a stream arrives.

Configuration¶

mediax::hls::HlsClientConfig:

Status and Statistics¶

GetLastStatus() returns an HlsStatus: kOk, kInvalidArgument, kInvalidState, kNetworkError, kHttpError, kTimeout, kParseError, kUnsupported or kCancelled. Use HlsStatusToString() for text and GetLastError() for the detail.

GetStatistics() returns playlist requests, segments and bytes downloaded, frames delivered, RTP packets, audio blocks delivered, errors and the next segment sequence number. GetVariant() returns the playing variant (URI, bandwidth, size, codecs, frame rate).

Console Example¶

hls-receive --url=https://example.com/live/stream.m3u8 --height=576 --record=out.mkv
hls-receive --url=https://example.com/live/stream.m3u8 --audio_dump=audio.raw   # Receive the audio too
hls-player                                                                       # SDL2 player with sound, plays ABC TV

The Qt6 player examples can also show HLS streams, and check a playlist is live, see RTSP Receiver and Examples.

Related¶

• C++ API: HLS classes
• The transport stream layer is shared with SRT, see C++ API: MPEG-TS classes