Skip to content

Commit

Permalink
docs: v0.1.0 documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@tobbee
tobbee committed Dec 27, 2024
1 parent 3137148 commit bb2093a
Show file tree
Hide file tree
Showing 2 changed files with 59 additions and 36 deletions.
11 changes: 9 additions & 2 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,15 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## Unreleased
## [Unreleased]

- Nothing yet

## v0.1.0 - cleaned grafov/m3u8 code

### Changed

The following changes are wrt to initial copy of `grafov/m3u8` files:
The following changes are wrt to initial copy of [grafov/m3u8][grafov] files:

- code changes to pass linting including Example names
- made errors more consistent and more verbose
Expand All @@ -18,3 +22,6 @@ The following changes are wrt to initial copy of `grafov/m3u8` files:
### Added

- initial version of the repo

[Unreleased]: https://github.com/Eyevinn/mp4ff/compare/v0.1.0...HEAD
[grafov]: https://github.com/grafov/m3u8
84 changes: 50 additions & 34 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,74 +1,87 @@
<h1 align="center">
hls-m3u8 - HLS m3u8 playlist library
</h1>
# hls-m3u8 - HLS m3u8 playlist library

![Test](https://github.com/Eyevinn/hls-m3u8/workflows/Go/badge.svg)
![golangci-lint](https://github.com/Eyevinn/mp4ff/workflows/golangci-lint/badge.svg?branch=master)
[![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/master/LICENSE)

Module hls-m3u8 implements parsing and generation of HLS m3u8 playlists.
HLS is an evolving protocol with multiple versions.
Versions 1-7 are described in [IETF RFC8216][rfc8216], but it has continued
to evolve with new features and versions in Internet Drafts [rfc8216bis][rfc8216bis].
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].
The current version (Dec. 27 2024) is [rfc8216bis-16][rfc8216bis].

One of the major libraries in Go for parsing and generating HLS playlist,
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 7,and
the library has not been updated in a long time. It was finally
archived in Dec. 2024.
However, the majority of that code was written up to version 5, and
the library has hardly been updated in a long time. It was finally archived in Dec. 2024.

The goal of this library is to provide an up-to-date alternative
to the [m3u8][grafov] library. The aim is to follow the specification
as it involves and add all new elements and do other updates so that
all m3u8 documents from version 3 and forward can be parsed and generated.
The goal of this library, hls-m3u8, is to provide an up-to-date replacement and improvement
of the [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.

During this evolution, the top-level multi-variant playlist changed
name to `Multivariant Playlist` from `Master Playlist` in [rfc8216bis-10][rfc8216bis-10] in 2021. The new name is also what
is used in this library.

Another big change is the introduction of partial segments in
[rfc8216bis-7][rfc8216bis-7] in 2020.
## Installation / Usage

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

## Installation / Usage
To enable it in your Go project, run

<!--Add clear instructions on how to use the project here -->
```sh
go get github.com/Eyevinn/hls-m3u8/m3u8
```

## Development

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

### pre-commit checks

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

```sh
> pre-commit install --hook-type commit-msg
```

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.

<!--Add clear instructions on how to start development of the project here -->
As a first release (v0.1.0), the code should be a cleaned version of [grafov/m3u8][grafov],
but later versions will probably have some non-compatible changes.

## Compatibility with grafov/m3u8
Some notable changes in the HLS specification are:

* the introduction of Low-Latency HLS and
partial segments in [rfc8216bis-07][rfc8216bis-07]
* change of name of the top-level multi-variant playlist from `Master Playlist` to `Multivariant Playlist`[rfc8216bis-10][rfc8216bis-10]

This project tries to align to the archived library [grafov/m3u8][grafov] to make the transition
from that library relatively simple. In case there are new tags, attributes, or use cases
like LL-HLS, the same API may not apply. Following more recent versions of the specification
the top-level playlist is now called `MultiVariantPlaylist` instead of `MasterPlaylist`.
There area also plenty of new tags and use cases.

The aim is to provide upgrade instructions, when the library API changes.

## Contributing

See [CONTRIBUTING](CONTRIBUTING.md)

## License

This project is licensed under the MIT License, see [LICENSE](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
## Support

Join our [community on Slack](http://slack.streamingtech.se) where you can post any questions regarding any of our open source projects. Eyevinn's consulting business can also offer you:
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
Expand All @@ -86,4 +99,7 @@ Want to know more about Eyevinn and how it is to work here. Contact us at work@e
[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
[grafov]: https://github.com/grafov/m3u8
[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

0 comments on commit bb2093a

Please sign in to comment.