Function: compileHttpHeaderFields()

function compileHttpHeaderFields(headers: HttpHeaders): string | undefined;

Defined in: packages/player/src/headers.ts:76

Compile a header map into one http-header-fields option value.

Parameters

Parameter	Type	Description
headers	HttpHeaders	The header map. An empty map compiles to undefined.

Returns

string | undefined

The option value, or undefined when there is nothing to send.

Throws

PlayerErrorException with code invalid-state when a header name is empty, is padded with whitespace, or contains :/CR/LF/NUL, or when a value contains CR/LF/NUL — see FORBIDDEN_IN_NAME. This is a request-splitting guard, not a style check: mpv concatenates these lines into the raw request.

Remarks

This is the inner of two escaping layers, and both are real.

--http-header-fields is a mpv string list option, separated by , with backslash escaping (mpv 0.41.0 mpv.rst, "String list and path list options": -set takes "a list of items (using the list separator, escaped with backslash)"). The parser is get_nextsep() in options/m_option.c:1380, which treats a , preceded by \ as literal and removes exactly that one backslash. So a header value containing a comma — Accept: text/html, application/xml, or a multi-valued Cache-Control — must be written \, here or it splits into two bogus header lines. That is the bug the audit found: the documented mpvOptions workaround for headers was unsafe in precisely the case people reach for it.

The outer layer is loadfile's own opt1=value1,opt2=value2 list, which is escaped separately with mpv's fixed-length form (see subparam.ts: escapeSubparam) by whoever assembles the file-option string. Keeping the two apart is deliberate: they are different parsers with different rules, and one function doing both would have to know which layer each backslash belonged to.