Skip to main content

Interface: LoadOptions

Defined in: packages/player/src/player.ts:712

Options for Player.load.

Extends​

Extended by​

Properties​

autoPlay?​

readonly optional autoPlay?: boolean;

Defined in: packages/player/src/player.ts:714

Start playing immediately. Defaults to true.

headers?​

readonly optional headers?: Readonly<Record<string, string>>;

Defined in: packages/player/src/player.ts:697

HTTP request headers for this source only — the typed form of mpv's http-header-fields.

Example​

await player.load(`${server}/Audio/${id}/stream`, {
  headers: { Authorization: `MediaBrowser Token="${token}"` },
})

Throws​

PlayerErrorException with code invalid-state when a header name is empty, padded with whitespace, or contains :, CR, LF or NUL, or when a value contains CR, LF or NUL. mpv writes these lines into the request verbatim (stream/stream_lavf.c:218 joins each with \r\n), so those characters are request splitting, not a formatting preference.

Remarks​

Why this exists rather than "just use mpvOptions". The raw route was unsafe in exactly the case people reach for it: http-header-fields is itself a ,-separated list, and the file-option string it travels in is also ,-separated, so any header containing a comma (Accept: text/html, application/xml, a multi-valued Cache-Control, a cookie pair) used to corrupt the whole option list. This path escapes both layers — the list separator with mpv's backslash form, the option value with mpv's fixed-length %n% form — so a header value can contain anything except the characters above.

Interaction with PlayerOptions.userAgent. They are different mpv options (user-agent vs http-header-fields) and both are sent, so a per-source User-Agent header does not silently disappear — but it does take precedence, because FFmpeg only appends its own user_agent line if (!has_header(s->headers, "\r\nUser-Agent: ")) (libavformat/http.c, FFmpeg 8.1.2, the tree these binaries are built from). Set one or the other, not both.

Interaction with SourceResolver. Headers belong to the entry, not to the URL, and survive a rewrite: mpv applies per-file options in load_per_file_options() (player/loadfile.c:1707) and only then runs the on_load hook that rewrites stream-open-filename (loadfile.c:1725). So a resolver that swaps a logical URI for a signed CDN URL still sends the headers the queue entry carried. If your signed URL makes the header redundant, drop the header — nothing removes it for you.

What it does not do. These are HTTP(S) options. file://, and any protocol not served by libavformat's HTTP client, ignore them (mpv: "Unknown or misspelled options are silently ignored").

Inherited from​

SourceOptions.headers

mpvOptions?​

readonly optional mpvOptions?: Readonly<Record<string, string>>;

Defined in: packages/player/src/player.ts:708

Extra per-file mpv options, e.g. { 'audio-channels': 'stereo' }.

Values are escaped with mpv's own fixed-length quoting before they are joined into loadfile's option list, so a value may contain commas, colons, quotes and spaces. A key given here wins over the typed options above it: pass 'http-header-fields' yourself and headers is not emitted at all (and you own both layers of escaping); pass 'demuxer' and the .m3u8 guard steps aside.

Inherited from​

SourceOptions.mpvOptions

startPosition?​

readonly optional startPosition?: number;

Defined in: packages/player/src/player.ts:649

Start position in seconds (mpv's per-file start option).

On Player.loadPlaylist this applies to one entry — the one at startIndex — and not to the rest of the queue. See LoadPlaylistOptions.startPosition.

Inherited from​

SourceOptions.startPosition