Configure Custom HTTP Headers in FFmpeg

This article provides a straightforward guide on how to configure custom HTTP headers in FFmpeg when ingesting remote files or streams. You will learn how to pass authentication tokens, user-agent strings, and other custom metadata to remote servers using FFmpeg’s command-line options.

To configure custom HTTP headers in FFmpeg, you must use the -headers protocol option. Because this option modifies how FFmpeg accesses the input stream, it must be placed before the input file option (-i) in your command line.

Basic Syntax for a Single Header

To send a single custom header, pass the header name and value as a string to the -headers option.

ffmpeg -headers "Authorization: Bearer YOUR_API_TOKEN" -i "https://example.com/secure/stream.m3u8" -c copy output.mp4

Configuring Multiple Headers

When you need to send multiple headers, they must be separated by a Carriage Return and Line Feed (CRLF) character sequence (\r\n).

In a standard Unix/Linux bash shell, you can format multiple headers using a dollar-quoted string ($'\r\n') to insert the line breaks correctly:

ffmpeg -headers "Authorization: Bearer YOUR_API_TOKEN"$'\r\n'"X-Custom-Header: CustomValue"$'\r\n' -i "https://example.com/secure/stream.m3u8" -c copy output.mp4

On Windows Command Prompt (cmd.exe), you can insert literal line breaks inside the quotes:

ffmpeg -headers "Authorization: Bearer YOUR_API_TOKEN
X-Custom-Header: CustomValue" -i "https://example.com/secure/stream.m3u8" -c copy output.mp4

Common Specific Header Options

While the generic -headers option works for any HTTP header, FFmpeg also provides dedicated shorthand options for some of the most common headers:

• User-Agent: Use the -user_agent option to identify your client.

  ffmpeg -user_agent "MyCustomPlayer/1.0" -i "https://example.com/stream.mp4" -c copy output.mp4

• Cookies: Use the -cookies option to pass session cookies.

  ffmpeg -cookies "session_id=abc123xyz;" -i "https://example.com/stream.mp4" -c copy output.mp4

Important Considerations

1. Placement: Always place the -headers, -user_agent, or -cookies options before the -i parameter. If placed after the input, FFmpeg will apply them to the output stream instead, which will result in an error or ignored options.
2. HTTPS Streams: These header options work seamlessly over both HTTP and HTTPS connections.
3. Redirects: FFmpeg will forward these custom headers if the remote server redirects the request to another URL, provided the redirect remains on the same domain.