gohlslib

README

gohlslib

HLS client and muxer library for the Go programming language.

Go ≥ 1.18 is required.

This library was forked from MediaMTX, it is currently in alpha stage and implements only the features strictly needed by MediaMTX, but the aim is implementing a wide range of features that allow to read and generate HLS streams.

Client features:

name	state
Read MPEG-TS streams	OK
Read fMP4 streams	OK
Read Low-latency streams	TODO
Read H264 tracks	OK
Read H265 tracks	OK
Read MPEG4 Audio (AAC) tracks	OK
Read Opus tracks	OK
Read a given variant	TODO (currently a single variant is read)

Muxer features:

name	state
Generate MPEG-TS streams	OK
Generate fMP4 streams	OK
Generate Low-latency streams	OK
Write H264 tracks	OK
Write H265 tracks	OK
Write MPEG4 Audio (AAC) tracks	OK
Write Opus tracks	OK
Save generated segments on disk	OK
Generate multi-variant streams	TODO

General features:

name	state
Parse and produce M3U8 playlists	OK
Examples	TODO (missing muxer)

Table of contents

• Examples
• API Documentation
• Standards
• Links

Examples

• playlist-parser
• client

API Documentation

https://pkg.go.dev/github.com/bluenviron/gohlslib#pkg-index

Standards

• HLS https://datatracker.ietf.org/doc/html/rfc8216
• HLS v2 https://datatracker.ietf.org/doc/html/draft-pantos-hls-rfc8216bis
• ITU-T Rec. H.264 (08/2021) https://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.264-202108-I!!PDF-E&type=items
• ITU-T Rec. H.265 (08/2021) https://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-H.265-202108-I!!PDF-E&type=items
• ISO 14496-3, Coding of audio-visual objects, part 3, Audio
• Opus in MP4/ISOBMFF https://opus-codec.org/docs/opus_in_isobmff.html
• HTTP 1.1 https://datatracker.ietf.org/doc/html/rfc2616
• Golang project layout https://github.com/golang-standards/project-layout

Links

Related projects

• MediaMTX https://github.com/aler9/rtsp-simple-server

Documentation

Overview

Package gohlslib is a HLS client and muxer library for the Go programming language.

Examples are available at https://github.com/bluenviron/gohlslib/tree/main/examples

Index

• type Client
  • func (c *Client) Close()
  • func (c *Client) OnData(forma *Track, cb func(time.Duration, interface{}))
  • func (c *Client) OnTracks(cb func([]*Track) error)
  • func (c *Client) Start() error
  • func (c *Client) Wait() chan error
• type LogFunc
• type LogLevel
• type Muxer
  • func (m *Muxer) Close()
  • func (m *Muxer) File(name string, msn string, part string, skip string) *MuxerFileResponse
  • func (m *Muxer) Start() error
  • func (m *Muxer) WriteAudio(ntp time.Time, pts time.Duration, au []byte) error
  • func (m *Muxer) WriteH26x(ntp time.Time, pts time.Duration, au [][]byte) error
• type MuxerFileResponse
• type MuxerVariant
• type Track

Types

type Client

type Client struct {
	//
	// Parameters (all optional except URI)
	//
	// URI of the playlist.
	URI string
	// if the playlist certificate is self-signed
	// or invalid, you can provide the fingerprint of the certificate in order to
	// validate it anyway. It can be obtained by running:
	// openssl s_client -connect source_ip:source_port </dev/null 2>/dev/null | sed -n '/BEGIN/,/END/p' > server.crt
	// openssl x509 -in server.crt -noout -fingerprint -sha256 | cut -d "=" -f2 | tr -d ':'
	Fingerprint string
	// function that receives log messages.
	// It defaults to log.Printf.
	Log LogFunc
	// contains filtered or unexported fields
}

Client is a HLS client.

func (*Client) Close

func (c *Client) Close()

Close closes all the Client resources.

func (*Client) OnData

func (c *Client) OnData(forma *Track, cb func(time.Duration, interface{}))

OnData sets a callback that is called when data arrives.

func (*Client) OnTracks

func (c *Client) OnTracks(cb func([]*Track) error)

OnTracks sets a callback that is called when tracks are read.

func (*Client) Start

func (c *Client) Start() error

Start starts the client.

func (*Client) Wait

func (c *Client) Wait() chan error

Wait waits for any error of the Client.

type LogFunc

type LogFunc func(level LogLevel, format string, args ...interface{})

LogFunc is the prototype of the log function.

type LogLevel

type LogLevel int

LogLevel is a log level.

const (
	LogLevelDebug LogLevel = iota + 1
	LogLevelInfo
	LogLevelWarn
	LogLevelError
)

Log levels.

type Muxer

type Muxer struct {
	//
	// parameters (all optional except VideoTrack or AudioTrack).
	//
	// video track.
	VideoTrack *Track
	// audio track.
	AudioTrack *Track
	// Variant to use.
	// It defaults to MuxerVariantLowLatency
	Variant MuxerVariant
	// Number of HLS segments to keep on the server.
	// Segments allow to seek through the stream.
	// Their number doesn't influence latency.
	// It defaults to 7.
	SegmentCount int
	// Minimum duration of each segment.
	// A player usually puts 3 segments in a buffer before reproducing the stream.
	// The final segment duration is also influenced by the interval between IDR frames,
	// since the server changes the duration in order to include at least one IDR frame
	// in each segment.
	// It defaults to 1sec.
	SegmentDuration time.Duration
	// Minimum duration of each part.
	// Parts are used in Low-Latency HLS in place of segments.
	// A player usually puts 3 parts in a buffer before reproducing the stream.
	// Part duration is influenced by the distance between video/audio samples
	// and is adjusted in order to produce segments with a similar duration.
	// It defaults to 200ms.
	PartDuration time.Duration
	// Maximum size of each segment.
	// This prevents RAM exhaustion.
	// It defaults to 50MB.
	SegmentMaxSize uint64
	// Directory in which to save segments.
	// This decreases performance, since saving segments on disk is less performant
	// than saving them on RAM, but allows to preserve RAM.
	Directory string
	// contains filtered or unexported fields
}

Muxer is a HLS muxer.

func (*Muxer) Close

func (m *Muxer) Close()

Close closes a Muxer.

func (*Muxer) File

func (m *Muxer) File(name string, msn string, part string, skip string) *MuxerFileResponse

File returns a file reader.

func (*Muxer) Start

func (m *Muxer) Start() error

Start initializes the muxer.

func (*Muxer) WriteAudio

func (m *Muxer) WriteAudio(ntp time.Time, pts time.Duration, au []byte) error

WriteAudio writes an audio access unit.

func (*Muxer) WriteH26x

func (m *Muxer) WriteH26x(ntp time.Time, pts time.Duration, au [][]byte) error

WriteH26x writes an H264 or an H265 access unit.

type MuxerFileResponse

type MuxerFileResponse struct {
	Status int
	Header map[string]string
	Body   io.ReadCloser
}

MuxerFileResponse is a response of the Muxer's File() func. Body must always be closed.

type MuxerVariant

type MuxerVariant int

MuxerVariant is a muxer variant.

const (
	MuxerVariantMPEGTS MuxerVariant = iota + 1
	MuxerVariantFMP4
	MuxerVariantLowLatency
)

supported variants.

type Track

type Track struct {
	codecs.Codec
}

Track is a HLS track.