Configure FFmpeg HLS Master and Variant Playlist Names

This article explains how to customize the master playlist name and individual variant playlist names when encoding HTTP Live Streaming (HLS) video using FFmpeg. You will learn the specific command-line flags and naming patterns required to define custom names for multi-bitrate streams, enabling cleaner directory structures and better stream management for adaptive bitrate streaming.

To configure custom master and variant playlist names in FFmpeg, you must utilize the HLS muxer (-f hls) along with the -master_pl_name option and the -var_stream_map flag.

Setting the Master Playlist Name

The master playlist acts as the entry point for the media player, referencing the various individual variant playlists (different resolutions/bitrates). You can explicitly set the name of this file using the -master_pl_name option.

-master_pl_name master.m3u8

Setting Individual Variant Playlist Names

To name the individual variant playlists, you map your output streams using -var_stream_map and use the %v placeholder in the final output path.

By default, FFmpeg replaces %v with the numerical index of the variant (0, 1, 2, etc.). However, you can assign custom string names to these variants inside the -var_stream_map setting using the name: group option.

Complete FFmpeg Command Example

Here is a complete command that takes an input video, creates two variants (one high-definition and one low-definition), assigns custom names to the variant playlists, and generates a master playlist:

ffmpeg -i input.mp4 \
  -map 0:v -map 0:a -map 0:v -map 0:a \
  -b:v:0 3000k -b:a:0 128k \
  -b:v:1 1000k -b:a:1 96k \
  -f hls \
  -hls_time 6 \
  -hls_playlist_type vod \
  -master_pl_name master.m3u8 \
  -var_stream_map "v:0,a:0,name:hd v:1,a:1,name:sd" \
  -hls_segment_filename "variant_%v/file_%03d.ts" \
  "variant_%v/playlist.m3u8"

How the Parameters Work:

• -master_pl_name master.m3u8: Creates a master playlist named master.m3u8 in the execution directory.
• -var_stream_map "v:0,a:0,name:hd v:1,a:1,name:sd": Defines two variants. The first variant (video 0 and audio 0) is named hd. The second variant (video 1 and audio 1) is named sd.
• "variant_%v/playlist.m3u8": This is the output template for the variant playlists. FFmpeg replaces %v with the custom names defined in the stream map. This creates two individual playlist files:
  • variant_hd/playlist.m3u8
  • variant_sd/playlist.m3u8
• -hls_segment_filename "variant_%v/file_%03d.ts": Ensures that the individual video segment files (.ts files) are also organized into their respective custom-named folders.