github.com/zchee/hlstools

HTTP Live Streaming Tools

The HTTP Live Streaming (HLS) tools package installs command-line tools that are used for deployment and validation of HLS and Low-Latency HLS solutions.

What's in this package

• Media File Segmenter
• Media Subtitle Segmenter
• Media Stream Segmenter
• Variant Playlist Creator
• Media Stream Validator
• HLS Report
• ID3 Tag Generator
• Low-Latency HLS Golang script
• Low-Latency HLS PHP script
• TS Recompressor

Tool Overview

Media File Segmenter (mediafilesegmenter) divides a MOV, MP4, M4V, M4A, or MP3 file into media segments and creates an index file. It can also perform segment encryption. The index file and media segments can be deployed using almost any web server infrastructure for streaming to iOS, macOS, and tvOS. The Media File Segmenter only produces Video-on-Demand (VOD) streams.

Media Subtitle Segmenter (mediasubtitlesegmenter) converts subtitle tracks from a Quicktime file with tx3g-formatted subtitle tracks or SRT files into WebVTT and segments them for deployment using HLS. It will also take WebVTT files and segment them.

Media Stream Segmenter (mediastreamsegmenter) receives an MPEG-2 transport stream over a UDP network connection or from input stream on a local port and packages it for HLS. It writes a single live Media Playlist with its corresponding Media Segments (including Partial Segments in Low-Latency mode). It can also perform segment encryption. It writes its output to the local filesystem or a WebDAV endpoint. The live Media Playlist and Segments can be deployed using almost any web server infrastructure for streaming to iOS, macOS, and tvOS. The Media Stream Segmenter produces either live or VOD streams.

Variant Playlist Creator (variantplaylistcreator) works with Media File Segmenter to create a multivariant playlist from multiple VOD streams. Variant plists produced by Media File Segmenter, are passed to Variant Playlist Creator.

Media Stream Validator (mediastreamvalidator) simulates an HLS session and verifies that the index file and media segments conform to the HLS specification. It checks for several "best practices" to ensure reliable streaming. If any errors or problems are found, a detailed diagnostic report is displayed. Validation data can be written to a JSON file using --validation-data argument.

HLS Report (hlsreport) uses the JSON file generated by Media Stream Validator to create a report for the validated stream.

ID3 Tag Generator (id3taggenerator) creates ID3 tags to be used as metadata for the Media File Segmenter or sends them over the network to the Media Stream Segmenter.

TS Recompressor (tsrecompressor) produces and encodes up to four continuous audio and video streams, either programmatically (a bip-bop image derived from the system clock) or by capturing video from the system camera and microphone. It encodes the streams at different bit rates and multicasts them as MPEG-2 Transport Streams to local UDP ports.

Low-Latency HLS Golang script (ll-hls-origin-example.go) implements the HLS Origin API for a Low-Latency HLS media playlist.

Low-Latency HLS PHP script (lowLatencyHLS.php) implements the HLS Origin API for a Low-Latency HLS media playlist. It can be used as an alternative to the Low-Latency HLS Golang script.

System Requirements

The HLS tools package requires a Mac running macOS 15 or later. It is recommended to use more recent hardware when using the tsrecompressor tool for encoding multiple bit rates in real time. Audio/Video capture requires a camera and microphone that is supported by AVFoundation. Delivering Low-Latency HLS streams requires an HTTP/2 server that supports stream priority control. Most testing has been done using Apache. (See "Protocol Extension for Low-Latency HLS" for more details on required server configuration.) WebDAV must be configured to support cross-machine publishing with mediastreamsegmenter. For prototyping, it can be convenient to set up Apache on the same Mac as the other tools. The version of Apache that ships with macOS can be configured to support both HTTP/2 and PHP.

Installation Instructions

To install the HLS tools, double-click the HTTP Live Streaming Tools.pkg and follow the instructions. The installer will install these tools into:

/usr/local/bin/hlsreport
/usr/local/bin/id3taggenerator
/usr/local/bin/mediafilesegmenter
/usr/local/bin/mediastreamsegmenter
/usr/local/bin/mediastreamvalidator
/usr/local/bin/mediasubtitlesegmenter
/usr/local/bin/tsrecompressor
/usr/local/bin/variantplaylistcreator
/usr/local/share/hlstools/ll-hls-origin-example.go
/usr/local/share/hlstools/lowLatencyHLS.php

The installer will install README files into:

/usr/local/share/hlstools/readme.rtf
/usr/local/share/hlstools/README-LL.md
/usr/local/share/hlstools/README-GO.md

Notice: The installer will replace previously installed versions of the files.

Please refer to the man-pages for detailed instructions for how to use the tools. The man-pages are invoked from the command-line as follows:

man hlsreport
man id3taggenerator
man mediafilesegmenter
man mediastreamsegmenter
man mediastreamvalidator
man mediasubtitlesegmenter
man tsrecompressor
man variantplaylistcreator

Copyright © 2009-2024. Apple Inc. All rights reserved.

ll-hls-origin-example.go

Implements the Delivery Directives Interface for a Low-Latency HLS media playlist (as described in the Internet-Draft draft-pantos-hls-rfc8216bis). Can be used as an alternative to the lowLatencyHLS.php script.

Only tags relevant for Low Latency streaming are parsed. Other tags are ignored, but preserved by Decode() and Encode().

This code is meant as an example, and as such some Go best practices (i.e. using test, checking input format, and using libraries) have not been followed to make it easier to distribute and compile.

See https://datatracker.ietf.org/doc/html/draft-pantos-hls-rfc8216bis for the protocol specification

• Command line flags:

• -certdir string

  • Dir with server.crt, and server.key files

• -dir string

  • Root dir with hls files

• -http string

  • Listen address (default ":8443")

• prep:

  • install the latest version of go : brew install go
  • install fsnotify dependency: go get github.com/fsnotify/fsnotify

• run:

$ go run ll-hls-origin-example.go -certdir /usr/local/etc/certs -dir /usr/local/var/www -http :443

where

• /usr/local/etc/certs is the directory that has the server.crt and server.key certificate files
• /usr/local/var/www is the directory that has the variant subdirectories that mediastreamsegmenter is writing the Low Latency HLS segments and prog_index.m3u8 files to

One log line per request will be printed to stdout in the following format:

2020-01-23 09:09:58.300396 -0700 MST m=+542.326255627 10.123.4.123:59230 HTTP/2.0 GET  ll-hls-org.apple.com /media0/lowLatencyHLS?_HLS_msn=529&_HLS_part=2 966.872231ms 967.727263ms 2141 200 OK
^date^^^^^ ^time^^^^^^^^^^ ^timezone ^uptime^^^^^^^^^ ^^cient-ip:port^^^ ^proto^^ ^m^  ^host^^^^^^^^^^^^^^^ ^path^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^bd^^^^^^^^^ ^td^^^^^^^^^ ^sz^ ^stc^^

• date the date of the start of the request
• time the time of the start of the request
• timezone the timezone of the above date & time
• uptime the time in seconds since the start of the program
• client-ip:port client IP address and port
• proto the protocol used
• m the method used
• host the Host: header sent
• path the full path (including querystring) of the request
• bd the duration the server blocked to wait for the resource to become available
• td total duration from receiving the request to sending the last bit to the NIC
• sz size of object served
• stc status code and code string