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, but the protocol has continued to evolve with new features and versions in a series of Internet Drafts rfc8216bis. The current version (Jan 3 2025) is rfc8216bis-16.
One of the major libraries in Go for parsing and generating HLS playlists, aka m3u8 files, has been the Github project grafov/m3u8. 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 m3u8 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 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 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.
This is a library that should be downloaded like other Go code.
To enable it in your Go project, run
go get github.com/Eyevinn/hls-m3u8/m3u8To use the code add
import github.com/Eyevinn/hls-m3u8/m3u8to your source files.
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 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:
"go.testEnvVars": {
"NO_COLOR" : "YES"
},To run checks before any commit is accepted, install [pre-commit][pre-commit] and then run
> pre-commit installto set up the automatic tests.
This project tries to align to the archived library grafov/m3u8 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
Replace import github.com/grafov/m3u8 with
import github.com/Eyevinn/hls-m3u8/m3u8 and you should
hopefully be fine to go.
Later versions do more changes and additions.
See CHANGELOG for a list of changes.
See CONTRIBUTING
This project is licensed under the BSD Clause 3 License, see LICENSE to align with the included code from the grafov/m3u8 project.
Use the issues to file an issue. Questions and discussions belong to the discussions part of the repo. For support questions, see below.
Join our community on Slack 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 if you are interested.
Eyevinn Technology 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 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!