Interface: LoadPlaylistOptions
Defined in: packages/player/src/player.ts:718
Options for Player.loadPlaylist.
Extends
Properties
autoPlay?
readonly optional autoPlay?: boolean;
Defined in: packages/player/src/player.ts:714
Start playing immediately. Defaults to true.
Inherited from
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
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
shuffle?
readonly optional shuffle?: boolean;
Defined in: packages/player/src/player.ts:772
Shuffle the queue once it is built, before playback starts.
The whole list is shuffled (mpv's playlist-shuffle, issued after every
entry has been appended and before the jump), and playback begins at the
first entry of the shuffled order.
Remarks
Combining this with startIndex throws an invalid-state
PlayerError, because the two cannot both be honoured. mpv's
playlist_shuffle() permutes every entry — it does not pin the current one
or shuffle only an unplayed tail (common/playlist.c, mpv 0.35.1) — so
after the shuffle an index no longer identifies the source the caller
passed at that position. Silently reinterpreting startIndex as "position
3 of a random permutation" would be a coin flip dressed up as an API.
To get "shuffle, but start with this track", put that track first yourself and shuffle the rest, or load in order and call PlaylistApi.shuffle afterwards (which keeps the playing entry playing).
startIndex?
readonly optional startIndex?: number;
Defined in: packages/player/src/player.ts:750
Which entry to start on. Defaults to 0.
Mutually exclusive with shuffle — see there.
startPosition?
readonly optional startPosition?: number;
Defined in: packages/player/src/player.ts:744
Start position in seconds, applied to the entry at startIndex only — every other entry starts at its own beginning.
Remarks
This is what makes the session-restore call mean what it reads like:
await player.loadPlaylist(tracks, { startIndex: 5, startPosition: 120 })
// entry 5 resumes at 2:00; entries 0-4 and 6+ start at 0:00.
Until 0.1.0 this option was attached to every appended entry, so restoring
a session made the whole queue start two minutes in — silently, because
start is a per-file option and nothing reports it back. If you genuinely
want an offset on every entry (a queue of identically-structured files with
a fixed intro, say), pass it yourself through
SourceOptions.mpvOptions as { start: '120' }, which is applied to
each entry exactly as before.
Cannot be combined with shuffle, for the same reason
startIndex cannot: after mpv permutes the queue, no index — and
therefore no entry — is identifiable as the one the offset was meant for.
The combination throws an invalid-state PlayerError.