HLS Output¶
Starting with liquidsoap 1.4.1
, it is possible to send your streams as HLS output.
The main operator is output.file.hls
. Here’s an example using it, courtesy of srt2hls:
aac_lofi = %ffmpeg(format="mpegts",
codec="libfdk_aac",
channels=2,
ar=44100,
# Bitrate is define per channel in ffmpeg,
# so for 2 channels, 16k per channel gives
# an overall bitrate of 32k
b="16k",
afterburner=1,
profile="aac_he_v2")
aac_midfi = %ffmpeg(format="mpegts",
codec="libfdk_aac",
channels=2,
ar=44100,
b="48k",
afterburner=1,
profile="aac_low")
aac_hifi = %ffmpeg(format="mpegts",
codec="libfdk_aac",
channels=2,
ar=44100,
b="96k",
afterburner=1,
profile="aac_low")
streams_info = [("aac_lofi",(40000,"mp4a.40.29","ts")),
("aac_midfi",(110000,"mp4a.40.2","ts")),
("aac_hifi",(220000,"mp4a.40.2","ts"))]
streams = [("aac_lofi",aac_lofi),
("aac_midfi", aac_midfi),
("aac_hifi", aac_hifi)]
def segment_name(~position,~extname,stream_name) =
timestamp = int_of_float(gettimeofday())
duration = 2
"#{stream_name}_#{duration}_#{timestamp}_#{position}.#{extname}"
end
output.file.hls(playlist="live.m3u8",
segment_duration=2.0,
segments=5,
segments_overhead=5,
segment_name=segment_name,
streams_info=streams_info,
persist=true,
persist_at="/path/to/state.config",
"/path/to/hls/directory",
streams,
source)
Let’s see what’s important here:
streams
describes the encoded streams. It’s a list of:(stream_name, encoder)
.stream_name
is used to generate the corresponding media playlists. Encoders can be any encoder supported by liquidsoap. However, the HLS RFC limits the list of possible codecs tomp3
andaac
. Furthermore, for the best possible compatible, it is recommended to send data encapsulated in aMPEG-TS
stream. Currently, the only encoder capable of doing this in liquidsoap is%ffmpeg
.streams_info
describes additional data used to generated the HLS playlists according to section 4.3.4.2 of the RFC. It consists of a list of the form:(stream_name, (average_bandwidth, codec_name, segments_file_extension))
. This list is inffered for the following formats:%mp3
,%fdkaac
,%shine
. When using these formats, you do not need to pass an entry for the corresponding stream in this list. However, since we’re using the%ffmpeg
encoder to getMPEG-TS
encapsulated data, we need to add these info for each stream.persist
andpersist_at
are used to allow liquidsoap to restart while keeping the existing segments and playlists. When shutting down, liquidsoap stores the current configuration atpersist_at
and uses it to restart the HLS stream when restarting.segments
andsegments_overhead
are used to keep track of the generated segments. Each media playlist will contain a number of segments defined bysegments
and an extra set of segments, defined bysegments_overhead
, is kept past the playlist size for those listeners who are still listening on outdated segments.
There are more useful options, in particular on_file_change
, which can be used for instance to sync up your segments and playlists
to a distant storage and hosting service such as S3.
Liquidsoap also provides a output.harbor.hls
and output.harbor.hls.ssl
which allow to serve HLS streams directly from
liquidsoap. Their options should be the same as output.file.hls
, except for harbor-specifc options port
and path
. It is
not recommended for listener-facing setup but can be useful to sync up with a caching system such as cloudfront.