Apple HTTP Live Streaming muxer that segments MPEG-TS according to the HTTP Live Streaming (HLS) specification.
It creates a playlist file, and one or more segment files. The output filename specifies the playlist filename.
By default, the muxer creates a file for each segment produced. These files have the same name as the playlist, followed by a sequential number and a .ts extension.
For example, to convert an input file with ffmpeg
:
ffmpeg -i in.nut out.m3u8
This example will produce the playlist, out.m3u8, and segment files: out0.ts, out1.ts, out2.ts, etc.
See also the segment muxer, which provides a more generic and flexible implementation of a segmenter, and can be used to perform HLS segmentation.
4.10.1 Options
This muxer supports the following options:
-
hls_time seconds
-
Set the target segment length in seconds. Default value is 2. Segment will be cut on the next key frame after this time has passed.
hls_list_size size
-
Set the maximum number of playlist entries. If set to 0 the list file will contain all the segments. Default value is 5.
hls_ts_options options_list
-
Set output format options using a :-separated list of key=value parameters. Values containing
:
special characters must be escaped.
hls_wrap wrap
-
Set the number after which the segment filename number (the number specified in each segment file) wraps. If set to 0 the number will be never wrapped. Default value is 0.
This option is useful to avoid to fill the disk with many segment files, and limits the maximum number of segment files written to disk to wrap.
start_number number
-
Start the playlist sequence number from number. Default value is 0.
hls_allow_cache allowcache
-
Explicitly set whether the client MAY (1) or MUST NOT (0) cache media segments.
hls_base_url baseurl
-
Append baseurl to every entry in the playlist. Useful to generate playlists with absolute paths.
Note that the playlist sequence number must be unique for each segment and it is not to be confused with the segment filename sequence number which can be cyclic, for example if thewrap option is specified.
hls_segment_filename filename
-
Set the segment filename. Unless
hls_flags single_file
is set, filename is used as a string format with the segment number:ffmpeg in.nut -hls_segment_filename 'file%03d.ts' out.m3u8
This example will produce the playlist, out.m3u8, and segment files: file000.ts, file001.ts, file002.ts, etc.
use_localtime
-
Use strftime on filename to expand the segment filename with localtime. The segment number (%d) is not available in this mode.
ffmpeg in.nut -use_localtime 1 -hls_segment_filename 'file-%Y%m%d-%s.ts' out.m3u8
This example will produce the playlist, out.m3u8, and segment files: file-20160215-1455569023.ts, file-20160215-1455569024.ts, etc.
use_localtime_mkdir
-
Used together with -use_localtime, it will create up to one subdirectory which is expanded in filename.
ffmpeg in.nut -use_localtime 1 -use_localtime_mkdir 1 -hls_segment_filename '%Y%m%d/file-%Y%m%d-%s.ts' out.m3u8
This example will create a directory 201560215 (if it does not exist), and then produce the playlist, out.m3u8, and segment files: 201560215/file-20160215-1455569023.ts,201560215/file-20160215-1455569024.ts, etc.
hls_key_info_file key_info_file
-
Use the information in key_info_file for segment encryption. The first line of key_info_file specifies the key URI written to the playlist. The key URL is used to access the encryption key during playback. The second line specifies the path to the key file used to obtain the key during the encryption process. The key file is read as a single packed array of 16 octets in binary format. The optional third line specifies the initialization vector (IV) as a hexadecimal string to be used instead of the segment sequence number (default) for encryption. Changes tokey_info_file will result in segment encryption with the new key/IV and an entry in the playlist for the new key URI/IV.
Key info file format:
key URI key file path IV (optional)
Example key URIs:
http://server/file.key /path/to/file.key file.key
Example key file paths:
file.key /path/to/file.key
Example IV:
0123456789ABCDEF0123456789ABCDEF
Key info file example:
http://server/file.key /path/to/file.key 0123456789ABCDEF0123456789ABCDEF
Example shell script:
#!/bin/sh BASE_URL=${1:-'.'} openssl rand 16 > file.key echo $BASE_URL/file.key > file.keyinfo echo file.key >> file.keyinfo echo $(openssl rand -hex 16) >> file.keyinfo ffmpeg -f lavfi -re -i testsrc -c:v h264 -hls_flags delete_segments \ -hls_key_info_file file.keyinfo out.m3u8
hls_flags single_file
-
If this flag is set, the muxer will store all segments in a single MPEG-TS file, and will use byte ranges in the playlist. HLS playlists generated with this way will have the version number 4. For example:
ffmpeg -i in.nut -hls_flags single_file out.m3u8
Will produce the playlist, out.m3u8, and a single segment file, out.ts.
hls_flags delete_segments
-
Segment files removed from the playlist are deleted after a period of time equal to the duration of the segment plus the duration of the playlist.
hls_flags round_durations
-
Round the duration info in the playlist file segment info to integer values, instead of using floating point.
hls_flags discont_starts
-
Add the
#EXT-X-DISCONTINUITY
tag to the playlist, before the first segment’s information.
hls_flags omit_endlist
-
Do not append the
EXT-X-ENDLIST
tag at the end of the playlist.
hls_flags split_by_time
-
Allow segments to start on frames other than keyframes. This improves behavior on some players when the time between keyframes is inconsistent, but may make things worse on others, and can cause some oddities during seeking. This flag should be used with the
hls_time
option.
hls_playlist_type event
-
Emit
#EXT-X-PLAYLIST-TYPE:EVENT
in the m3u8 header. Forces hls_list_size to 0; the playlist can only be appended to.
hls_playlist_type vod
-
Emit
#EXT-X-PLAYLIST-TYPE:VOD
in the m3u8 header. Forces hls_list_size to 0; the playlist must not change.
method
-
Use the given HTTP method to create the hls files.
ffmpeg -re -i in.ts -f hls -method PUT http://example.com/live/out.m3u8
This example will upload all the mpegts segment files to the HTTP server using the HTTP PUT method, and update the m3u8 files every
refresh
times using the same method. Note that the HTTP server must support the given method for uploading files.