Parse and demux MPEG Transport Streams (.ts) natively in GO

[![GoReportCard](http://goreportcard.com/badge/github.com/asticode/go-astits)](http://goreportcard.com/report/github.com/asticode/go-astits)
[![GoDoc](https://godoc.org/github.com/asticode/go-astits?status.svg)](https://godoc.org/github.com/asticode/go-astits)
[![Test](https://github.com/asticode/go-astits/actions/workflows/test.yml/badge.svg)](https://github.com/asticode/go-astits/actions/workflows/test.yml)
[![Coveralls](https://coveralls.io/repos/github/asticode/go-astits/badge.svg?branch=master)](https://coveralls.io/github/asticode/go-astits)

This is a Golang library to natively demux and mux MPEG Transport Streams (ts) in GO.

WARNING: this library is not yet production ready. Use at your own risks!

# Installation

To install the library use the following:

    go get -u github.com/asticode/go-astits/...

To install the executables use the following:

    go install github.com/asticode/go-astits/cmd
    
# Before looking at the code...

The transport stream is made of packets.<br>
Each packet has a header, an optional adaptation field and a payload.<br>
Several payloads can be appended and parsed as a data.

```
                                           TRANSPORT STREAM
 +--------------------------------------------------------------------------------------------------+
 |                                                                                                  |
 
                       PACKET                                         PACKET
 +----------------------------------------------+----------------------------------------------+----
 |                                              |                                              |
 
 +--------+---------------------------+---------+--------+---------------------------+---------+
 | HEADER | OPTIONAL ADAPTATION FIELD | PAYLOAD | HEADER | OPTIONAL ADAPTATION FIELD | PAYLOAD | ...
 +--------+---------------------------+---------+--------+---------------------------+---------+
 
                                      |         |                                    |         |
                                      +---------+                                    +---------+
                                           |                                              |
                                           +----------------------------------------------+
                                                                DATA
```
    
# Using the library in your code

WARNING: the code below doesn't handle errors for readability purposes. However you SHOULD!

## Demux

```go
// Create a cancellable context in case you want to stop reading packets/data any time you want
ctx, cancel := context.WithCancel(context.Background())

// Handle SIGTERM signal
ch := make(chan os.Signal, 1)
signal.Notify(ch, syscall.SIGTERM)
go func() {
    <-ch
    cancel()
}()

// Open your file or initialize any kind of io.Reader
// Buffering using bufio.Reader is recommended for performance
f, _ := os.Open("/path/to/file.ts")
defer f.Close()

// Create the demuxer
dmx := astits.NewDemuxer(ctx, f)
for {
    // Get the next data
    d, _ := dmx.NextData()
    
    // Data is a PMT data
    if d.PMT != nil {
        // Loop through elementary streams
        for _, es := range d.PMT.ElementaryStreams {
                fmt.Printf("Stream detected: %d\n", es.ElementaryPID)
        }
        return
    }
}
```

## Mux

```go
// Create a cancellable context in case you want to stop writing packets/data any time you want
ctx, cancel := context.WithCancel(context.Background())

// Handle SIGTERM signal
ch := make(chan os.Signal, 1)
signal.Notify(ch, syscall.SIGTERM)
go func() {
    <-ch
    cancel()
}()

// Create your file or initialize any kind of io.Writer
// Buffering using bufio.Writer is recommended for performance
f, _ := os.Create("/path/to/file.ts")
defer f.Close()

// Create the muxer
mx := astits.NewMuxer(ctx, f)

// Add an elementary stream
mx.AddElementaryStream(astits.PMTElementaryStream{
    ElementaryPID: 1,
    StreamType:    astits.StreamTypeMetadata,
})

// Write tables
// Using that function is not mandatory, WriteData will retransmit tables from time to time 
mx.WriteTables()

// Write data
mx.WriteData(&astits.MuxerData{
    PES: &astits.PESData{
        Data: []byte("test"),
    },
    PID: 1,
})
```

## Options

In order to pass options to the demuxer or the muxer, look for the methods prefixed with `DemuxerOpt` or `MuxerOpt` and add them upon calling `NewDemuxer` or `NewMuxer` :

```go
// This is your custom packets parser
p := func(ps []*astits.Packet) (ds []*astits.Data, skip bool, err error) {
        // This is your logic
        skip = true
        return
}

// Now you can create a demuxer with the proper options
dmx := NewDemuxer(ctx, f, DemuxerOptPacketSize(192), DemuxerOptPacketsParser(p))
```

# CLI

This library provides 2 CLIs that will automatically get installed in `GOPATH/bin` on `go get` execution.

## astits-probe

### List streams

    $ astits-probe -i <path to your file> -f <format: text|json (default: text)>

### List packets

    $ astits-probe packets -i <path to your file>

### List data

    $ astits-probe data -i <path to your file> -d <data type: eit|nit|... (repeatable argument | if empty, all data types are shown)>

## astits-es-split

### Split streams into separate .ts files

    $ astits-es-split <path to your file> -o <path to output dir>

# Features and roadmap

- [x] Add demuxer
- [x] Add muxer
- [x] Demux PES packets
- [x] Mux PES packets
- [x] Demux PAT packets
- [x] Mux PAT packets
- [x] Demux PMT packets
- [x] Mux PMT packets
- [x] Demux EIT packets
- [ ] Mux EIT packets
- [x] Demux NIT packets
- [ ] Mux NIT packets
- [x] Demux SDT packets
- [ ] Mux SDT packets
- [x] Demux TOT packets
- [ ] Mux TOT packets
- [ ] Demux BAT packets
- [ ] Mux BAT packets
- [ ] Demux DIT packets
- [ ] Mux DIT packets
- [ ] Demux RST packets
- [ ] Mux RST packets
- [ ] Demux SIT packets
- [ ] Mux SIT packets
- [ ] Mux ST packets
- [ ] Demux TDT packets
- [ ] Mux TDT packets
- [ ] Demux TSDT packets
- [ ] Mux TSDT packets


go-astits

# Deprecation Notice

This repository is no longer maintained.

# goav
Golang binding for FFmpeg

A comprehensive binding to the ffmpeg video/audio manipulation library.

[![GoDoc](https://godoc.org/github.com/giorgisio/goav?status.svg)](https://godoc.org/github.com/giorgisio/goav)

## Usage

`````go

import "github.com/giorgisio/goav/avformat"

func main() {

	filename := "sample.mp4"

	// Register all formats and codecs
	avformat.AvRegisterAll()

	ctx := avformat.AvformatAllocContext()

	// Open video file
	if avformat.AvformatOpenInput(&ctx, filename, nil, nil) != 0 {
		log.Println("Error: Couldn't open file.")
		return
	}

	// Retrieve stream information
	if ctx.AvformatFindStreamInfo(nil) < 0 {
		log.Println("Error: Couldn't find stream information.")

		// Close input file and free context
		ctx.AvformatCloseInput()
		return
	}

	//...

}
`````

## Libraries

* `avcodec` corresponds to the ffmpeg library: libavcodec [provides implementation of a wider range of codecs]
* `avformat` corresponds to the ffmpeg library: libavformat [implements streaming protocols, container formats and basic I/O access]
* `avutil` corresponds to the ffmpeg library: libavutil [includes hashers, decompressors and miscellaneous utility functions]
* `avfilter` corresponds to the ffmpeg library: libavfilter [provides a mean to alter decoded Audio and Video through chain of filters]
* `avdevice` corresponds to the ffmpeg library: libavdevice [provides an abstraction to access capture and playback devices]
* `swresample` corresponds to the ffmpeg library: libswresample [implements audio mixing and resampling routines]
* `swscale` corresponds to the ffmpeg library: libswscale [implements color conversion and scaling routines]


## Installation

[FFMPEG INSTALL INSTRUCTIONS](https://github.com/FFmpeg/FFmpeg/blob/master/INSTALL.md)

``` sh
sudo apt-get -y install autoconf automake build-essential libass-dev libfreetype6-dev libsdl1.2-dev libtheora-dev libtool libva-dev libvdpau-dev libvorbis-dev libxcb1-dev libxcb-shm0-dev libxcb-xfixes0-dev pkg-config texi2html zlib1g-dev

sudo apt install -y libavdevice-dev libavfilter-dev libswscale-dev libavcodec-dev libavformat-dev libswresample-dev libavutil-dev

sudo apt-get install yasm

export FFMPEG_ROOT=$HOME/ffmpeg
export CGO_LDFLAGS="-L$FFMPEG_ROOT/lib/ -lavcodec -lavformat -lavutil -lswscale -lswresample -lavdevice -lavfilter"
export CGO_CFLAGS="-I$FFMPEG_ROOT/include"
export LD_LIBRARY_PATH=$HOME/ffmpeg/lib
``` 

``` 
go get github.com/giorgisio/goav

``` 

## More Examples

Coding examples are available in the examples/ directory.

## Note
- Function names in Go are consistent with that of the libraries to help with easy search
- [cgo: Extending Go with C](http://blog.giorgis.io/cgo-examples)
- goav comes with absolutely no warranty.

## Contribute
- Fork this repo and create your own feature branch.
- Follow standard Go conventions
- Test your code.
- Create pull request

## TODO

- [ ] Returning Errors
- [ ] Garbage Collection
- [X] Review included/excluded functions from each library
- [ ] Go Tests
- [ ] Possible restructuring packages
- [x] Tutorial01.c
- [ ] More Tutorial

## License
This library is under the [MIT License](http://opensource.org/licenses/MIT)


goav

# gortsplib

[![Test](https://github.com/bluenviron/gortsplib/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/bluenviron/gortsplib/actions/workflows/test.yml?query=branch%3Amain)
[![Lint](https://github.com/bluenviron/gortsplib/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/bluenviron/gortsplib/actions/workflows/lint.yml?query=branch%3Amain)
[![Go Report Card](https://goreportcard.com/badge/github.com/bluenviron/gortsplib)](https://goreportcard.com/report/github.com/bluenviron/gortsplib)
[![CodeCov](https://codecov.io/gh/bluenviron/gortsplib/branch/main/graph/badge.svg)](https://app.codecov.io/gh/bluenviron/gortsplib/tree/main)
[![PkgGoDev](https://pkg.go.dev/badge/github.com/bluenviron/gortsplib/v5)](https://pkg.go.dev/github.com/bluenviron/gortsplib/v5#pkg-index)

RTSP client and server library for the Go programming language, written for [MediaMTX](https://github.com/bluenviron/mediamtx).

Go &ge; 1.25 is required.

Features:

* Client
  * Support secure protocol variants (RTSPS, SRTP, SRTCP)
  * Support tunneling (RTSP-over-HTTP, RTSP-over-WebSocket)
  * Query servers about available media streams
  * Read media streams from a server ("play")
    * Read streams with the UDP, UDP-multicast or TCP transport protocol
    * Switch transport protocol automatically
    * Read selected media streams
    * Pause or seek without disconnecting from the server
    * Write to ONVIF back channels
    * Get PTS (presentation timestamp) of inbound packets
    * Get NTP (absolute timestamp) of inbound packets
  * Write media streams to a server ("record")
    * Write streams with the UDP or TCP transport protocol
    * Switch transport protocol automatically
    * Pause without disconnecting from the server
* Server
  * Support secure protocol variants (RTSPS, SRTP, SRTCP)
  * Support tunneling (RTSP-over-HTTP, RTSP-over-WebSocket)
  * Handle requests from clients
  * Validate client credentials
  * Read media streams from clients ("record")
    * Read streams with the UDP or TCP transport protocol
    * Get PTS (presentation timestamp) of inbound packets
    * Get NTP (absolute timestamp) of inbound packets
  * Serve media streams to clients ("play")
    * Write streams with the UDP, UDP-multicast or TCP transport protocol
    * Compute and provide SSRC, RTP-Info to clients
    * Read ONVIF back channels
* Utilities
  * Parse RTSP elements
  * Encode/decode RTP packets into/from codec-specific frames

## Table of contents

* [Examples](#examples)
* [API Documentation](#api-documentation)
* [RTP Payload Formats](#rtp-payload-formats)
* [Specifications](#specifications)
* [Related projects](#related-projects)

## Examples

* [client-query](examples/client-query/main.go)
* [client-play](examples/client-play/main.go)
* [client-play-timestamp](examples/client-play-timestamp/main.go)
* [client-play-options](examples/client-play-options/main.go)
* [client-play-pause](examples/client-play-pause/main.go)
* [client-play-to-record](examples/client-play-to-record/main.go)
* [client-play-backchannel](examples/client-play-backchannel/main.go)
* [client-play-format-av1](examples/client-play-format-av1/main.go)
* [client-play-format-av1-to-jpeg](examples/client-play-format-av1-to-jpeg/main.go)
* [client-play-format-g711](examples/client-play-format-g711/main.go)
* [client-play-format-h264](examples/client-play-format-h264/main.go)
* [client-play-format-h264-to-jpeg](examples/client-play-format-h264-to-jpeg/main.go)
* [client-play-format-h264-to-disk](examples/client-play-format-h264-to-disk/main.go)
* [client-play-format-h264-mpeg4audio-to-disk](examples/client-play-format-h264-mpeg4audio-to-disk/main.go)
* [client-play-format-h265](examples/client-play-format-h265/main.go)
* [client-play-format-h265-to-jpeg](examples/client-play-format-h265-to-jpeg/main.go)
* [client-play-format-h265-to-disk](examples/client-play-format-h265-to-disk/main.go)
* [client-play-format-lpcm](examples/client-play-format-lpcm/main.go)
* [client-play-format-mjpeg](examples/client-play-format-mjpeg/main.go)
* [client-play-format-mpeg4audio](examples/client-play-format-mpeg4audio/main.go)
* [client-play-format-mpeg4audio-to-disk](examples/client-play-format-mpeg4audio-to-disk/main.go)
* [client-play-format-opus](examples/client-play-format-opus/main.go)
* [client-play-format-opus-to-disk](examples/client-play-format-opus-to-disk/main.go)
* [client-play-format-vp8](examples/client-play-format-vp8/main.go)
* [client-play-format-vp9](examples/client-play-format-vp9/main.go)
* [client-record-options](examples/client-record-options/main.go)
* [client-record-pause](examples/client-record-pause/main.go)
* [client-record-format-av1](examples/client-record-format-av1/main.go)
* [client-record-format-g711](examples/client-record-format-g711/main.go)
* [client-record-format-h264](examples/client-record-format-h264/main.go)
* [client-record-format-h264-from-disk](examples/client-record-format-h264-from-disk/main.go)
* [client-record-format-h265](examples/client-record-format-h265/main.go)
* [client-record-format-lpcm](examples/client-record-format-lpcm/main.go)
* [client-record-format-mjpeg](examples/client-record-format-mjpeg/main.go)
* [client-record-format-mpeg4audio](examples/client-record-format-mpeg4audio/main.go)
* [client-record-format-opus](examples/client-record-format-opus/main.go)
* [client-record-format-vp8](examples/client-record-format-vp8/main.go)
* [client-record-format-vp9](examples/client-record-format-vp9/main.go)
* [client-record-format-klv](examples/client-record-format-klv/main.go)
* [server](examples/server/main.go)
* [server-secure](examples/server-secure/main.go)
* [server-auth](examples/server-auth/main.go)
* [server-record-format-h264-to-disk](examples/server-record-format-h264-to-disk/main.go)
* [server-play-format-h264-from-disk](examples/server-play-format-h264-from-disk/main.go)
* [server-play-backchannel](examples/server-play-backchannel/main.go)
* [proxy](examples/proxy/main.go)
* [proxy-backchannel](examples/proxy-backchannel/main.go)

## API Documentation

[Click to open the API Documentation](https://pkg.go.dev/github.com/bluenviron/gortsplib/v5#pkg-index)

## RTP Payload Formats

In RTSP, media streams are transmitted by using RTP packets, which are encoded in a specific, codec-dependent, format. This library supports the following formats:

### Video

|format|documentation|encoder and decoder available|
|------|-------------|-----------------------------|
|AV1|[link](https://pkg.go.dev/github.com/bluenviron/gortsplib/v5/pkg/format#AV1)|:heavy_check_mark:|
|VP9|[link](https://pkg.go.dev/github.com/bluenviron/gortsplib/v5/pkg/format#VP9)|:heavy_check_mark:|
|VP8|[link](https://pkg.go.dev/github.com/bluenviron/gortsplib/v5/pkg/format#VP8)|:heavy_check_mark:|
|H265|[link](https://pkg.go.dev/github.com/bluenviron/gortsplib/v5/pkg/format#H265)|:heavy_check_mark:|
|H264|[link](https://pkg.go.dev/github.com/bluenviron/gortsplib/v5/pkg/format#H264)|:heavy_check_mark:|
|MPEG-4 Video (H263, Xvid)|[link](https://pkg.go.dev/github.com/bluenviron/gortsplib/v5/pkg/format#MPEG4Video)|:heavy_check_mark:|
|MPEG-1/2 Video|[link](https://pkg.go.dev/github.com/bluenviron/gortsplib/v5/pkg/format#MPEG1Video)|:heavy_check_mark:|
|M-JPEG|[link](https://pkg.go.dev/github.com/bluenviron/gortsplib/v5/pkg/format#MJPEG)|:heavy_check_mark:|

### Audio

|format|documentation|encoder and decoder available|
|------|-------------|-----------------------------|
|Opus|[link](https://pkg.go.dev/github.com/bluenviron/gortsplib/v5/pkg/format#Opus)|:heavy_check_mark:|
|Vorbis|[link](https://pkg.go.dev/github.com/bluenviron/gortsplib/v5/pkg/format#Vorbis)||
|MPEG-4 Audio (AAC)|[link](https://pkg.go.dev/github.com/bluenviron/gortsplib/v5/pkg/format#MPEG4Audio)|:heavy_check_mark:|
|MPEG-4 Audio LATM (AAC-LATM)|[link](https://pkg.go.dev/github.com/bluenviron/gortsplib/v5/pkg/format#MPEG4AudioLATM)|:heavy_check_mark:|
|MPEG-1/2 Audio (MP3)|[link](https://pkg.go.dev/github.com/bluenviron/gortsplib/v5/pkg/format#MPEG1Audio)|:heavy_check_mark:|
|AC-3|[link](https://pkg.go.dev/github.com/bluenviron/gortsplib/v5/pkg/format#AC3)|:heavy_check_mark:|
|Speex|[link](https://pkg.go.dev/github.com/bluenviron/gortsplib/v5/pkg/format#Speex)||
|G726|[link](https://pkg.go.dev/github.com/bluenviron/gortsplib/v5/pkg/format#G726)||
|G722|[link](https://pkg.go.dev/github.com/bluenviron/gortsplib/v5/pkg/format#G722)|:heavy_check_mark:|
|G711 (PCMA, PCMU)|[link](https://pkg.go.dev/github.com/bluenviron/gortsplib/v5/pkg/format#G711)|:heavy_check_mark:|
|LPCM|[link](https://pkg.go.dev/github.com/bluenviron/gortsplib/v5/pkg/format#LPCM)|:heavy_check_mark:|

### Other

|format|documentation|encoder and decoder available|
|------|-------------|-----------------------------|
|MPEG-TS|[link](https://pkg.go.dev/github.com/bluenviron/gortsplib/v5/pkg/format#MPEGTS)|:heavy_check_mark:|
|KLV|[link](https://pkg.go.dev/github.com/bluenviron/gortsplib/v5/pkg/format#KLV)|:heavy_check_mark:|

## Specifications

|name|area|
|----|----|
|[RFC2326, RTSP 1.0](https://datatracker.ietf.org/doc/html/rfc2326)|protocol|
|[RFC7826, RTSP 2.0](https://datatracker.ietf.org/doc/html/rfc7826)|protocol|
|[ONVIF Streaming Specification 23.06](https://www.onvif.org/specs/stream/ONVIF-Streaming-Spec.pdf)|protocol|
|[RFC8866, SDP: Session Description Protocol](https://datatracker.ietf.org/doc/html/rfc8866)|SDP|
|[RFC4567, Key Management Extensions for Session Description Protocol (SDP) and Real Time Streaming Protocol (RTSP)](https://datatracker.ietf.org/doc/html/rfc4567)|secure variants|
|[RFC3830, MIKEY: Multimedia Internet KEYing](https://datatracker.ietf.org/doc/html/rfc3830)|secure variants|
|[RTP Payload Format For AV1 (v1.0)](https://aomediacodec.github.io/av1-rtp-spec/)|payload formats / AV1|
|[RFC9628, RTP Payload Format for VP9 Video](https://datatracker.ietf.org/doc/html/rfc9628)|payload formats / VP9|
|[RFC7741, RTP Payload Format for VP8 Video](https://datatracker.ietf.org/doc/html/rfc7741)|payload formats / VP8|
|[RFC7798, RTP Payload Format for High Efficiency Video Coding (HEVC)](https://datatracker.ietf.org/doc/html/rfc7798)|payload formats / H265|
|[RFC6184, RTP Payload Format for H.264 Video](https://datatracker.ietf.org/doc/html/rfc6184)|payload formats / H264|
|[RFC3640, RTP Payload Format for Transport of MPEG-4 Elementary Streams](https://datatracker.ietf.org/doc/html/rfc3640)|payload formats / MPEG-4 audio, MPEG-4 video|
|[RFC2250, RTP Payload Format for MPEG1/MPEG2 Video](https://datatracker.ietf.org/doc/html/rfc2250)|payload formats / MPEG-1/2 video, MPEG-1/2 audio, MPEG-TS|
|[RFC2435, RTP Payload Format for JPEG-compressed Video](https://datatracker.ietf.org/doc/html/rfc2435)|payload formats / M-JPEG|
|[RFC7587, RTP Payload Format for the Opus Speech and Audio Codec](https://datatracker.ietf.org/doc/html/rfc7587)|payload formats / Opus|
|[Multiopus in libwebrtc](https://webrtc-review.googlesource.com/c/src/+/129768)|payload formats / Opus|
|[RFC5215, RTP Payload Format for Vorbis Encoded Audio](https://datatracker.ietf.org/doc/html/rfc5215)|payload formats / Vorbis|
|[RFC4184, RTP Payload Format for AC-3 Audio](https://datatracker.ietf.org/doc/html/rfc4184)|payload formats / AC-3|
|[RFC6416, RTP Payload Format for MPEG-4 Audio/Visual Streams](https://datatracker.ietf.org/doc/html/rfc6416)|payload formats / MPEG-4 audio LATM|
|[RFC5574, RTP Payload Format for the Speex Codec](https://datatracker.ietf.org/doc/html/rfc5574)|payload formats / Speex|
|[RFC3551, RTP Profile for Audio and Video Conferences with Minimal Control](https://datatracker.ietf.org/doc/html/rfc3551)|payload formats / G726, G722, G711, LPCM|
|[RFC3190, RTP Payload Format for 12-bit DAT Audio and 20- and 24-bit Linear Sampled Audio](https://datatracker.ietf.org/doc/html/rfc3190)|payload formats / LPCM|
|[RFC6597, RTP Payload Format for Society of Motion Picture and Television Engineers (SMPTE) ST 336 Encoded Data](https://datatracker.ietf.org/doc/html/rfc6597)|payload formats / KLV|
|[Codec specifications](https://github.com/bluenviron/mediacommon#specifications)|codecs|
|[Golang project layout](https://github.com/golang-standards/project-layout)|project layout|

## Related projects

* [MediaMTX](https://github.com/bluenviron/mediamtx)
* [gohlslib](https://github.com/bluenviron/gohlslib)
* [gortmplib](https://github.com/bluenviron/gortmplib)
* [mediacommon](https://github.com/bluenviron/mediacommon)
* [pion/sdp (SDP library used internally)](https://github.com/pion/sdp)
* [pion/rtp (RTP library used internally)](https://github.com/pion/rtp)
* [pion/rtcp (RTCP library used internally)](https://github.com/pion/rtcp)
* [pion/srtp (SRTP library used internally)](https://github.com/pion/srtp)


gortsplib

[![GoReportCard](http://goreportcard.com/badge/github.com/asticode/go-astiav)](http://goreportcard.com/report/github.com/asticode/go-astiav)
[![GoDoc](https://godoc.org/github.com/asticode/go-astiav?status.svg)](https://godoc.org/github.com/asticode/go-astiav)
[![Test](https://github.com/asticode/go-astiav/actions/workflows/test.yml/badge.svg)](https://github.com/asticode/go-astiav/actions/workflows/test.yml)
[![Coveralls](https://coveralls.io/repos/github/asticode/go-astiav/badge.svg?branch=master)](https://coveralls.io/github/asticode/go-astiav)

`astiav` is a Golang library providing C bindings for [ffmpeg](https://github.com/FFmpeg/FFmpeg)

It's only compatible with `ffmpeg` `n8.0`.

Its main goals are to:

- [x] provide a better GO idiomatic API
    - standard error pattern
    - typed constants and flags
    - struct-based functions
    - ...
- [x] provide the GO version of [ffmpeg examples](https://github.com/FFmpeg/FFmpeg/tree/n8.0/doc/examples)
- [x] be fully tested

:warning: breaking changes will be introduced in `go-astiav` **without** using the `v2` golang pattern. You can see the list of breaking changes [here](BREAKING_CHANGES.md).

# Examples

Examples are located in the [examples](examples) directory and mirror as much as possible the [ffmpeg examples](https://github.com/FFmpeg/FFmpeg/tree/n8.0/doc/examples).

|name|astiav|ffmpeg|
|---|---|---|
|BitStream Filtering|[see](examples/bit_stream_filtering/main.go)|X
|Custom IO Demuxing|[see](examples/custom_io_demuxing/main.go)|[see](https://github.com/FFmpeg/FFmpeg/blob/n8.0/doc/examples/avio_read_callback.c)
|Custom IO Muxing|[see](examples/custom_io_muxing/main.go)|X
|Demuxing/Decoding|[see](examples/demuxing_decoding/main.go)|[see](https://github.com/FFmpeg/FFmpeg/blob/n8.0/doc/examples/demux_decode.c)
|Filtering|[see](examples/filtering/main.go)|[see](https://github.com/FFmpeg/FFmpeg/blob/n8.0/doc/examples/decode_filter_video.c)
|Frame data manipulation|[see](examples/frame_data_manipulation/main.go)|X
|Hardware Decoding/Filtering|[see](examples/hardware_decoding_filtering/main.go)|[see](https://github.com/FFmpeg/FFmpeg/blob/n8.0/doc/examples/hw_decode.c)
|Hardware Encoding|[see](examples/hardware_encoding/main.go)|[see](https://github.com/FFmpeg/FFmpeg/blob/n8.0/doc/examples/vaapi_encode.c)
|Remuxing|[see](examples/remuxing/main.go)|[see](https://github.com/FFmpeg/FFmpeg/blob/n8.0/doc/examples/remux.c)
|Resampling audio|[see](examples/resampling_audio/main.go)|[see](https://github.com/FFmpeg/FFmpeg/blob/n8.0/doc/examples/resample_audio.c)
|Scaling video|[see](examples/scaling_video/main.go)|[see](https://github.com/FFmpeg/FFmpeg/blob/n8.0/doc/examples/scale_video.c)
|Transcoding|[see](examples/transcoding/main.go)|[see](https://github.com/FFmpeg/FFmpeg/blob/n8.0/doc/examples/transcode.c)

*Tip: you can use the video sample located in the `testdata` directory for your tests*

# Patterns

*NB: errors are not checked below for readibility purposes, however you should!*

First off, all use cases are different and it's impossible to provide patterns that work in every situation. That's why `ffmpeg`'s doc or source code should be your ultimate source of truth regarding how to use this library. That's why all methods of this library have been documented with a link referencing the documentation of the C function they use.

However it's possible to give rules of thumb and patterns that fit most use cases and can kickstart most people. Here's a few of them:

## When to call `Alloc()`, `.Unref()` and `.Free()`

Let's take the `FormatContext.ReadFrame()` pattern as an example. The pattern is similar with frames.

```go
// You can allocate the packet once and reuse the same object in the for loop below
pkt := astiav.AllocPacket()

// However, once you're done using the packet, you need to make sure to free it
defer pkt.Free()

// Loop
for {
    // We'll use a closure to ease unreferencing the packet
    func() {
        // Read frame using the same packet every time
        formatContext.ReadFrame(pkt)

        // However make sure to unreference the packet once you're done with what 
        // have been "injected" by the .ReadFrame() method
        defer pkt.Unref()

        // Here you can do whatever you feel like with your packet
    }()
}
```

# Install ffmpeg from source

Check out the `ffmpeg` section in the [Devcontainer Dockerfile](.devcontainer/Dockerfile) to see how to install ffmpeg from source.

For your GO code to pick up `ffmpeg` dependency automatically, you'll need to update the following environment variables :

(don't forget to replace `{{ path to your ffmpeg directory }}` with the absolute path to your ffmpeg directory)

```sh
export CGO_CFLAGS="-I{{ path to your ffmpeg directory }}/include/",
export CGO_LDFLAGS="-L{{ path to your ffmpeg directory }}/lib/",
export PKG_CONFIG_PATH="{{ path to your ffmpeg directory }}/lib/pkgconfig",
```

## Building on Windows

Building on Windows requires msys2 / mingw64 gcc toolchain. Read the [Quickstart guide](https://www.msys2.org) to install Msys2.

Once complete run the Mingw64 shell from the installation folder, run the below commands:

```shell
# Update Packages
pacman -Syu
# Install Requirements to Build
pacman -S --noconfirm --needed git diffutils mingw-w64-x86_64-toolchain pkg-config make nasm
# Clone the repository using git
git clone https://github.com/asticode/go-astiav
cd go-astiav
```

Then once you clone this repository, follow along the build instructions above.

> **Notes:**
> For `pkg-config` use `pkgconfiglite` from choco.
> Remember to set `CGO` and `PKG_CONFIG` env vars properly to point to the folder where ffmpeg was built.

# Why astiav?

After maintaining for several years the most starred [fork](https://github.com/asticode/goav) of [goav](https://github.com/giorgisio/goav), I've decided to write from scratch my own C bindings to fix most of the problems I still encountered using `goav`.


go-astiav

Parser and generator for HLS (M3U8) playlists; kept up to date with the spec

# hls-m3u8 - HLS m3u8 playlist library

![Test](https://github.com/Eyevinn/hls-m3u8/workflows/Go/badge.svg)
[![Coverage Status](https://coveralls.io/repos/github/Eyevinn/hls-m3u8/badge.svg?branch=main)](https://coveralls.io/github/Eyevinn/hls-m3u8?branch=main)
[![GoDoc](https://godoc.org/github.com/Eyevinn/hls-m3u8?status.svg)](http://godoc.org/github.com/Eyevinn/hls-m3u8)
[![Go Report Card](https://goreportcard.com/badge/github.com/Eyevinn/hls-m3u8)](https://goreportcard.com/report/github.com/Eyevinn/hls-m3u8)
[![license](https://img.shields.io/github/license/Eyevinn/hls-m3u8.svg)](https://github.com/Eyevinn/hls-m3u8/blob/main/LICENSE)

hls-m3u8 implements parsing and generation of HLS m3u8 playlists.
HLS (HTTP Live Streaming) is an evolving protocol with multiple versions.
Versions 1-7 are described in [IETF RFC8216][rfc8216], but the protocol has continued
to evolve with new features and versions in a
series of [Internet Drafts rfc8216bis][rfc8216bis].

One of the major libraries in Go for parsing and generating HLS playlists,
aka m3u8 files, has been the Github project [grafov/m3u8][grafov].
However, the majority of that code was written up to version 5,
It was finally archived in Dec. 2024.

The goal of this library, `hls-m3u8`,  is to provide an up-to-date replacement and improvement of the [grafov/m3u8][grafov] library. The aim is to follow the HLS specification
as it evolves and add all new elements and do other updates in order that
all m3u8 documents (from version 3 and forward) can be parsed and generated.
There is typically a new draft every 6 months.
The current version (Jan 9 2026) is [rfc8216bis-19][rfc8216bis].
Its specification should be supported by this repo, but all parameter
values are not validated.

The HLS protocol has different versions, and there are rules for what minimal
version to signal depending on features being used. That mechanism is implemented
in the `CalcMinVersion()` method of the `Playlist` interface.

## Structure and design of the code

There are two types of m3u8 playlists: `Master` or `Multivariant` playlists, and `Media` playlists.
These are represented as two different structs, but they have a common interface `Playlist`.

There is a function `Decode`, that decodes and autodetects the type of playlist, by decoding
both in parallel, and stopping one, once the type is known.

For generating playlists, one starts by calling either `NewMasterPlaylist` or `NewMediaPlaylist`.
One can then `Set` or `Append` extra data. For example, one can `Append` a full media segment or
`AppendPartial` a partial segment to Low-Latency HLS media playlists.

For live media playlists with a fixed sliding window, one
can set a `winsize` and it will be used to always output
the latest segments.

For VOD or EVENT media playlists, the `winsize` should be 0.

For writing, there are `Encode` methods that return a `*bytes.Buffer`. This buffer serves as a cache.
It is also possible to call `EncodeWithSkip` to signal skipping of the first `n` segments.
The `String` method makes it easy to use the standard `fmt.Print` functions.

## Installation / Usage

This is a library that should be downloaded like other Go code.

To enable it in your Go project, run

```sh
go get github.com/Eyevinn/hls-m3u8/m3u8
```

To use the code add

```go
import github.com/Eyevinn/hls-m3u8/m3u8
```

to your source files.

### Examples

Testable examples can be found in m3u8/*_test.go files. For nicer browser formatting, see
[pkg.go.dev][m3u8-examples].

Sample playlists are provided in `m3u8/sample-playlists`.

In addition, there are some simple examples below (without error handling)

#### Create simple media playlist

This uses a sliding window of 3 segments and
maximum of 50 segments.

	p, _ := NewMediaPlaylist(3, 50)
	for i := 0; i < 5; i++ {
	  _ = p.Append(fmt.Sprintf("test%d.ts", i), 5.0, "")
	}
	fmt.Println(p)

We add 5 testX.ts segments to the playlist before encoding it to M3U8 format and converting to string.
Due to the sliding window, only the last three
segments will be included.

#### Parsing of a master playlist:

	f, _ := os.Open("sample-playlists/master.m3u8")
	p := NewMasterPlaylist()
	_ = p.DecodeFrom(bufio.NewReader(f), true /*strict*/)
	fmt.Printf("Playlist object: %+v\n", p)

Here the `strict` parameter is set to true. If false, the parser
allows more errors.

## Development

There are tests and sample-playlists available.
There is also a `Makefile` that runs test, checks coverage, and the license
of dependencies.

For tests, the [is][is] package is used. It outputs failing tests with
line numbers and colors, but colors do not work properly in VisualStudio Code.
To turn them off in VSC, add the following configuration:

```json
    "go.testEnvVars": {
        "NO_COLOR" : "YES"
    },
```

### pre-commit checks

To run checks before any commit is accepted, install [pre-commit][pre-commit] and then run

```sh
> pre-commit install
```

to set up the automatic tests.

## Compatibility with grafov/m3u8

This project tries to align to the archived library [grafov/m3u8][grafov] to make the transition from that library relatively simple.

The first release (v0.1.0), is essentially a cleaned
and slightly bug-fixed  version of [grafov/m3u8][grafov]

Replace `import github.com/grafov/m3u8` with
`import github.com/Eyevinn/hls-m3u8/m3u8` and you should
hopefully be fine to go.

Later versions have more changes and additions, so it is likely
that more changes are needed to legacy code.

See [CHANGELOG](CHANGELOG) for a list of changes.

## Contributing

See [CONTRIBUTING](CONTRIBUTING.md)

## License

This project is licensed under the BSD Clause 3 License, see [LICENSE](LICENSE)
to align with the included code from the [grafov/m3u8][grafov] project.

## Issues and Discussion

Use the [issues][issues] to file an issue. Questions and discussions belong to the
[discussions][discussions] part of the repo. For support questions, see below.

## Support

Join our [community on Slack](https://slack.streamingtech.se) where you can post any questions regarding any of Eyevinn's open source projects. Eyevinn's consulting business can also offer you:

- Further development of this component
- Customization and integration of this component into your platform
- Support and maintenance agreement

Contact [sales@eyevinn.se](mailto:sales@eyevinn.se) if you are interested.

# About Eyevinn Technology

[Eyevinn Technology](https://www.eyevinntechnology.se) is an independent consultant firm specialized in video and streaming. Independent in a way that we are not commercially tied to any platform or technology vendor. As our way to innovate and push the industry forward we develop proof-of-concepts and tools. The things we learn and the code we write we share with the industry in [blogs](https://dev.to/video) and by open sourcing the code we have written.

Want to know more about Eyevinn and how it is to work here. Contact us at work@eyevinn.se!

[rfc8216]: https://datatracker.ietf.org/doc/html/rfc8216
[rfc8216bis]: https://datatracker.ietf.org/doc/draft-pantos-hls-rfc8216bis/
[rfc8216bis-07]: https://datatracker.ietf.org/doc/html/draft-pantos-hls-rfc8216bis-07
[rfc8216bis-10]: https://datatracker.ietf.org/doc/html/draft-pantos-hls-rfc8216bis-10
[rfc8216bis-16]: https://datatracker.ietf.org/doc/html/draft-pantos-hls-rfc8216bis-16
[grafov]: https://github.com/grafov/m3u8
[issues]: https://github.com/Eyevinn/hls-m3u8/issues
[discussions]: https://github.com/Eyevinn/hls-m3u8/discussions
[is]: https://github.com/matryer/is
[m3u8-examples]: https://pkg.go.dev/github.com/Eyevinn/hls-m3u8/m3u8#pkg-examples

hls-m3u8

Zero-dependency library for parsing, filtering, transforming, and building HLS and DASH manifests

# manifestor

[![Go Reference](https://pkg.go.dev/badge/github.com/alanzng/manifestor.svg)](https://pkg.go.dev/github.com/alanzng/manifestor)
[![CI](https://github.com/alanzng/manifestor/actions/workflows/ci.yml/badge.svg)](https://github.com/alanzng/manifestor/actions/workflows/ci.yml)
[![Go Report Card](https://goreportcard.com/badge/github.com/alanzng/manifestor)](https://goreportcard.com/report/github.com/alanzng/manifestor)
[![Coverage](https://codecov.io/gh/alanzng/manifestor/branch/main/graph/badge.svg)](https://codecov.io/gh/alanzng/manifestor)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Parse, filter, build, and transform HLS & DASH manifests in Go. Zero dependencies. Ships as a library, HTTP proxy server, and CLI tool.

---

## Features

- **Parse** HLS Master Playlists (`.m3u8`) and DASH MPDs (`.mpd`) from string, file, or URL
- **Filter** variants/representations by codec, resolution, bandwidth, frame rate, audio language, MIME type
- **Transform** URIs — CDN rewrites, absolute URI resolution, auth token injection (variants, audio tracks, I-frame streams, and DASH `<BaseURL>` elements)
- **Inject** extra tracks — append subtitle tracks, alternate audio, or additional representations after filtering
- **Build** complete HLS or DASH manifests from scratch with a fluent builder API
- **Serve** as an HTTP proxy that filters manifests on the fly
- **CLI** tool for scripting and local use
- Zero non-stdlib dependencies
- Thread-safe — `Filter()` is safe for concurrent use
- HLS versions 3–7; DASH profiles `isoff-on-demand` and `isoff-live`

---

## Installation

### Library

```bash
go get github.com/alanzng/manifestor
```

### CLI

```bash
go install github.com/alanzng/manifestor/cmd/manifestor@latest
```

### Docker

```bash
docker pull ghcr.io/alanng/manifestor:latest
```

---

## Quick Start

### Filter an HLS manifest

```go
import (
    manifestor "github.com/alanzng/manifestor"
    "github.com/alanzng/manifestor/manifest"
)

filtered, err := manifest.Filter(content,
    manifest.WithCodec(manifestor.H264),
    manifest.WithMaxResolution(manifestor.Res1080p),
    manifest.WithMaxBandwidth(5_000_000),
    manifest.WithCDNBaseURL("https://cdn.example.com"),
)
```

### Filter from URL

```go
filtered, err := manifest.FilterFromURL("https://example.com/master.m3u8",
    manifest.WithCodec(manifestor.H264),
    manifest.WithAuthToken("token=abc123"),
)
```

### Real-world example — Vieon VOD pipeline

Take a Bento4-generated master playlist with mixed AVC1/HVC1 video and a single audio track, and produce a delivery manifest with H.265 only, max 720p, absolute CDN URLs, a dubbed audio track, and subtitles.

**HLS:**

```go
import (
    manifestor "github.com/alanzng/manifestor"
    "github.com/alanzng/manifestor/hls"
    "github.com/alanzng/manifestor/manifest"
)

const cdnBase = "https://vod-bp.vieon.vn/abc123/.../vod/2026/03/12/uuid/"
const dubbedBase = "https://vod-bp.vieon.vn/def456/.../vod/2026/03/24/uuid2/"

out, err := manifest.Filter(content,
    manifest.WithCodec(manifestor.H265),
    manifest.WithMaxResolution(manifestor.Res720p),
    manifest.WithAbsoluteURIs(cdnBase),
    manifest.WithHLSVariantSubtitleGroup("subs"),
    manifest.WithHLSInjectSubtitle(hls.SubtitleTrackParams{
        GroupID:  "subs",
        Name:     "Tiếng Việt",
        Language: "vi",
        URI:      "https://static.vieon.vn/subtitle/vi.m3u8",
        Default:  true,
    }),
    manifest.WithHLSInjectAudioTrack(hls.AudioTrackParams{
        GroupID:  "audio/mp4a",
        Name:     "Thuyết Minh",
        Language: "tm",
        URI:      dubbedBase + "audio-tg-mp4a.m3u8",
    }),
)
```

**DASH:**

```go
import (
    manifestor "github.com/alanzng/manifestor"
    "github.com/alanzng/manifestor/dash"
    "github.com/alanzng/manifestor/manifest"
)

out, err := manifest.Filter(content,
    manifest.WithCodec(manifestor.H265),
    manifest.WithMaxResolution(manifestor.Res720p),
    manifest.WithAbsoluteURIs(cdnBase),
    manifest.WithDASHInjectAdaptationSet(dash.AdaptationSetParams{
        MimeType: "audio/mp4",
        Lang:     "tm",
        Name:     "Thuyết Minh",
        Representations: []dash.RepresentationParams{
            {ID: "tm-audio", Bandwidth: 196728, Codecs: "mp4a.40.2",
                BaseURL: dubbedBase + "media-audio-tg-mp4a.mp4"},
        },
    }),
    manifest.WithDASHInjectAdaptationSet(dash.AdaptationSetParams{
        ContentType: "text",
        MimeType:    "text/vtt",
        Lang:        "vi",
        Roles:       []dash.Role{{SchemeIDURI: "urn:mpeg:dash:role:2011", Value: "subtitle"}},
        Representations: []dash.RepresentationParams{
            {ID: "subtitles/vi", Bandwidth: 16,
                BaseURL: "https://static.vieon.vn/subtitle/vi.vtt"},
        },
    }),
)
```

### Build an HLS Master Playlist

```go
import "github.com/alanzng/manifestor/hls"

b := hls.NewMasterBuilder()
b.SetVersion(6).
    AddAudioTrack(hls.AudioTrackParams{
        GroupID:    "audio-en",
        Name:       "English",
        Language:   "en",
        URI:        "https://cdn.example.com/audio/en/index.m3u8",
        Default:    true,
        AutoSelect: true,
    }).
    AddVariant(hls.VariantParams{
        URI:          "https://cdn.example.com/1080p/index.m3u8",
        Bandwidth:    5_000_000,
        Codecs:       "avc1.640028,mp4a.40.2",
        Width:        1920,
        Height:       1080,
        FrameRate:    29.97,
        AudioGroupID: "audio-en",
    }).
    AddVariant(hls.VariantParams{
        URI:          "https://cdn.example.com/720p/index.m3u8",
        Bandwidth:    2_800_000,
        Codecs:       "avc1.4d401f,mp4a.40.2",
        Width:        1280,
        Height:       720,
        FrameRate:    29.97,
        AudioGroupID: "audio-en",
    })

playlist, err := b.Build()
```

### Build a DASH MPD

```go
import "github.com/alanzng/manifestor/dash"

b := dash.NewMPDBuilder(dash.MPDConfig{
    Profile:       "isoff-on-demand",
    Duration:      "PT4M0.00S",
    MinBufferTime: "PT1.5S",
})
b.AddAdaptationSet(dash.AdaptationSetParams{
    MimeType: "video/mp4",
    SegmentTemplate: &dash.SegmentTemplateParams{
        Initialization: "$RepresentationID$/init.mp4",
        Media:          "$RepresentationID$/$Number$.m4s",
        Timescale:      90000,
        Duration:       270000,
    },
    Representations: []dash.RepresentationParams{
        {ID: "v1", Bandwidth: 5_000_000, Codecs: "avc1.640028", Width: 1920, Height: 1080},
        {ID: "v2", Bandwidth: 2_000_000, Codecs: "avc1.4d401f", Width: 1280, Height: 720},
    },
})
b.AddAdaptationSet(dash.AdaptationSetParams{
    MimeType: "audio/mp4",
    Lang:     "en",
    Name:     "English",
    Representations: []dash.RepresentationParams{
        {
            ID:        "a1",
            Bandwidth: 128000,
            Codecs:    "mp4a.40.2",
            BaseURL:   "https://cdn.example.com/audio-en.mp4",
            AudioChannelConfiguration: &dash.AudioChannelConfiguration{
                SchemeIDURI: "urn:mpeg:dash:23003:3:audio_channel_configuration:2011",
                Value:       "2",
            },
        },
    },
})

mpd, err := b.Build()
```

### HTTP Server

```bash
# Start the proxy server
manifestor serve --port 8080

# Filter a live manifest via HTTP
curl "http://localhost:8080/filter?url=https://example.com/master.m3u8&codec=h264&max_res=1920x1080"
```

### CLI

```bash
# Filter a local file
manifestor filter --input master.m3u8 --codec h264 --max-res 1920x1080

# Filter from URL and write to file
manifestor filter --url https://example.com/master.m3u8 --codec h264 --output filtered.m3u8

# Build from a JSON spec
manifestor build --format hls --variants spec.json --output master.m3u8
```

---

## API Reference

### Filter Options (unified — work on both HLS and DASH)

| Option | Description |
|---|---|
| `WithCodec(manifestor.Codec)` | Keep only **video** variants matching codec: `H264`, `H265`, `VP9`, `AV1`. Audio tracks are always preserved. Use `manifestor.ParseCodec(s)` for string input. |
| `WithMaxResolution(manifestor.Resolution)` | Exclude variants wider or taller than the resolution. Presets: `Res720p`, `Res1080p`, `Res4K`, etc. |
| `WithMinResolution(manifestor.Resolution)` | Exclude variants smaller than the resolution |
| `WithExactResolution(manifestor.Resolution)` | Keep only variants matching exactly |
| `WithMaxBandwidth(bps)` | Exclude variants above `bps` bits/s |
| `WithMinBandwidth(bps)` | Exclude variants below `bps` bits/s |
| `WithMaxFrameRate(fps)` | Exclude variants with frame rate above `fps` |
| `WithAudioLanguage(lang)` | Keep only audio tracks matching BCP-47 `lang` |
| `WithMimeType(manifestor.MimeType)` | Keep only representations matching MIME type (DASH only). Constants: `MimeVideoMP4`, `MimeAudioMP4`, `MimeTextVTT`, etc. |
| `WithCDNBaseURL(base)` | Rewrite all URIs to use `base` as CDN origin |
| `WithAbsoluteURIs(origin)` | Resolve relative URIs to absolute using `origin` |
| `WithAuthToken(token)` | Append `token=` query parameter to all URIs |

URI rewriting covers: HLS variant URIs, audio track URIs, I-frame stream URIs; DASH `<BaseURL>` elements.

### HLS-only filter options

| Option | Description |
|---|---|
| `WithHLSInjectVariant(p)` | Append a variant stream after filtering |
| `WithHLSInjectAudioTrack(p)` | Append an `#EXT-X-MEDIA AUDIO` track after filtering |
| `WithHLSInjectSubtitle(p)` | Append an `#EXT-X-MEDIA SUBTITLES` track after filtering |
| `WithHLSVariantSubtitleGroup(id)` | Set `SUBTITLES="id"` on all surviving variants |

### DASH-only filter options

| Option | Description |
|---|---|
| `WithDASHInjectAdaptationSet(p)` | Append an `<AdaptationSet>` to every Period after filtering |

### Custom callbacks (package-level only)

| Option | Package | Description |
|---|---|---|
| `WithCustomFilter(fn)` | `hls`, `dash` | User-defined filter: `func(*Variant) bool` / `func(*Representation) bool` |
| `WithCustomTransformer(fn)` | `hls`, `dash` | User-defined transformer applied to each surviving variant/representation |

### Errors

| Error | Condition |
|---|---|
| `ErrInvalidFormat` | Content is neither valid HLS nor DASH |
| `ErrNotMasterPlaylist` | HLS content is a media playlist, not a master |
| `ErrNoVariantsRemain` | All variants were filtered out |
| `ErrFetchFailed` | Upstream URL fetch failed |
| `ErrParseFailure` | Manifest could not be parsed |
| `ErrEmptyVariantList` | `Build()` called with no variants added |
| `ErrInvalidVariant` | A variant is missing `URI` or `Bandwidth` |
| `ErrOrphanedGroupID` | `AudioGroupID` references a non-existent `#EXT-X-MEDIA` group |
| `ErrInvalidLanguageTag` | DASH `lang` is not a valid BCP-47 tag |

---

## DASH Data Model

Key fields parsed and round-tripped through `Parse` → `Filter` → `Serialize`:

| Element | Fields |
|---|---|
| `<MPD>` | `Profile`, `Duration`, `MinBufferTime`, `MinUpdatePeriod` |
| `<AdaptationSet>` | `ID`, `ContentType`, `MimeType`, `Lang`, `Name` (label attr), `Roles`, `SegmentTemplate`, `SegmentBase` |
| `<Representation>` | `ID`, `Bandwidth`, `Codecs`, `Width`, `Height`, `FrameRate`, `MimeType`, `StartWithSAP`, `BaseURL`, `AudioChannelConfiguration` |
| `<Role>` | `SchemeIDURI`, `Value` |
| `<AudioChannelConfiguration>` | `SchemeIDURI`, `Value` |

---

## HTTP API

### `GET /filter`

Fetches and filters an upstream manifest.

| Parameter | Required | Description |
|---|---|---|
| `url` | yes | Upstream manifest URL |
| `codec` | no | `h264` \| `h265` \| `vp9` \| `av1` |
| `max_res` | no | e.g. `1920x1080` |
| `min_res` | no | e.g. `854x480` |
| `max_bw` | no | bits/s e.g. `5000000` |
| `min_bw` | no | bits/s e.g. `500000` |
| `fps` | no | max frame rate e.g. `30` |
| `cdn` | no | CDN base URL |
| `token` | no | Auth token string |
| `lang` | no | BCP-47 audio language |

**Responses:** `200 OK`, `400 Bad Request`, `422 Unprocessable Entity`, `502 Bad Gateway`

### `POST /build`

Builds a manifest from a JSON payload. See [HTTP API docs](docs/http-api.md) for full schema.

---

## Performance

| Operation | Target | Typical |
|---|---|---|
| Parse + filter + serialize 50 KB manifest | < 5 ms | ~1–2 ms |
| Build 100-variant manifest | < 2 ms | ~0.5 ms |

---

## Supported Manifest Sources

Tested against real-world output from:

- [Bento4](https://www.bento4.com/) `mp4-dash.py`
- [Shaka Packager](https://github.com/shaka-project/shaka-packager)
- AWS MediaConvert
- Azure Media Services
- Vieon VOD platform

---

## Who is using manifestor

<table>
    <thead>
        <tr>
            <th>Name</th>
            <th>Logo</th>
            <th>Website</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><strong>Vieon</strong></td>
            <td align="center">
                <picture>
                    <source media="(prefers-color-scheme: dark)" srcset="docs/images/vieon-logo-dark.svg" />
                    <img height="32px" src="docs/images/vieon-logo-light.svg" alt="Vieon" />
                </picture>
            </td>
            <td><a href="https://vieon.vn/">vieon.vn</a></td>
            <td>Vietnam's leading OTT streaming platform. Uses manifestor to filter and transform HLS &amp; DASH manifests for multi-codec VOD delivery (AVC1 + HVC1) with CDN rewriting and per-request auth tokens.</td>
        </tr>
    </tbody>
</table>

---

## Contributing

Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.

---

## License

MIT — see [LICENSE](LICENSE).


manifestor

Go bindings for libvlc 2.X/3.X/4.X (used by the VLC media player)

<h1 align="center">
  <div>
    <img src="https://raw.githubusercontent.com/adrg/adrg.github.io/master/assets/projects/libvlc-go/logo.svg" alt="libvlc-go logo"/>
  </div>
</h1>

<h3 align="center">Handcrafted Go bindings for libVLC and high-level media player interface</h3>

<p align="center">
    <a href="https://github.com/adrg/libvlc-go/actions/workflows/lint-v3.yml">
        <img alt="Build status" src="https://img.shields.io/github/actions/workflow/status/adrg/libvlc-go/lint-v3.yml">
    </a>
    <a href="https://pkg.go.dev/github.com/adrg/libvlc-go/v3">
        <img alt="pkg.go.dev documentation" src="https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white">
    </a>
    <a href="https://opensource.org/licenses/MIT" rel="nofollow">
        <img alt="MIT license" src="https://img.shields.io/github/license/adrg/libvlc-go"/>
    </a>
    <a href="https://github.com/avelino/awesome-go#video">
        <img alt="Awesome Go" src="https://awesome.re/mentioned-badge.svg"/>
    </a>
    <a href="https://ko-fi.com/T6T72WATK">
        <img alt="Buy me a coffee" src="https://img.shields.io/static/v1.svg?label=%20&message=Buy%20me%20a%20coffee&color=579fbf&logo=buy%20me%20a%20coffee&logoColor=white"/>
    </a>
    <br />
    <a href="https://goreportcard.com/report/github.com/adrg/libvlc-go">
        <img alt="Go report card" src="https://goreportcard.com/badge/github.com/adrg/libvlc-go" />
    </a>
    <a href="https://github.com/adrg/libvlc-go/graphs/contributors">
        <img alt="GitHub contributors" src="https://img.shields.io/github/contributors/adrg/libvlc-go" />
    </a>
    <a href="https://discord.gg/3h3K3JF">
        <img alt="Discord channel" src="https://img.shields.io/discord/716939396464508958?label=discord" />
    </a>
    <a href="https://github.com/adrg/libvlc-go/issues?q=is%3Aopen+is%3Aissue">
        <img alt="GitHub open issues" src="https://img.shields.io/github/issues-raw/adrg/libvlc-go">
    </a>
    <a href="https://github.com/adrg/libvlc-go/issues?q=is%3Aissue+is%3Aclosed">
        <img alt="GitHub closed issues" src="https://img.shields.io/github/issues-closed-raw/adrg/libvlc-go" />
    </a>
</p>

The package can be useful for adding multimedia capabilities to applications
through the provided player interfaces. It relies on Go modules in order to
mirror each supported major version of [libVLC](https://www.videolan.org/vlc/libvlc.html).

Documentation for v3, which implements bindings for libVLC 3.X, can be found on [pkg.go.dev](https://pkg.go.dev/github.com/adrg/libvlc-go/v3).  
Documentation for v2, which implements bindings for libVLC 2.X, can be found on [pkg.go.dev](https://pkg.go.dev/github.com/adrg/libvlc-go/v2).

<p align="center">
    <a href="https://github.com/adrg/libvlc-go-examples/tree/master/v3/gtk3_player">
      <img align="center" width="49%" alt="libvlc-go media player" src="https://raw.githubusercontent.com/adrg/adrg.github.io/master/assets/projects/libvlc-go/gtk3-media-player-example/libvlc-gtk3-media-player.jpg">
    </a>
    <a href="https://github.com/adrg/libvlc-go-examples/tree/master/v3/gtk3_screen_recorder">
      <img align="center" width="49%" alt="libvlc-go screen recorder" src="https://raw.githubusercontent.com/adrg/adrg.github.io/master/assets/projects/libvlc-go/gtk3-screen-recorder-example/libvlc-gtk3-screen-recorder.jpg">
    </a>
    <a href="https://github.com/adrg/libvlc-go-examples/tree/master/v3/gtk3_equalizer">
      <img align="center" width="49%" alt="libvlc-go equalizer" src="https://raw.githubusercontent.com/adrg/adrg.github.io/master/assets/projects/libvlc-go/gtk3-equalizer-example/libvlc-gtk3-equalizer.jpg">
    </a>
    <a href="https://github.com/adrg/libvlc-go-examples/tree/master/v3/gtk3_media_discovery">
      <img align="center" width="49%" alt="libvlc-go media discovery" src="https://raw.githubusercontent.com/adrg/adrg.github.io/master/assets/projects/libvlc-go/gtk3-media-discovery-example/libvlc-gtk3-media-discovery.jpg">
    </a>
</p>

Example applications:

* [GUI media player](https://github.com/adrg/libvlc-go-examples/tree/master/v3/gtk3_player)
* [GUI screen recorder](https://github.com/adrg/libvlc-go-examples/tree/master/v3/gtk3_screen_recorder)
* [GUI equalizer](https://github.com/adrg/libvlc-go-examples/tree/master/v3/gtk3_equalizer)
* [GUI media discovery](https://github.com/adrg/libvlc-go-examples/tree/master/v3/gtk3_media_discovery)

## Prerequisites

The libVLC development files are required. Instructions for installing the
VLC SDK on multiple operating systems can be found on the wiki pages of this project.

- [Install on Linux](https://github.com/adrg/libvlc-go/wiki/Install-on-Linux)
- [Install on Windows](https://github.com/adrg/libvlc-go/wiki/Install-on-Windows)
- [Install on macOS](https://github.com/adrg/libvlc-go/wiki/Install-on-macOS)

## Installation

In order to support multiple versions of libVLC, the package contains a Go
module for each major version of the API. Choose an installation option
depending on the version of libVLC you want to use.

**libVLC v3.X**

```bash
go get github.com/adrg/libvlc-go/v3
```

**libVLC v2.X**

```bash
go get github.com/adrg/libvlc-go/v2

# Build for libVLC < v2.2.0
go build -tags legacy
```

All versions above also work for projects which are not using Go modules.
However, consider switching to modules.

## Examples

* [GTK 3 media player](https://github.com/adrg/libvlc-go-examples/tree/master/v3/gtk3_player) (using [gotk3](https://github.com/gotk3/gotk3))
* [GTK 3 screen recorder](https://github.com/adrg/libvlc-go-examples/tree/master/v3/gtk3_screen_recorder) (using [gotk3](https://github.com/gotk3/gotk3))
* [GTK 3 media discovery](https://github.com/adrg/libvlc-go-examples/tree/master/v3/gtk3_media_discovery) (using [gotk3](https://github.com/gotk3/gotk3))
* [GTK 3 equalizer](https://github.com/adrg/libvlc-go-examples/tree/master/v3/gtk3_equalizer) (using [gotk3](https://github.com/gotk3/gotk3))
* [GTK 2 media player](https://github.com/adrg/libvlc-go-examples/tree/master/v3/gtk2_player) (using [go-gtk](https://github.com/mattn/go-gtk))
* [GTK 2 screen recorder](https://github.com/adrg/libvlc-go-examples/tree/master/v3/gtk2_screen_recorder) (using [go-gtk](https://github.com/mattn/go-gtk))
* [Basic player usage](https://github.com/adrg/libvlc-go-examples/blob/master/v3/player/player.go)
* [Basic list player usage](https://github.com/adrg/libvlc-go-examples/tree/master/v3/list_player/list_player.go)
* [Handling events](https://github.com/adrg/libvlc-go-examples/tree/master/v3/event_handling/event_handling.go)
* [Retrieve media tracks](https://github.com/adrg/libvlc-go-examples/blob/master/v3/media_tracks/media_tracks.go)
* [Retrieve media information](https://github.com/adrg/libvlc-go-examples/blob/master/v3/media_information/media_information.go)
* [Display screen as player media](https://github.com/adrg/libvlc-go-examples/blob/master/v3/display_screen_media/display_screen_media.go)
* [Stream media to Chromecast](https://github.com/adrg/libvlc-go-examples/blob/master/v3/chromecast_streaming/chromecast_streaming.go)
* [Player equalizer usage](https://github.com/adrg/libvlc-go-examples/blob/master/v3/equalizer/equalizer.go)

Examples for all supported API versions can be found at https://github.com/adrg/libvlc-go-examples.

## Usage

```go
package main

import (
    "log"

    vlc "github.com/adrg/libvlc-go/v3"
)

func main() {
    // Initialize libVLC. Additional command line arguments can be passed in
    // to libVLC by specifying them in the Init function.
    if err := vlc.Init("--no-video", "--quiet"); err != nil {
        log.Fatal(err)
    }
    defer vlc.Release()

    // Create a new player.
    player, err := vlc.NewPlayer()
    if err != nil {
        log.Fatal(err)
    }
    defer func() {
        player.Stop()
        player.Release()
    }()

    // Add a media file from path or from URL.
    // Set player media from path:
    // media, err := player.LoadMediaFromPath("localpath/test.mp4")
    // Set player media from URL:
    media, err := player.LoadMediaFromURL("http://stream-uk1.radioparadise.com/mp3-32")
    if err != nil {
        log.Fatal(err)
    }
    defer media.Release()

    // Retrieve player event manager.
    manager, err := player.EventManager()
    if err != nil {
        log.Fatal(err)
    }

    // Register the media end reached event with the event manager.
    quit := make(chan struct{})
    eventCallback := func(event vlc.Event, userData interface{}) {
        close(quit)
    }

    eventID, err := manager.Attach(vlc.MediaPlayerEndReached, eventCallback, nil)
    if err != nil {
        log.Fatal(err)
    }
    defer manager.Detach(eventID)

    // Start playing the media.
    err = player.Play()
    if err != nil {
        log.Fatal(err)
    }

    <-quit
}
```

## In action

A list of projects using libvlc-go, in alphabetical order. If you want to
showcase your project in this section, please create a pull request with it.

- [Alio](https://github.com/fenimore/alio) - Command-line music player with Emacs style key bindings.
- [Tripbot](https://github.com/adanalife/tripbot) - An ongoing 24/7 slow-TV art project.

## Stargazers over time

[![Stargazers over time](https://starchart.cc/adrg/libvlc-go.svg)](https://starchart.cc/adrg/libvlc-go)

## Contributing

Contributions in the form of pull requests, issues or just general feedback,
are always welcome.  
See [CONTRIBUTING.MD](CONTRIBUTING.md).

**Contributors**:
[adrg](https://github.com/adrg),
[fenimore](https://github.com/fenimore),
[tarrsalah](https://github.com/tarrsalah),
[danielpellon](https://github.com/danielpellon),
[patknight](https://github.com/patknight),
[sndnvaps](https://github.com/sndnvaps),
[karlpip](https://github.com/karlpip).

## Discord server

libvlc-go is part of the libVLC Discord Community [server](https://discord.gg/3h3K3JF). Feel free to come say hello!

## References

For more information see the
[libVLC](https://www.videolan.org/developers/vlc/doc/doxygen/html/group__libvlc.html) documentation.

## License

Copyright (c) 2018 Adrian-George Bostan.

This project is licensed under the [MIT license](https://opensource.org/licenses/MIT).
See [LICENSE](LICENSE) for more details.


libvlc-go

Library and tools for working with MP4 files containing video, audio, subtitles, or metadata

mp4ff

Video capture library for Linux, written in Go

### Go FFmpeg Bindings 

#### Installation
##### Prerequisites
Current master branch supports all major Go versions, starting from 1.6.   

##### Build/install FFmpeg
build lastest version of ffmpeg, obtained from [https://github.com/FFmpeg/FFmpeg](https://github.com/FFmpeg/FFmpeg)  
There is one required option, which is disabled by default, you should turn on: `--enable-shared`  

E.g.:

```sh
./configure --prefix=/usr/local/ffmpeg --enable-shared
make
make install
```

Add pkgconfig path:

```sh
export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:/usr/local/ffmpeg/lib/pkgconfig/
```

Ensure, that `PKG_CONFIG_PATH` contains path to ffmpeg's pkgconfig folder.

```sh
# check it by running
pkg-config --libs libavformat
```

It should print valid path to the avformat library.  

Now, just run

```sh
go get github.com/3d0c/gmf
```

##### Other methods
This package uses pkg-config way to obtain flags, includes and libraries path, so if you have ffmpeg installed, just ensure, that your installation has them (pkgconfig/ folder with proper `pc` files).

#### Docker containers
Thanks to [@ergoz](https://github.com/ergoz) you can try a docker container [riftbit/ffalpine](https://hub.docker.com/r/riftbit/ffalpine)

Thanks to [@denismakogon](https://github.com/denismakogon) there is one more project, worth to mention
[https://github.com/denismakogon/ffmpeg-debian](https://github.com/denismakogon/ffmpeg-debian)

#### Usage
Please see [examples](examples/).

#### Support and Contribution
If something doesn't work, just fix it. Do not hesitate to pull request.

#### Credits
I borrowed the name from project, abandoned on code.google.com/p/gmf. Original code is available here in intitial commit from 03 Apr 2013.


Manipulate subtitles in GO (.srt, .stl, .ttml, .webvtt, .ssa/.ass, teletext, .smi, etc.)

[![GoReportCard](http://goreportcard.com/badge/github.com/asticode/go-astisub)](http://goreportcard.com/report/github.com/asticode/go-astisub)
[![GoDoc](https://godoc.org/github.com/asticode/go-astisub?status.svg)](https://godoc.org/github.com/asticode/go-astisub)
[![Test](https://github.com/asticode/go-astisub/actions/workflows/test.yml/badge.svg)](https://github.com/asticode/go-astisub/actions/workflows/test.yml)
[![Coveralls](https://coveralls.io/repos/github/asticode/go-astisub/badge.svg?branch=master)](https://coveralls.io/github/asticode/go-astisub)

This is a Golang library to manipulate subtitles. 

It allows you to manipulate `srt`, `stl`, `ttml`, `ssa/ass`, `webvtt` and `teletext` files for now.

Available operations are `parsing`, `writing`, `applying linear correction`, `syncing`, `fragmenting`, `unfragmenting`, `merging` and `optimizing`.

# Installation

To install the library:

    go get github.com/asticode/go-astisub

To install the CLI:

    go install github.com/asticode/go-astisub/cmd/astisub        

# Using the library in your code

WARNING: the code below doesn't handle errors for readibility purposes. However you SHOULD!

```go
// Open subtitles
s1, _ := astisub.OpenFile("/path/to/example.ttml")
s2, _ := astisub.ReadFromSRT(bytes.NewReader([]byte("1\n00:01:00.000 --> 00:02:00.000\nCredits")))

// Add a duration to every subtitles (syncing)
s1.Add(-2*time.Second)

// Fragment the subtitles
s1.Fragment(2*time.Second)

// Merge subtitles
s1.Merge(s2)

// Optimize subtitles
s1.Optimize()

// Unfragment the subtitles
s1.Unfragment()

// Apply linear correction
s1.ApplyLinearCorrection(1*time.Second, 2*time.Second, 5*time.Second, 7*time.Second)

// Write subtitles
s1.Write("/path/to/example.srt")
var buf = &bytes.Buffer{}
s2.WriteToTTML(buf)
```

# Using the CLI

If **astisub** has been installed properly you can:

- convert any type of subtitle to any other type of subtitle:

        astisub convert -i example.srt -o example.ttml

- apply linear correction to any type of subtitle:

        astisub apply-linear-correction -i example.srt -a1 1s -d1 2s -a2 5s -d2 7s -o example.out.srt

- fragment any type of subtitle:

        astisub fragment -i example.srt -f 2s -o example.out.srt

- merge any type of subtitle into any other type of subtitle:

        astisub merge -i example.srt -i example.ttml -o example.out.srt

- optimize any type of subtitle:

        astisub optimize -i example.srt -o example.out.srt

- unfragment any type of subtitle:

        astisub unfragment -i example.srt -o example.out.srt

- sync any type of subtitle:

        astisub sync -i example.srt -s "-2s" -o example.out.srt

# Features and roadmap

- [x] parsing
- [x] writing
- [x] syncing
- [x] fragmenting/unfragmenting
- [x] merging
- [x] ordering
- [x] optimizing
- [x] linear correction
- [x] .srt
- [x] .ttml
- [x] .vtt
- [x] .stl
- [x] .ssa/.ass
- [x] .teletext
- [ ] .smi


go-astisub

Parser and generator library for MPEG-DASH manifest files

[![Build Status](https://github.com/unki2aut/go-mpd/actions/workflows/ci.yml/badge.svg)](https://github.com/unki2aut/go-mpd/actions/workflows/ci.yml) [![Go Coverage](https://github.com/unki2aut/go-mpd/wiki/coverage.svg)](https://raw.githack.com/wiki/unki2aut/go-mpd/coverage.html) [![Go Report Card](https://goreportcard.com/badge/github.com/unki2aut/go-mpd)](https://goreportcard.com/report/github.com/unki2aut/go-mpd) [![GoDoc](https://godoc.org/github.com/unki2aut/go-mpd?status.svg)](https://godoc.org/github.com/unki2aut/go-mpd)
# go-mpd 

Go library for parsing and generating MPEG-DASH Media Presentation Description (MPD) files.

This project is based on https://github.com/mc2soft/mpd.

## Usage

```go
package main

import (
	"fmt"
	"github.com/unki2aut/go-mpd"
)

func main() {
	mpd := new(mpd.MPD)
	mpd.Decode([]byte(`<MPD type="static" mediaPresentationDuration="PT3M30S">
  <Period>
    <AdaptationSet mimeType="video/mp4" codecs="avc1.42c00d">
      <SegmentTemplate media="../video/$RepresentationID$/dash/segment_$Number$.m4s" initialization="../video/$RepresentationID$/dash/init.mp4" duration="100000" startNumber="0" timescale="25000"/>
      <Representation id="180_250000" bandwidth="250000" width="320" height="180" frameRate="25"/>
      <Representation id="270_400000" bandwidth="400000" width="480" height="270" frameRate="25"/>
      <Representation id="360_800000" bandwidth="800000" width="640" height="360" frameRate="25"/>
      <Representation id="540_1200000" bandwidth="1200000" width="960" height="540" frameRate="25"/>
      <Representation id="720_2400000" bandwidth="2400000" width="1280" height="720" frameRate="25"/>
      <Representation id="1080_4800000" bandwidth="4800000" width="1920" height="1080" frameRate="25"/>
    </AdaptationSet>
    <AdaptationSet lang="en" mimeType="audio/mp4" codecs="mp4a.40.2" bitmovin:label="English stereo">
      <AudioChannelConfiguration schemeIdUri="urn:mpeg:dash:23003:3:audio_channel_configuration:2011" value="2"/>
      <SegmentTemplate media="../audio/$RepresentationID$/dash/segment_$Number$.m4s" initialization="../audio/$RepresentationID$/dash/init.mp4" duration="191472" startNumber="0" timescale="48000"/>
      <Representation id="1_stereo_128000" bandwidth="128000" audioSamplingRate="48000"/>
    </AdaptationSet>
  </Period>
</MPD>`))

	fmt.Println(mpd.MediaPresentationDuration)
}
```

## Related links
* https://en.wikipedia.org/wiki/Dynamic_Adaptive_Streaming_over_HTTP
* [ISO_IEC_23009-1_2014 Standard](http://standards.iso.org/ittf/PubliclyAvailableStandards/c065274_ISO_IEC_23009-1_2014.zip)

## MPD parsing/generation in other languages
* Javascript - https://github.com/videojs/mpd-parser
* Python - https://github.com/sangwonl/python-mpegdash
* Cpp - https://github.com/bitmovin/libdash
* Java - https://github.com/carlanton/mpd-tools


The Best Go Libraries For Video (12)