Custom HTTP Headers for FFmpeg HLS PUT Uploads

This article explains how to configure and send custom HTTP headers when uploading HTTP Live Streaming (HLS) segments and playlists using the HTTP PUT method in FFmpeg. By leveraging specific command-line flags, you can easily pass authentication tokens, content types, or custom metadata to your destination ingest server.

To send custom HTTP headers during an HLS upload, you must use FFmpeg’s -headers option. Because HTTP headers require carriage return and line feed (\r\n) separators, the syntax must be formatted correctly so your shell passes the newlines to FFmpeg.

The FFmpeg Command Syntax

Here is the standard command structure for uploading HLS segments via HTTP PUT with custom headers:

ffmpeg -i input.mp4 \
  -c:v libx264 -c:a aac \
  -f hls \
  -hls_time 4 \
  -hls_list_size 5 \
  -method PUT \
  -headers $'Authorization: Bearer YOUR_TOKEN\r\nX-Custom-Header: MyValue\r\n' \
  -hls_segment_filename 'http://your-server.com/live/seg_%03d.ts' \
  http://your-server.com/live/playlist.m3u8

Key Parameters Explained

• -f hls: Specifies the HLS muxer.
• -method PUT: Instructs FFmpeg to use the HTTP PUT method instead of the default GET or POST for uploading the playlist and transport stream (.ts) segments.
• -headers: This flag contains the custom HTTP headers. Note the use of $'...' in Bash, which enables the interpretation of backslash-escaped characters like \r\n. Every header line—including the last one—must end with \r\n.
• -hls_segment_filename: The HTTP destination URL where the individual segment files will be uploaded.

Important Considerations

1. Single vs. Multiple Headers: If you only need to send a single header, you must still append \r\n to the end of the string (e.g., -headers $'Authorization: Bearer Token\r\n').
2. HTTP Server Configuration: Ensure your receiving web server is configured to accept PUT requests and is prepared to parse the custom headers you are sending.
3. Connection Reuse: For better upload performance, add -http_persistent 1 to your command. This keeps the TCP connection alive across multiple segment uploads, reducing latency.