Playlist API

Playlist management, track operations, autoplaylists, and helpers.

Targeting a playlist

Methods that act on a single playlist identify it by either playlist (its index) or playlistGuid. Pass only one of the two; passing both fails with INVALID_PARAMS.

• Index (playlist): Refers to whichever playlist occupies that position when the host handles the call. Once playlists are removed or reordered, the same index can refer to a different playlist, for example while a menu listing the playlists is still open.
• GUID (playlistGuid): Stays with its playlist. A call made with it reaches that playlist, or fails with NOT_FOUND if the playlist has been removed. Playlists with the same name have different GUIDs.

playlist.getAll, getActive, getPlaying, create, duplicate, and createAutoplaylist report each playlist's GUID as guid. Results that identify a playlist by index also carry its GUID as playlistGuid, and playlist:* events identify playlists by GUID; see each event's payload for the field name. library.addToPlaylist, queue.add, queue.addPaths, and artwork.getByPlaylistItem accept the same two keys, as does each entry of queue.setContents and queue.insertNext. playlist.reorderPlaylists takes the new order as GUIDs in newOrderGuids.

const res = await fb2k.invoke('playlist.getAll');
if (res.success === false) throw new Error(res.error);
const target = res.playlists.find((p) => p.name === 'Favorites');
if (target) {
    await fb2k.invoke('library.addToPlaylist', {
        paths: ['E:\\Music\\song.flac'],
        playlistGuid: target.guid,
    });
}

List management

playlist.getCount

Report how many playlists there are.

This method takes no parameters.

Returns

Field	Type	Description
count	integer	Number of playlists.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

const res = await fb2k.invoke('playlist.getCount');
if (res.success === false) throw new Error(res.error);
const { count } = res;

playlist.getAll

List every playlist in playlist order.

This method takes no parameters.

Returns

Field	Type	Description
playlists	PlaylistInfo[]	Every playlist, in playlist order.
playlists[].index	integer	Position in the playlist list, from 0.
playlists[].guid	string	Unique identifier of the playlist, formatted as {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}. Pass as playlistGuid to reliably target this playlist.
playlists[].name	string	Playlist name.
playlists[].trackCount	integer	Number of tracks.
playlists[].isActive	boolean	Whether this is the active playlist.
playlists[].isPlaying	boolean	Whether this is the playing playlist.
playlists[].isLocked	boolean	Whether the playlist carries a lock.
playlists[].isAutoplaylist	boolean	Whether the playlist is an autoplaylist, as playlist.isAutoplaylist reports it.
count	integer	Number of entries in playlists.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

Duration Field Omission

playlist.getAll does not return duration (avoids loading every track across every playlist). Use playlist.getActive or playlist.getPlaying when you need a single playlist duration.

Autoplaylist Flag

The isAutoplaylist field is inlined in playlist.getAll; you do not need per-playlist playlist.isAutoplaylist calls.

playlist.getActive

Describe the active playlist, the one the user is looking at. found is false when there is none, and the other fields are then absent.

This method takes no parameters.

Returns

Field	Type	Description
found	boolean	Whether there is an active playlist.
index	integer	Index of the active playlist.
guid	string	Unique identifier of the playlist, formatted as {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}. Pass as playlistGuid to reliably target this playlist.
name	string	Its name.
trackCount	integer	Number of tracks.
isActive	boolean	Always true here.
isPlaying	boolean	Whether it is also the playing playlist.
isLocked	boolean	Whether it carries a lock.
duration	number	Total length of its tracks in seconds; tracks of unknown length count as 0.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

playlist.setActive

Make a playlist the active one. An index past the last playlist fails with INVALID_INDEX.

Parameter	Type	Required	Description
playlist	integer	No	Index of the playlist to activate. Give this or playlistGuid; with neither the call fails with INVALID_PARAMS. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.

Returns

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

Unlike most playlist methods, playlist has no active-playlist fallback: omitting it fails with INVALID_PARAMS.

await fb2k.invoke('playlist.setActive', { playlist: 1 });

playlist.getPlaying

Describe the playing playlist, the one playback takes its next track from. found is false when there is none, and the other fields are then absent.

This method takes no parameters.

Returns

Field	Type	Description
found	boolean	Whether there is a playing playlist.
index	integer	Index of the playing playlist.
guid	string	Unique identifier of the playlist, formatted as {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}. Pass as playlistGuid to reliably target this playlist.
name	string	Its name.
trackCount	integer	Number of tracks.
isActive	boolean	Whether it is also the active playlist.
isPlaying	boolean	Always true here.
isLocked	boolean	Whether it carries a lock.
duration	number	Total length of its tracks in seconds; tracks of unknown length count as 0.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

playlist.create

Create an empty playlist. Fails with OPERATION_FAILED when foobar2000 refuses to create one.

Parameter	Type	Required	Description
name	string	No	Name of the new playlist. Default: "New Playlist".
position	integer	No	Where to insert it in the playlist list; omitted, at the end. At least 0.

Returns

Field	Type	Description
index	integer	Index of the new playlist.
guid	string	Unique identifier of the playlist, formatted as {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}. Pass as playlistGuid to reliably target this playlist.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

const result = await fb2k.invoke('playlist.create', { name: 'Rock Music' });

playlist.remove

Delete a playlist. Fails with LOCKED when a lock on the playlist refuses the removal, and with OPERATION_FAILED when foobar2000 refuses it otherwise.

Parameter	Type	Required	Description
playlist	integer	No	Index of the playlist to delete; omitted, the active playlist. An index past the last playlist fails with INVALID_INDEX; with this omitted and no active playlist the call fails with NO_ACTIVE_ITEM. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.

Returns

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

playlist.rename

Rename a playlist. Fails with LOCKED when a lock on the playlist refuses the new name, and with OPERATION_FAILED when foobar2000 refuses it otherwise.

Parameter	Type	Required	Description
playlist	integer	No	Index of the playlist to rename. An index past the last playlist fails with INVALID_INDEX. Give this or playlistGuid; with neither the call fails with INVALID_PARAMS. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.
name	string	Yes	New name.

Returns

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

As with playlist.setActive, playlist has no active-playlist fallback: omitting it fails with INVALID_PARAMS.

await fb2k.invoke('playlist.rename', { playlist: 0, name: 'My Favorites' });

playlist.clear

Remove every track from a playlist, saving an undo point first. A locked playlist fails with LOCKED before anything changes; tracks left behind afterwards fail with OPERATION_FAILED, the failure carrying the same fields as a success.

Parameter	Type	Required	Description
playlist	integer	No	Index of the playlist to empty; omitted, the active playlist. An index past the last playlist fails with INVALID_INDEX; with this omitted and no active playlist the call fails with NO_ACTIVE_ITEM. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.

Returns

Field	Type	Description
playlist	integer	Index of the playlist.
playlistGuid	string	Unique identifier of the playlist, formatted as {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}. Pass as playlistGuid to reliably target this playlist.
clearedCount	integer	Number of tracks it held before.
remainingCount	integer	Number of tracks left; 0 on success.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

playlist.duplicate

Copy a playlist, tracks included, into a new playlist placed right after it.

Parameter	Type	Required	Description
playlist	integer	No	Index of the playlist to copy; omitted, the active playlist. An index past the last playlist fails with INVALID_INDEX; with this omitted and no active playlist the call fails with NO_ACTIVE_ITEM. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.
name	string	No	Name of the copy; omitted or empty, the original name followed by (Copy).

Returns

Field	Type	Description
index	integer	Index of the copy.
sourcePlaylist	integer	Index of the playlist that was copied.
sourcePlaylistGuid	string	GUID of the playlist that was copied, as playlistGuid takes it.
newPlaylist	integer	Index of the copy; the same as index.
guid	string	GUID of the copy, as playlistGuid takes it.
name	string	Name of the copy.
trackCount	integer	Number of tracks copied.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

Track operations

playlist.getTrackCount

Report how many tracks a playlist holds. An index past the last playlist, a playlistGuid no playlist has, or no active playlist when both are omitted, reports 0 rather than failing.

Parameter	Type	Required	Description
playlist	integer	No	Index of the playlist; omitted, the active playlist. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist, used in place of an index. For read queries where a missing target returns an empty result instead of failing. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS.

Returns

Field	Type	Description
count	integer	Number of tracks.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

A zero count does not tell an empty playlist from one that does not exist.

playlist.getTracks

A page of a playlist's rows. Without fields each row is a whole playlist row with the play statistics foo_playcount provides; fields narrows every row to the named keys, from the list library.query takes, and always keeps index. A playlist index past the last one, a playlistGuid no playlist has, and no active playlist when both are omitted, answer an empty page.

Parameter	Type	Required	Description
playlist	integer	No	Playlist index; omitted, the active playlist. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist, used in place of an index. For read queries where a missing target returns an empty result instead of failing. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS.
start	integer	No	First row to return. At least 0. Default: 0.
count	integer	No	Most rows to return. At least 0. Default: 100.
formats	Record<string, string>	No	Extra columns, each a Title Formatting pattern under a name of your choosing; every row carries their values under formats, in projected rows too.
fields	string[]	No	Keys each row carries besides index; omitted, the whole row. The names are case-sensitive and are those library.query takes; an unknown name fails with INVALID_PARAMS and is listed in details.unknownFields. The optional albumId is omitted if no album identifier exists. Must not be empty.

Returns

Field	Type	Description
playlist	integer	The playlist read, as given or resolved. -1 when there is none to name: playlist was omitted and there is no active playlist, or no playlist has the playlistGuid. An index past the last playlist comes back as given.
playlistGuid	string	GUID of the playlist read, as playlistGuid takes it; absent when the playlist does not exist, so its absence is what tells a missing playlist from an empty one.
start	integer	The start applied.
count	integer	Rows returned.
total	integer	Rows in the playlist; 0 when it does not exist.
tracks	PlaylistTrackPartial[]	The rows from start: whole rows, or index plus the fields asked for.
tracks[].handle	string	Cross-endpoint unique track identifier: formatted as absolutePath, appended with |subsong:N when subsong is non-zero. The same track yields the same handle from every method. Differs from standard filesystem paths; endpoints document whether handle identifiers are accepted in place of paths.
tracks[].path	string	Path as foobar2000 stores it: file:// for a local file, file-relative:// for a path stored relative to the foobar2000 folder (a portable install), or a remote URL. No subsong suffix.
tracks[].absolutePath	string	Native filesystem path without the subsong suffix; the same as path for a remote URL.
tracks[].subsong	integer	Subsong identifier the decoder assigns inside the file, not necessarily a sequence number; 0 for a whole file and for a remote stream.
tracks[].title	string	First TITLE value; empty when untagged.
tracks[].artist	string	Every ARTIST value joined with ", "; empty when untagged.
tracks[].artists	string[]	Every ARTIST value in tag order; empty when untagged.
tracks[].album	string	First ALBUM value; empty when untagged.
tracks[].albumId	string	Opaque album identity when its original name or album artist contains invalid UTF-8. Use this instead of the display names to match an album row; absent for ordinary names.
tracks[].albumArtist	string	Every ALBUM ARTIST value joined with ", "; empty when untagged.
tracks[].albumArtists	string[]	All ALBUM ARTIST values in tag order (albumArtists.join(", ") equals albumArtist); empty array when untagged. In library.getAlbums, a track that has an album is filed under the name album and the album artist albumArtists[0] (falling back to artists[0], or "" when both are empty); those are the name and albumArtist of that album's row. When albumId is present, match by albumId instead of display names to avoid collision from character replacement.
tracks[].genre	string	Every GENRE value joined with ", "; empty when untagged.
tracks[].date	string	First DATE value as tagged, such as 2019 or 2019-05-01; empty when untagged.
tracks[].trackNumber	integer	TRACKNUMBER read as an integer; 0 when absent or not a number.
tracks[].discNumber	integer	DISCNUMBER read as an integer; 0 when absent or not a number.
tracks[].duration	number	Length in seconds; 0 when unknown.
tracks[].fileSize	integer	File size in bytes; -1 when unknown, as for a remote stream.
tracks[].bitrate	integer	Average bitrate in kbit/s; 0 when unknown.
tracks[].sampleRate	integer	Sample rate in Hz; 0 when unknown.
tracks[].channels	integer	Channel count; 0 when unknown.
tracks[].codec	string	Codec name as the decoder reports it, such as FLAC or MP3; empty when unknown.
tracks[].rating	integer	Rating value from 0 to 5. Prefers the %rating% statistic (foo_playcount) if within 1..5; otherwise falls back to the RATING tag clamped to 0..5; 0 if neither is present.
tracks[].index	integer	Row in the playlist, from 0.
tracks[].composer	string	Every COMPOSER value joined with ", "; empty when untagged.
tracks[].comment	string	First COMMENT value; empty when untagged.
tracks[].playCount	integer	%play_count% from foo_playcount; absent when it gives no number, and on rows of playlist.getSelectedTracks or of a fields request.
tracks[].firstPlayed	string	%first_played% as foo_playcount formats it; absent when empty, on rows of playlist.getSelectedTracks and on rows of a fields request.
tracks[].lastPlayed	string	%last_played% as foo_playcount formats it; absent when empty, on rows of playlist.getSelectedTracks and on rows of a fields request.
tracks[].added	string	%added% as foo_playcount formats it; absent when empty, on rows of playlist.getSelectedTracks and on rows of a fields request.
tracks[].formats	Record<string, string>	Named Title Formatting columns; present only when formats was requested.
contentVersion	string	Pages can be joined only when this matches; absent when the playlist does not exist.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

Multi-value tags in artist / albumArtist / genre / composer (only the fields this API actually returns) are joined with , in their original order, without de-duplication.

rating first reads %rating% and uses a value from 1 to 5. If that value is missing or outside this range, it reads the file's RATING tag and clamps it to 0-5; no available rating gives 0 (unrated). rating.get uses the same rule: storage is 'stats' for an accepted %rating% value and 'file' otherwise, including when no file tag exists.

Extra columns (formats)

formats maps column names to Title Formatting patterns; each track (including projected tracks) carries the evaluated values under its own formats object:

const result = await fb2k.invoke('playlist.getTracks', {
    start: 0, count: 50,
    formats: {
        myRating: '%rating%',
        codec: '%codec%'
    }
});
// Each row includes formats: { myRating: '5', codec: 'FLAC' }

Paths

absolutePath is the local filesystem path and can be passed directly to APIs such as artwork.getForTrack. path is the foobar2000 internal form.

Projection (fields parameter)

Specifying fields limits the returned object to the selected fields; index is always included.

const page = await fb2k.invoke('playlist.getTracks', {
    start: 0, count: 200,
    fields: ['title', 'artist', 'album', 'duration', 'path']
});

Accepted names are index, handle, title, artist, artists, album, albumId, albumArtist, albumArtists, genre, date, trackNumber, discNumber, duration, path, absolutePath, fileSize, bitrate, sampleRate, channels, codec, subsong and rating. The optional albumId is omitted when unavailable. Field names are case sensitive. Supplying unrecognized fields causes the invocation to fail with INVALID_PARAMS, listing them under details.unknownFields. composer, comment, and play-count fields cannot be projected and are returned only on full rows.

Omitting handle, absolutePath, and rating avoids resolving filesystem paths and evaluating %rating% per row. To retrieve play statistics during projection, request them via formats.

playlist.getGroupRuns

Split a whole playlist into runs of adjacent rows whose group key is equal, with ASCII letters compared case-insensitively; a second pattern sub-groups each run. Rows are never reordered and only the run boundaries come back, so the answer grows with the number of runs, not of rows. Keys are evaluated off the main thread. More than two patterns, an empty pattern or one that fails to compile fails with INVALID_PARAMS, the last two with details.pattern giving its position. An index past the last playlist fails with INVALID_INDEX and details.playlist giving the index asked for, a playlistGuid no playlist has with NOT_FOUND and details.playlistGuid; with both omitted and no active playlist the call fails with NO_ACTIVE_ITEM. An error while the keys are evaluated fails with OPERATION_FAILED, the failure carrying an empty runs and total 0.

Parameter	Type	Required	Description
patterns	string[]	Yes	One or two Title Formatting patterns; the second sub-groups each run. Must not be empty.
playlist	integer	No	Playlist index; omitted, the active playlist. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.

Returns

Field	Type	Description
playlist	integer	The playlist grouped.
playlistGuid	string	Unique identifier of the playlist, formatted as {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}. Pass as playlistGuid to reliably target this playlist.
total	integer	Rows in the playlist; the runs' count values add up to it.
runs	PlaylistGroupRun[]	The runs in playlist order, the first starting at row 0; empty for an empty playlist.
runs[].start	integer	First row of the run.
runs[].count	integer	Rows in the run.
runs[].key	string	The group key as the first row of the run spells it.
runs[].sub	PlaylistGroupSubRun[]	Second-level runs inside this one; present only when two patterns were provided.
runs[].sub[].start	integer	First row of the run.
runs[].sub[].count	integer	Rows in the run.
runs[].sub[].key	string	The second-level key as the first row of the run spells it.
contentVersion	string	The runs describe the rows as they were at this version.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

With two patterns each run also carries sub, and the sub-run start values are absolute row indices, not offsets within the parent:

{
    "start": 12,
    "count": 9,
    "key": "Album B | Artist B",
    "sub": [
        { "start": 12, "count": 5, "key": "1" },
        { "start": 17, "count": 4, "key": "2" }
    ]
}

Keys are compared case-insensitively over ASCII A-Z/a-z only; every other code point is compared byte for byte. An empty key is an ordinary key, not a missing one — a pattern that evaluates to an empty string still forms runs, so handle the fallback text on the display side if you want one.

Driving a grouped virtual list

Pair this with playlist.getTracks: the runs provide every header position and let the UI calculate total scroll height; each visible page of rows is fetched separately. Response size depends on the number of runs, key lengths and second-level groups, not on full track metadata. A pattern that puts every track in its own run makes runs as long as the playlist, and the host sets no upper bound. Compare total with a page response for the same playlist to detect a change in track count. Equal totals do not rule out replacements or reordering between the independent reads.

playlist.getMatchingRows

The rows of a playlist whose tracks match a foobar2000 query, in playlist order, in one call however long the playlist is; read the rows themselves with playlist.getTracksAt. The query takes the Media Library search syntax without SORT BY. A query the parser rejects fails with INVALID_PARAMS and details.param query, and so does one carrying SORT BY; many malformed queries are not rejected but simply match nothing. An index past the last playlist fails with INVALID_INDEX, a playlistGuid no playlist has with NOT_FOUND, and with both omitted and no active playlist the call fails with NO_ACTIVE_ITEM. The answer is a snapshot taken on the main thread: editing the playlist or a track's tags can change it, and so can the passing of time for a query such as %added% DURING LAST 2 WEEKS, which no event announces.

Parameter	Type	Required	Description
query	string	Yes	foobar2000 query, as in the Media Library search; SORT BY is refused. Must not be empty.
playlist	integer	No	Playlist index; omitted, the active playlist. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.

Returns

Field	Type	Description
playlist	integer	The playlist searched.
playlistGuid	string	Unique identifier of the playlist, formatted as {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}. Pass as playlistGuid to reliably target this playlist.
total	integer	Rows in the playlist when the query ran. Equal to the total of a later playlist.getTracks does not mean the playlist is unchanged: reordering and tag edits keep the count.
items	integer[]	The matching rows, ascending.
count	integer	Number of entries in items.
contentVersion	string	The row numbers in items hold only while the playlist keeps this version.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

Filtering a long playlist takes two calls however many rows it holds: one for the matching row numbers, then playlist.getTracksAt for the rows on screen.

// The playlist on screen, by the guid playlist.getAll reported for it
const playlistGuid = '{A9624480-77F0-4A2B-A76F-7EAB0C2EEC1C}';
const hits = await fb2k.invoke('playlist.getMatchingRows', {
    playlistGuid,
    query: 'artist HAS nachi OR title HAS nachi',
});
if (hits.success) {
    const page = await fb2k.invoke('playlist.getTracksAt', {
        playlistGuid,
        rows: hits.items.slice(0, 50),
        fields: ['title', 'artist', 'duration'],
    });
}

A lowercase letter in the query matches either case in the tag, an uppercase one only the same case, so lowercase the words a user types. HAS matches * and ? literally; IS treats them as wildcards. A double quote cannot be written inside a quoted value.

playlist.getTracksAt

Rows of a playlist picked by row number, in the order given, such as the rows playlist.getMatchingRows answers, which need not be adjacent. Each row is shaped as in playlist.getTracks and carries its index; a row past the last one is skipped, and duplicate indices are returned multiple times. A playlist index past the last one, a playlistGuid that matches no playlist, or an omitted playlist with no active playlist returns an empty result set.

Parameter	Type	Required	Description
rows	integer[]	Yes	Rows to read, in the order to return them. Each item: at least 0.
playlist	integer	No	Playlist index; omitted, the active playlist. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist, used in place of an index. For read queries where a missing target returns an empty result instead of failing. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS.
formats	Record<string, string>	No	Extra columns, as in playlist.getTracks.
fields	string[]	No	Keys each row carries besides index, as in playlist.getTracks; omitted, the whole row. Must not be empty.

Returns

Field	Type	Description
playlist	integer	The playlist read, as playlist in the result of playlist.getTracks.
playlistGuid	string	GUID of the playlist read; absent when it does not exist, as in playlist.getTracks.
total	integer	Rows in the playlist; 0 when it does not exist.
count	integer	Rows returned.
tracks	PlaylistTrackPartial[]	The rows in the order asked for, skipping those past the last row.
tracks[].handle	string	Cross-endpoint unique track identifier: formatted as absolutePath, appended with |subsong:N when subsong is non-zero. The same track yields the same handle from every method. Differs from standard filesystem paths; endpoints document whether handle identifiers are accepted in place of paths.
tracks[].path	string	Path as foobar2000 stores it: file:// for a local file, file-relative:// for a path stored relative to the foobar2000 folder (a portable install), or a remote URL. No subsong suffix.
tracks[].absolutePath	string	Native filesystem path without the subsong suffix; the same as path for a remote URL.
tracks[].subsong	integer	Subsong identifier the decoder assigns inside the file, not necessarily a sequence number; 0 for a whole file and for a remote stream.
tracks[].title	string	First TITLE value; empty when untagged.
tracks[].artist	string	Every ARTIST value joined with ", "; empty when untagged.
tracks[].artists	string[]	Every ARTIST value in tag order; empty when untagged.
tracks[].album	string	First ALBUM value; empty when untagged.
tracks[].albumId	string	Opaque album identity when its original name or album artist contains invalid UTF-8. Use this instead of the display names to match an album row; absent for ordinary names.
tracks[].albumArtist	string	Every ALBUM ARTIST value joined with ", "; empty when untagged.
tracks[].albumArtists	string[]	All ALBUM ARTIST values in tag order (albumArtists.join(", ") equals albumArtist); empty array when untagged. In library.getAlbums, a track that has an album is filed under the name album and the album artist albumArtists[0] (falling back to artists[0], or "" when both are empty); those are the name and albumArtist of that album's row. When albumId is present, match by albumId instead of display names to avoid collision from character replacement.
tracks[].genre	string	Every GENRE value joined with ", "; empty when untagged.
tracks[].date	string	First DATE value as tagged, such as 2019 or 2019-05-01; empty when untagged.
tracks[].trackNumber	integer	TRACKNUMBER read as an integer; 0 when absent or not a number.
tracks[].discNumber	integer	DISCNUMBER read as an integer; 0 when absent or not a number.
tracks[].duration	number	Length in seconds; 0 when unknown.
tracks[].fileSize	integer	File size in bytes; -1 when unknown, as for a remote stream.
tracks[].bitrate	integer	Average bitrate in kbit/s; 0 when unknown.
tracks[].sampleRate	integer	Sample rate in Hz; 0 when unknown.
tracks[].channels	integer	Channel count; 0 when unknown.
tracks[].codec	string	Codec name as the decoder reports it, such as FLAC or MP3; empty when unknown.
tracks[].rating	integer	Rating value from 0 to 5. Prefers the %rating% statistic (foo_playcount) if within 1..5; otherwise falls back to the RATING tag clamped to 0..5; 0 if neither is present.
tracks[].index	integer	Row in the playlist, from 0.
tracks[].composer	string	Every COMPOSER value joined with ", "; empty when untagged.
tracks[].comment	string	First COMMENT value; empty when untagged.
tracks[].playCount	integer	%play_count% from foo_playcount; absent when it gives no number, and on rows of playlist.getSelectedTracks or of a fields request.
tracks[].firstPlayed	string	%first_played% as foo_playcount formats it; absent when empty, on rows of playlist.getSelectedTracks and on rows of a fields request.
tracks[].lastPlayed	string	%last_played% as foo_playcount formats it; absent when empty, on rows of playlist.getSelectedTracks and on rows of a fields request.
tracks[].added	string	%added% as foo_playcount formats it; absent when empty, on rows of playlist.getSelectedTracks and on rows of a fields request.
tracks[].formats	Record<string, string>	Named Title Formatting columns; present only when formats was requested.
contentVersion	string	The row numbers hold only while the playlist keeps this version; absent when the playlist does not exist.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

playlist.playTrack

Play a row of a playlist, as double-clicking it does. A row past the last one fails with INVALID_INDEX. With deferred, expectedVersion is verified again before starting playback; if rows changed in between, playback is skipped.

Parameter	Type	Required	Description
playlist	integer	No	Index of the playlist; omitted, the active playlist. An index past the last playlist fails with INVALID_INDEX; with this omitted and no active playlist the call fails with NO_ACTIVE_ITEM. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.
index	integer	No	Row to play. At least 0. Default: 0.
deferred	boolean	No	Start the playback after the current message has been handled instead of before the call returns. The playlist is looked up again by its GUID when the playback starts: moved meanwhile, the same playlist plays; removed meanwhile, or shorter than index by then, nothing plays. Default: false.
muted	boolean	No	Mute before starting, so a page that sets the volume right afterwards leaves no audible gap. The mute is not undone by this call. Default: false.
expectedVersion	string	No	Expected content version for optimistic concurrency control. When mismatched, mutations are aborted with STALE_TARGET (details.current carries current version). Omitted, no check is made.

Returns

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

muted: true mutes before playback starts and never unmutes afterwards, so the player is left muted — restore the volume yourself when the intent was only to suppress the start of the track.

await fb2k.invoke('playlist.playTrack', { playlist: 0, index: 5 });

// Deferred start, recommended for streaming sources
await fb2k.invoke('playlist.playTrack', { playlist: 0, index: 0, deferred: true });

playlist.removeTracks

Remove rows from a playlist, saving an undo point first. Rows past the last one are ignored; a negative row fails with INVALID_PARAMS. A locked playlist fails with LOCKED.

Parameter	Type	Required	Description
playlist	integer	No	Index of the playlist; omitted, the active playlist. An index past the last playlist fails with INVALID_INDEX; with this omitted and no active playlist the call fails with NO_ACTIVE_ITEM. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.
items	integer[]	Yes	Rows to remove. Each item: at least 0.
expectedVersion	string	No	Expected content version for optimistic concurrency control. When mismatched, mutations are aborted with STALE_TARGET (details.current carries current version). Omitted, no check is made.

Returns

Field	Type	Description
contentVersion	string	Already includes this change; pass it as expectedVersion to the next call.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

playlist.removeSelectedTracks

Remove the selected rows from a playlist, saving an undo point first. A locked playlist fails with LOCKED.

Parameter	Type	Required	Description
playlist	integer	No	Index of the playlist; omitted, the active playlist. An index past the last playlist fails with INVALID_INDEX; with this omitted and no active playlist the call fails with NO_ACTIVE_ITEM. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.

Returns

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

playlist.moveTracks

Move the selected rows of a playlist by delta positions, saving an undo point first. When items is specified, it replaces the current selection before moving, and the caller's own selection is lost. A locked playlist fails with LOCKED.

Parameter	Type	Required	Description
playlist	integer	No	Index of the playlist; omitted, the active playlist. An index past the last playlist fails with INVALID_INDEX; with this omitted and no active playlist the call fails with NO_ACTIVE_ITEM. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.
items	integer[]	No	Target row indices to move; specified indices replace the current playlist selection before moving. When omitted or empty, moves the currently selected rows. Each item: at least 0.
delta	integer	Yes	How many positions to move: negative towards the top, positive towards the bottom.
expectedVersion	string	No	Expected content version for optimistic concurrency control. When mismatched, mutations are aborted with STALE_TARGET (details.current carries current version). Omitted, no check is made.

Returns

Field	Type	Description
contentVersion	string	Already includes this change; pass it as expectedVersion to the next call.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

await fb2k.invoke('playlist.moveTracks', { items: [0, 1, 2], delta: 3 });
await fb2k.invoke('playlist.moveTracks', { items: [5, 6], delta: -2 });

playlist.addPaths

Append files, folders or URLs to a playlist, saving an undo point first. foobar2000 resolves the batch as its own Add Files does: folders and playlist files are expanded, duplicates are dropped and the rows are sorted by the user's incoming-item order, so they do not keep the given order (playlist.addPathsSequential does). Entries longer than 2048 characters, and entries that resolve to nothing, are counted in invalidCount. When nothing is added the call fails with NOT_FOUND. A locked playlist fails with LOCKED. foobar2000 can show a progress dialog while it resolves the paths, and the playlist is looked up again afterwards: moved meanwhile, the tracks still go into it and playlist in the result is its new index; removed meanwhile, the call fails with OPERATION_FAILED.

Parameter	Type	Required	Description
playlist	integer	No	Index of the playlist; omitted, the active playlist. An index past the last playlist fails with INVALID_INDEX; with this omitted and no active playlist the call fails with NO_ACTIVE_ITEM. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.
paths	string[]	Yes	Files, folders or URLs; a |subsong:N suffix selects a subsong. Must not be empty.

Returns

Field	Type	Description
playlist	integer	Index of the playlist.
playlistGuid	string	Unique identifier of the playlist, formatted as {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}. Pass as playlistGuid to reliably target this playlist.
requestedPaths	integer	Number of entries in paths.
addedCount	integer	Tracks added; a folder counts every track it holds.
invalidCount	integer	Entries that were not usable.
countBefore	integer	Number of tracks before the addition.
totalCount	integer	Number of tracks after the addition.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

Additional public APIs

playlist.addHandles

Append tracks to a playlist, saving an undo point first. handles takes the same entries as playlist.insertTracks; when none is usable the call fails with NOT_FOUND. A locked playlist fails with LOCKED.

Parameter	Type	Required	Description
playlist	integer	No	Index of the playlist; omitted, the active playlist. An index past the last playlist fails with INVALID_INDEX; with this omitted and no active playlist the call fails with NO_ACTIVE_ITEM. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.
handles	any[]	Yes	Tracks to append: each a path with an optional |subsong:N suffix, or { path, subsong }. Must not be empty.

Returns

Field	Type	Description
playlist	integer	Index of the playlist.
playlistGuid	string	Unique identifier of the playlist, formatted as {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}. Pass as playlistGuid to reliably target this playlist.
requestedCount	integer	Number of entries in handles.
addedCount	integer	Tracks appended.
invalidCount	integer	Entries that were not usable.
countBefore	integer	Number of tracks before the addition.
totalCount	integer	Number of tracks after the addition.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

await fb2k.invoke('playlist.addHandles', { handles: ['C:\\Music\\song.flac'] });

playlist.addPathsAsync

Start appending paths to a playlist without waiting: the call returns a receipt, and playlist:addComplete with the same operationId reports the outcome. Plain files and URLs are added before the call returns; playlist files (.pls, .m3u, .cue and the like) are expanded in the background. Entries that are empty or longer than 2048 characters are counted in invalidCount; when no entry is left the call fails with INVALID_PARAMS. A locked playlist fails with LOCKED. The expanded tracks go into the same playlist even if it was moved meanwhile; if it was removed or locked meanwhile they are dropped.

Parameter	Type	Required	Description
playlist	integer	No	Index of the playlist; omitted, the active playlist. An index past the last playlist fails with INVALID_INDEX; with this omitted and no active playlist the call fails with NO_ACTIVE_ITEM. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.
paths	string[]	Yes	Files, folders, URLs or playlist files; a |subsong:N suffix selects a subsong. Must not be empty.

Returns

Field	Type	Description
operationId	string	Id of the operation; playlist:addComplete carries the same id.
playlistGuid	string	GUID of the playlist the paths go to; playlist:addComplete carries the same one.
status	"pending"	Always pending.
totalCount	integer	Entries that were accepted for processing.
invalidCount	integer	Entries refused before processing: empty or longer than 2048 characters.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

const res = await fb2k.invoke('playlist.addPathsAsync', { paths: ['C:\\Music\\Album'] });
if (res.success === false) throw new Error(res.error);
const { operationId } = res;

playlist.addPathsSequential

Append paths to a playlist in the given order, saving an undo point first; a path that expands to several tracks (a folder, a cue sheet) keeps its place. Entries longer than 2048 characters, and entries that resolve to nothing, are skipped. A locked playlist fails with LOCKED. A playlist moved or removed while the paths are resolved is handled as in playlist.addPaths.

Parameter	Type	Required	Description
playlist	integer	No	Index of the playlist; omitted, the active playlist. An index past the last playlist fails with INVALID_INDEX; with this omitted and no active playlist the call fails with NO_ACTIVE_ITEM. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.
paths	string[]	Yes	Files, folders or URLs, in the order to add them; a |subsong:N suffix selects a subsong. Must not be empty.

Returns

Field	Type	Description
playlist	integer	Index of the playlist.
playlistGuid	string	Unique identifier of the playlist, formatted as {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}. Pass as playlistGuid to reliably target this playlist.
addedCount	integer	Tracks added; 0 when nothing resolved, which still succeeds.
order	integer[]	Row of each added track, in the order they were added.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

await fb2k.invoke('playlist.addPathsSequential', { paths: ['C:\\Music\\a.flac', 'C:\\Music\\b.flac'] });

playlist.convertToAutoplaylist

Turn an existing playlist into an autoplaylist; its tracks are replaced by the query results. Fails with OPERATION_FAILED when foobar2000 refuses, for instance because the playlist is already an autoplaylist.

Parameter	Type	Required	Description
playlist	integer	No	Index of the playlist to convert; omitted, the active playlist. An index past the last playlist fails with INVALID_INDEX; with this omitted and no active playlist the call fails with NO_ACTIVE_ITEM. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.
query	string	Yes	Library query that selects the tracks, in foobar2000's query syntax. Must not be empty.
sort	string	No	Title Formatting pattern to sort the results by; empty, library order. Default: "".
keepSorted	boolean	No	Keep the playlist sorted by sort: when set, the user cannot reorder its tracks. Default: false.

Returns

Field	Type	Description
playlist	integer	Index of the playlist.
playlistGuid	string	Unique identifier of the playlist, formatted as {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}. Pass as playlistGuid to reliably target this playlist.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

await fb2k.invoke('playlist.convertToAutoplaylist', { playlist: 0, query: '%genre% IS Rock' });

playlist.createAutoplaylist

Create a playlist that foobar2000 fills from a library query and keeps up to date. An autoplaylist foobar2000 refuses to set up fails with OPERATION_FAILED, and the new playlist is removed again.

Parameter	Type	Required	Description
name	string	No	Name of the new playlist. Default: "New Autoplaylist".
query	string	Yes	Library query that selects the tracks, in foobar2000's query syntax. Must not be empty.
sort	string	No	Title Formatting pattern to sort the results by; empty, library order. Default: "".
keepSorted	boolean	No	Keep the playlist sorted by sort: when set, the user cannot reorder its tracks. Default: false.

Returns

Field	Type	Description
index	integer	Index of the new playlist.
playlist	integer	Index of the new playlist; the same as index.
guid	string	Unique identifier of the playlist, formatted as {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}. Pass as playlistGuid to reliably target this playlist.
name	string	Name of the new playlist.
query	string	The query, as given.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

const res = await fb2k.invoke('playlist.createAutoplaylist', { name: 'Rock', query: '%genre% IS Rock' });
if (res.success === false) throw new Error(res.error);
const { index } = res;

playlist.deselectAll

Clear the selection of a playlist.

Parameter	Type	Required	Description
playlist	integer	No	Index of the playlist; omitted, the active playlist. An index past the last playlist fails with INVALID_INDEX; with this omitted and no active playlist the call fails with NO_ACTIVE_ITEM. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.

Returns

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

await fb2k.invoke('playlist.deselectAll', { playlist: 0 });

playlist.focusTrack

Move the focus of a playlist; the same operation as playlist.setFocusedTrack under its older name.

Parameter	Type	Required	Description
playlist	integer	No	Index of the playlist; omitted, the active playlist. An index past the last playlist fails with INVALID_INDEX; with this omitted and no active playlist the call fails with NO_ACTIVE_ITEM. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.
index	integer	No	Row to focus; omitted or negative, the playlist loses its focus.
expectedVersion	string	No	Expected content version for optimistic concurrency control. When mismatched, mutations are aborted with STALE_TARGET (details.current carries current version). Omitted, no check is made.

Returns

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

await fb2k.invoke('playlist.focusTrack', { playlist: 0, index: 3 });

playlist.getAutoplaylistInfo

Describe a playlist's autoplaylist status and native editor availability without opening UI. Provider query failures fail with OPERATION_FAILED; an unknown capability is not a failure.

Parameter	Type	Required	Description
playlist	integer	No	Index of the playlist; omitted, the active playlist. An index past the last playlist fails with INVALID_INDEX; with this omitted and no active playlist the call fails with NO_ACTIVE_ITEM. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.

Returns

Field	Type	Description
isAutoplaylist	boolean	Whether the playlist is an autoplaylist. keepSorted, source and lockName are present only when it is; editor availability is always reported on success.
playlist	integer	Index of the playlist.
playlistGuid	string	Unique identifier of the playlist, formatted as {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}. Pass as playlistGuid to reliably target this playlist.
editorAvailability	"available" | "unavailable" | "unknown"	available means the provider declares UI support; unknown means it cannot be probed without attempting the native call. Neither guarantees that a particular call shows a window.
editorAvailabilityReason	"supported" | "noEditor" | "legacyClient" | "unverifiedLock" | "notAutoplaylist"	Why the capability is available, unavailable, or unknown. A legacy client or a compatible automatic-playlist lock has no side-effect-free editor probe.
configAvailability	"available" | "unavailable"	Whether this component can read and edit the provider's configuration.
configAvailabilityReason	"supported" | "externalProvider" | "unverifiedLock" | "notAutoplaylist"	Own providers are supported; external providers and unverified locks have no configuration protocol here.
keepSorted	boolean	Whether the manager-backed autoplaylist keeps its tracks sorted. For source: 'dui', the existing false value is a placeholder because the lock's configuration is not readable.
source	"sdk" | "dui"	sdk identifies the autoplaylist-manager path, including third-party clients; dui identifies the existing automatic-lock name heuristic. Neither identifies the current UI or editor support.
lockName	string	Name of the playlist's lock, present when source is dui.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

const info = await fb2k.invoke('playlist.getAutoplaylistInfo', { playlist: 0 });
if (info.success === false) throw new Error(info.error);
if (info.isAutoplaylist) console.log(info.source, info.keepSorted);

playlist.showAutoplaylistUI

Accept a request to open the native editor of an explicitly named autoplaylist. Give exactly one of playlist and playlistGuid. Acceptance precedes the queued native call; its normal return or failure is reported by playlist:autoplaylistUIResult to the same calling document. Subscribe before calling because the event can arrive before the acceptance promise resolves. The request does not activate the playlist or start playback. A normal native return does not report whether a window appeared, the user saved changes, cancelled, or closed the editor.

Parameter	Type	Required	Description
playlist	integer	No	Playlist index when the host first handles the request. Required unless playlistGuid is supplied; use the GUID to preserve identity across that initial queueing delay. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.

Returns

Field	Type	Description
accepted	boolean	Always true on success: the request was accepted, not necessarily executed yet.
operationId	string	Opaque identifier used to correlate the single native-call result event.
playlistGuid	string	Unique identifier of the playlist, formatted as {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}. Pass as playlistGuid to reliably target this playlist.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

The host resolves the target on its first main-thread turn and pins its GUID. A numeric index therefore means the playlist at that position at that first lookup; use playlistGuid to keep identity stable before it. Later reordering cannot redirect the request. The host queries the current provider again before calling it, so the GUID binds the playlist, not a particular provider instance. The playlist's track lock does not itself prevent opening its editor.

Failures

Before acceptance, a business failure is returned in the response, with any reason under details.reason. Once accepted, a failure is reported only by playlist:autoplaylistUIResult, with reason directly on the event. It does not produce a second response to the original request.

Situation	code	reason
No target, both target keys, malformed value or negative index	INVALID_PARAMS	—
Nonnegative index past the end	INVALID_INDEX	—
Target GUID no longer exists	NOT_FOUND	targetGone
Ordinary playlist	NOT_SUPPORTED	notAutoplaylist
Provider explicitly reports no editor	NOT_SUPPORTED	noEditor
Same GUID already queued or inside its native call	OPERATION_FAILED	requestInProgress
Provider query failed	OPERATION_FAILED	queryFailed
Native call could not be scheduled	OPERATION_FAILED	dispatchFailed
Native call threw, or the lock entry returned false	OPERATION_FAILED	providerFailed

A lock entry returning false does not establish that an editor is unavailable. An explicit no-editor result, a query error or a native-call error never triggers a retry through a different provider path.

Lifetime and repeated requests

The in-progress record is shared across the process for each GUID and lasts until the native call returns or throws. Navigating a page does not release a call that has already entered the provider. A non-modal editor may outlive that call; its owner and reuse behavior belong to the provider. The API cannot specify an owner, guarantee activation of an existing editor, or close that editor when the page is disposed.

Navigation, destruction or host recreation cancels pending work for the old document and discards results addressed to it. Results never go to a replacement document or fall back to the main window. If the original document is still valid when the native call finishes but the target was deleted, the result is NOT_FOUND / targetGone, even if the provider also threw. This does not undo actions the provider already performed.

See the complete SDK subscription example for a subscription installed before the call, a bounded early-result buffer, operationId matching and disposal. Acceptance and a successful call result provide no saved, cancelled, closed or changed notification. Refresh affected state from actual playlist:itemsAdded, playlist:itemsRemoved, playlist:itemsReordered, playlist:itemsReplaced and playlist:lockChanged events. A call result can prompt one reread but cannot cover subsequent edits in a non-modal window.

playlist.getAutoplaylistQuery

Describe a playlist's autoplaylist status without editor capability fields, and read the query and sort of a list driven by foobar2000's built-in query/sort client. The read does not open UI or change the list; it reflects the client's current state on every call. Lists of any other provider (third-party, managed by this component, lock-only) and lists whose configuration cannot be decoded return null for both, with note saying which; getAutoplaylistConfig reads the managed ones.

Parameter	Type	Required	Description
playlist	integer	No	Index of the playlist; omitted, the active playlist. An index past the last playlist fails with INVALID_INDEX; with this omitted and no active playlist the call fails with NO_ACTIVE_ITEM. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.

Returns

Field	Type	Description
isAutoplaylist	boolean	Whether the playlist is an autoplaylist; keepSorted, source, note and lockName are present only when true.
playlist	integer	Index of the playlist.
playlistGuid	string	Unique identifier of the playlist, formatted as {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}. Pass as playlistGuid to reliably target this playlist.
query	string | null	The list's query, read from foobar2000's built-in query/sort client. null when the provider is another one, the configuration cannot be decoded, or the playlist is not an autoplaylist; note says which for an autoplaylist.
sort	string | null	The independent sort expression, an empty string when none is set. null exactly when query is null. A host older than this field omits it, so test query first.
keepSorted	boolean	Whether the manager-backed autoplaylist keeps its tracks sorted. The false value for source: 'dui' is a placeholder for an unreadable lock configuration.
source	"sdk" | "dui"	sdk identifies the autoplaylist-manager path, including third-party clients; dui identifies the existing automatic-lock name heuristic. Neither identifies the current UI or editor support.
note	string	Why query is null for an autoplaylist: the provider does not support reading, the configuration cannot be parsed, or the list is managed (use getAutoplaylistConfig). Absent when query was read.
lockName	string	Name of the playlist's lock, present when source is dui.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

const q = await fb2k.invoke('playlist.getAutoplaylistQuery', { playlist: 0 });
// q.query and q.sort are strings for a list driven by the built-in query/sort client,
// otherwise null with q.note saying why

playlist.getAvailableColumns

List the playlist columns that foobar2000 and the installed components define for the Default UI playlist view.

This method takes no parameters.

Returns

Field	Type	Description
columns	PlaylistColumnDefinition[]	Every column, component by component.
columns[].id	string	Column GUID, written as XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX in upper case without braces, unlike a playlist GUID.
columns[].name	string	Display name.
columns[].pattern	string	Title Formatting pattern of the cell text.
columns[].alignment	"left" | "right" | "center"	Alignment of the cell text.
columns[].numeric	boolean	Whether the column holds numbers.
columns[].sortPattern	string	Title Formatting pattern used to sort by this column; absent when sorting uses pattern.
count	integer	Number of entries in columns.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

const result = await fb2k.invoke('playlist.getAvailableColumns');

playlist.getFocusTrack

Report the focused row of a playlist; the same as playlist.getFocusedTrack under its older name, except that a missing playlist fails instead of answering index -1: an index past the last playlist with INVALID_INDEX, a playlistGuid no playlist has with NOT_FOUND, and no active playlist when both are omitted with NO_ACTIVE_ITEM. On success playlist and playlistGuid are always present.

Parameter	Type	Required	Description
playlist	integer	No	Index of the playlist; omitted, the active playlist. An index past the last playlist fails with INVALID_INDEX; with this omitted and no active playlist the call fails with NO_ACTIVE_ITEM. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.

Returns

Field	Type	Description
playlist	integer	Index of the playlist.
playlistGuid	string	Unique identifier of the playlist, formatted as {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}. Pass as playlistGuid to reliably target this playlist.
index	integer	Focused row; -1 when the playlist has no focus.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

const res = await fb2k.invoke('playlist.getFocusTrack', { playlist: 0 });
if (res.success === false) throw new Error(res.error);
const { index } = res;

playlist.getFocusedTrack

Report the focused row of a playlist. An index past the last playlist, a playlistGuid no playlist has, or no active playlist when both are omitted, reports index -1 without playlist and playlistGuid rather than failing.

Parameter	Type	Required	Description
playlist	integer	No	Index of the playlist; omitted, the active playlist. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist, used in place of an index. For read queries where a missing target returns an empty result instead of failing. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS.

Returns

Field	Type	Description
playlist	integer	Index of the playlist; absent when there is no such playlist.
playlistGuid	string	GUID of the playlist, as playlistGuid takes it; absent when there is no such playlist.
index	integer	Focused row; -1 when the playlist has no focus or does not exist.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

const res = await fb2k.invoke('playlist.getFocusedTrack', { playlist: 0 });
if (res.success === false) throw new Error(res.error);
const { index } = res;

playlist.getLockInfo

Report whether a playlist carries a lock, such as an autoplaylist's.

Parameter	Type	Required	Description
playlist	integer	No	Index of the playlist; omitted, the active playlist. An index past the last playlist fails with INVALID_INDEX; with this omitted and no active playlist the call fails with NO_ACTIVE_ITEM. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.

Returns

Field	Type	Description
playlist	integer	Index of the playlist.
playlistGuid	string	Unique identifier of the playlist, formatted as {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}. Pass as playlistGuid to reliably target this playlist.
isLocked	boolean	Whether it carries a lock.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

const res = await fb2k.invoke('playlist.getLockInfo', { playlist: 0 });
if (res.success === false) throw new Error(res.error);
const { isLocked } = res;

playlist.getSelectedTracks

The selected rows of a playlist in playlist order, without the play statistics. An index past the last playlist fails with INVALID_INDEX, a playlistGuid no playlist has with NOT_FOUND; with both omitted and no active playlist the call fails with NO_ACTIVE_ITEM. Each of these failures, and giving both keys or a malformed GUID, carries an empty tracks.

Parameter	Type	Required	Description
playlist	integer	No	Playlist index; omitted, the active playlist. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.

Returns

Field	Type	Description
playlist	integer	The playlist read.
playlistGuid	string	Unique identifier of the playlist, formatted as {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}. Pass as playlistGuid to reliably target this playlist.
tracks	PlaylistTrack[]	The selected rows in playlist order.
tracks[].…	Track	Every field of Track.
tracks[].index	integer	Row in the playlist, from 0.
tracks[].composer	string	Every COMPOSER value joined with ", "; empty when untagged.
tracks[].comment	string	First COMMENT value; empty when untagged.
tracks[].playCount	integer	%play_count% from foo_playcount; absent when it gives no number, and on rows of playlist.getSelectedTracks or of a fields request.
tracks[].firstPlayed	string	%first_played% as foo_playcount formats it; absent when empty, on rows of playlist.getSelectedTracks and on rows of a fields request.
tracks[].lastPlayed	string	%last_played% as foo_playcount formats it; absent when empty, on rows of playlist.getSelectedTracks and on rows of a fields request.
tracks[].added	string	%added% as foo_playcount formats it; absent when empty, on rows of playlist.getSelectedTracks and on rows of a fields request.
tracks[].formats	Record<string, string>	Named Title Formatting columns; present only when formats was requested.
count	integer	Rows returned.
contentVersion	string	The row numbers in tracks hold only while the playlist keeps this version.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

const result = await fb2k.invoke('playlist.getSelectedTracks');

playlist.getSelection

List the selected rows of a playlist.

Parameter	Type	Required	Description
playlist	integer	No	Index of the playlist; omitted, the active playlist. An index past the last playlist fails with INVALID_INDEX; with this omitted and no active playlist the call fails with NO_ACTIVE_ITEM. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.

Returns

Field	Type	Description
items	integer[]	Selected rows, in playlist order.
count	integer	Number of entries in items.
playlist	integer	Index of the playlist.
playlistGuid	string	Unique identifier of the playlist, formatted as {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}. Pass as playlistGuid to reliably target this playlist.
contentVersion	string	The row numbers in items hold only while the playlist keeps this version.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

const res = await fb2k.invoke('playlist.getSelection', { playlist: 0 });
if (res.success === false) throw new Error(res.error);
const { items, count } = res;

playlist.insertTracks

Insert tracks at a position of a playlist, saving an undo point first. Each entry of handles is a path with an optional |subsong:N suffix, or { path, subsong }; entries that are neither, or that name nothing, are counted in invalidCount. When none is usable the call fails with NOT_FOUND. A locked playlist fails with LOCKED.

Parameter	Type	Required	Description
playlist	integer	No	Index of the playlist; omitted, the active playlist. An index past the last playlist fails with INVALID_INDEX; with this omitted and no active playlist the call fails with NO_ACTIVE_ITEM. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.
position	integer	No	Row before which the tracks go; past the last row, they are appended. At least 0. Default: 0.
handles	any[]	Yes	Tracks to insert: each a path with an optional |subsong:N suffix, or { path, subsong }. Must not be empty.
expectedVersion	string	No	Expected content version for optimistic concurrency control. When mismatched, mutations are aborted with STALE_TARGET (details.current carries current version). Omitted, no check is made.

Returns

Field	Type	Description
playlist	integer	Index of the playlist.
playlistGuid	string	Unique identifier of the playlist, formatted as {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}. Pass as playlistGuid to reliably target this playlist.
insertIndex	integer	The position that was asked for, before it was limited to the end of the playlist.
requestedCount	integer	Number of entries in handles.
addedCount	integer	Tracks inserted.
invalidCount	integer	Entries that were not usable.
countBefore	integer	Number of tracks before the insertion.
totalCount	integer	Number of tracks after the insertion.
contentVersion	string	Already includes this change; pass it as expectedVersion to the next call.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

const result = await fb2k.invoke('playlist.insertTracks', {
    playlist: 0,
    position: 5,
    handles: ['C:\\Music\\song.flac'],
});

playlist.isAutoplaylist

Report whether a playlist has an autoplaylist-manager client, including third-party clients, or is recognized by the compatible lock-name rule containing Auto.

Parameter	Type	Required	Description
playlist	integer	No	Index of the playlist; omitted, the active playlist. An index past the last playlist fails with INVALID_INDEX; with this omitted and no active playlist the call fails with NO_ACTIVE_ITEM. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.

Returns

Field	Type	Description
playlist	integer	Index of the playlist.
playlistGuid	string	Unique identifier of the playlist, formatted as {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}. Pass as playlistGuid to reliably target this playlist.
isAutoplaylist	boolean	Whether it is an autoplaylist.
lockName	string	Name of the playlist's lock, present when it carries a named lock without an autoplaylist-manager client, whether or not the lock makes it count as an autoplaylist.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

const res = await fb2k.invoke('playlist.isAutoplaylist', { playlist: 0 });
if (res.success === false) throw new Error(res.error);
const { isAutoplaylist } = res;

playlist.isLocked

Report whether a playlist carries a lock. An index past the last playlist fails with INVALID_INDEX, a playlistGuid no playlist has with NOT_FOUND. Every failure to find the playlist, and giving both keys or a malformed GUID, carries isLocked false.

Parameter	Type	Required	Description
playlist	integer	No	Index of the playlist; omitted, the active playlist. With this omitted and no active playlist the call fails with NO_ACTIVE_ITEM. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.

Returns

Field	Type	Description
isLocked	boolean	Whether the playlist carries a lock.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

const res = await fb2k.invoke('playlist.isLocked', { playlist: 0 });
if (res.success === false) throw new Error(res.error);
const { isLocked } = res;

playlist.redo

Reapply the change the last playlist.undo reverted. Fails with NOT_FOUND when there is nothing to redo, and with LOCKED when a lock on the playlist refuses the change.

Parameter	Type	Required	Description
playlist	integer	No	Index of the playlist; omitted, the active playlist. An index past the last playlist fails with INVALID_INDEX; with this omitted and no active playlist the call fails with NO_ACTIVE_ITEM. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.

Returns

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

await fb2k.invoke('playlist.redo', { playlist: 0 });

playlist.removeAutoplaylist

Release an autoplaylist-manager client, including a third-party client, keeping the current tracks. A compatible automatic-playlist lock without a manager client cannot be released this way: the call succeeds with source dui and changes nothing; playlist.remove deletes that playlist. A playlist that is not an autoplaylist fails with NOT_FOUND.

Parameter	Type	Required	Description
playlist	integer	No	Index of the playlist; omitted, the active playlist. An index past the last playlist fails with INVALID_INDEX; with this omitted and no active playlist the call fails with NO_ACTIVE_ITEM. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.

Returns

Field	Type	Description
playlist	integer	Index of the playlist.
playlistGuid	string	Unique identifier of the playlist, formatted as {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}. Pass as playlistGuid to reliably target this playlist.
source	"sdk" | "dui"	sdk when a manager client was released, including a third-party client; dui when only a compatible automatic-playlist lock was found and nothing changed.
note	string	Explanation, present when source is dui.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

await fb2k.invoke('playlist.removeAutoplaylist', { playlist: 0 });

playlist.reorder

Reorder a playlist's tracks, saving an undo point first: newOrder[i] is the current row of the track that moves to row i. A locked playlist fails with LOCKED, a list whose length is not the track count or that names a row twice with INVALID_PARAMS, an entry past the last row with INVALID_INDEX.

Parameter	Type	Required	Description
playlist	integer	No	Index of the playlist; omitted, the active playlist. An index past the last playlist fails with INVALID_INDEX; with this omitted and no active playlist the call fails with NO_ACTIVE_ITEM. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.
newOrder	integer[]	Yes	For each new row, the current row of the track that goes there; every row exactly once. Each item: at least 0.
expectedVersion	string	No	Expected content version for optimistic concurrency control. When mismatched, mutations are aborted with STALE_TARGET (details.current carries current version). Omitted, no check is made.

Returns

Field	Type	Description
playlist	integer	Index of the playlist.
playlistGuid	string	Unique identifier of the playlist, formatted as {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}. Pass as playlistGuid to reliably target this playlist.
itemCount	integer	Number of tracks reordered.
contentVersion	string	Already includes this change; pass it as expectedVersion to the next call.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

// newOrder must be a full permutation of the playlist's current track indices
await fb2k.invoke('playlist.reorder', { playlist: 0, newOrder: [2, 0, 1] });

playlist.reorderPlaylists

Reorder the playlist list, giving for each new position either the current index of the playlist that goes there (newOrder) or its GUID (newOrderGuids); give exactly one of the two, or the call fails with INVALID_PARAMS. Indices are read as the call arrives, so indices taken from playlist.getAll before another change reorder the wrong playlists without an error as long as the count still matches; GUIDs keep naming the playlists they were read from. A list whose length is not the playlist count fails with INVALID_PARAMS, and so does one naming a playlist twice or a malformed GUID; an index past the last playlist fails with INVALID_INDEX, a GUID no playlist has with NOT_FOUND.

Parameter	Type	Required	Description
newOrder	integer[]	No	For each new position, the current index of the playlist that goes there; every playlist exactly once. Each item: at least 0.
newOrderGuids	string[]	No	For each new position, the guid of the playlist that goes there, as playlist.getAll reports it; every playlist exactly once.

Returns

Field	Type	Description
count	integer	Number of playlists.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

// newOrder must be a full permutation of the existing playlist indices
await fb2k.invoke('playlist.reorderPlaylists', { newOrder: [2, 0, 1] });

playlist.replaceAllAndPlay

Replace the whole content of a playlist and play it: stop playback, clear the playlist (saving an undo point), add the paths in the given order as playlist.addPathsSequential does, make the playlist active and play or focus playIndex. Unlike playlist.addPaths, duplicates are kept and the user's incoming-item order is not applied. Entries longer than 2048 characters, and entries that resolve to nothing, are skipped. When nothing could be added the call fails with NOT_FOUND, and the playlist stays empty. A locked playlist fails with LOCKED before anything changes. The paths are resolved after the clear, as in playlist.addPaths: a playlist moved meanwhile is still the one filled and played; one removed meanwhile fails with OPERATION_FAILED, and one locked meanwhile fails with LOCKED and stays empty.

Parameter	Type	Required	Description
playlist	integer	No	Index of the playlist; omitted, the active playlist. An index past the last playlist fails with INVALID_INDEX; with this omitted and no active playlist the call fails with NO_ACTIVE_ITEM. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.
paths	string[]	Yes	The new content: files, folders or URLs. Must not be empty.
playIndex	integer	No	Row to play, or to focus with autoPlay false; past the last row, the first one. The rows follow the order of paths: when every path is one track, this is the index of the path to play. A path that expands to several tracks (a folder, a cue sheet) takes that many rows, and a skipped path takes none. At least 0. Default: 0.
stopFirst	boolean	No	Stop playback first, when something is playing. Default: true.
autoPlay	boolean	No	Play playIndex; false only focuses it. Default: true.

Returns

Field	Type	Description
playlist	integer	Index of the playlist.
playlistGuid	string	Unique identifier of the playlist, formatted as {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}. Pass as playlistGuid to reliably target this playlist.
clearedCount	integer	Number of tracks removed.
addedCount	integer	Tracks added.
totalCount	integer	Number of tracks afterwards.
playIndex	integer	Row that was played or focused.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

await fb2k.invoke('playlist.replaceAllAndPlay', { paths: ['C:\\Music\\song.flac'] });

playlist.reverse

Reverse the order of a playlist's tracks, saving an undo point first. A locked playlist fails with LOCKED.

Parameter	Type	Required	Description
playlist	integer	No	Index of the playlist; omitted, the active playlist. An index past the last playlist fails with INVALID_INDEX; with this omitted and no active playlist the call fails with NO_ACTIVE_ITEM. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.

Returns

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

await fb2k.invoke('playlist.reverse', { playlist: 0 });

playlist.selectAll

Select every row of a playlist.

Parameter	Type	Required	Description
playlist	integer	No	Index of the playlist; omitted, the active playlist. An index past the last playlist fails with INVALID_INDEX; with this omitted and no active playlist the call fails with NO_ACTIVE_ITEM. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.

Returns

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

await fb2k.invoke('playlist.selectAll', { playlist: 0 });

playlist.setFocusedTrack

Move the focus of a playlist to a row, or remove it. A row past the last one fails with INVALID_INDEX.

Parameter	Type	Required	Description
playlist	integer	No	Index of the playlist; omitted, the active playlist. An index past the last playlist fails with INVALID_INDEX; with this omitted and no active playlist the call fails with NO_ACTIVE_ITEM. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.
index	integer	No	Row to focus; omitted or negative, the playlist loses its focus.
expectedVersion	string	No	Expected content version for optimistic concurrency control. When mismatched, mutations are aborted with STALE_TARGET (details.current carries current version). Omitted, no check is made.

Returns

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

await fb2k.invoke('playlist.setFocusedTrack', { playlist: 0, index: 3 });

playlist.setSelection

Select rows of a playlist. Rows past the last one are ignored; a negative row fails with INVALID_PARAMS.

Parameter	Type	Required	Description
playlist	integer	No	Index of the playlist; omitted, the active playlist. An index past the last playlist fails with INVALID_INDEX; with this omitted and no active playlist the call fails with NO_ACTIVE_ITEM. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.
indices	integer[]	Yes	Rows to select; an empty list selects nothing. Each item: at least 0.
clearOthers	boolean	No	Deselect every other row; false adds indices to the current selection. Default: true.
expectedVersion	string	No	Expected content version for optimistic concurrency control. When mismatched, mutations are aborted with STALE_TARGET (details.current carries current version). Omitted, no check is made.

Returns

Field	Type	Description
contentVersion	string	Selecting rows leaves it unchanged.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

await fb2k.invoke('playlist.setSelection', { playlist: 0, indices: [0, 1, 2] });

playlist.shuffle

Put a playlist's tracks in random order, saving an undo point first. A locked playlist fails with LOCKED.

Parameter	Type	Required	Description
playlist	integer	No	Index of the playlist; omitted, the active playlist. An index past the last playlist fails with INVALID_INDEX; with this omitted and no active playlist the call fails with NO_ACTIVE_ITEM. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.

Returns

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

await fb2k.invoke('playlist.shuffle', { playlist: 0 });

playlist.sort

Sort a playlist by a Title Formatting pattern, saving an undo point first. A locked playlist fails with LOCKED.

Parameter	Type	Required	Description
playlist	integer	No	Index of the playlist; omitted, the active playlist. An index past the last playlist fails with INVALID_INDEX; with this omitted and no active playlist the call fails with NO_ACTIVE_ITEM. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.
pattern	string	No	Title Formatting pattern to sort by. Default: "%title%".
descending	boolean	No	Reverse the whole playlist after sorting. The reversal covers all tracks, even when selectedOnly is set. Default: false.
selectedOnly	boolean	No	Sort only the selected tracks among themselves, keeping the others in place. Default: false.

Returns

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

await fb2k.invoke('playlist.sort', { playlist: 0, pattern: '%artist% - %title%' });

playlist.undo

Revert a playlist to its last undo point. Fails with NOT_FOUND when there is none, and with LOCKED when a lock on the playlist refuses the change.

Parameter	Type	Required	Description
playlist	integer	No	Index of the playlist; omitted, the active playlist. An index past the last playlist fails with INVALID_INDEX; with this omitted and no active playlist the call fails with NO_ACTIVE_ITEM. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.

Returns

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

await fb2k.invoke('playlist.undo', { playlist: 0 });

Related playlist events

The following playlist lifecycle events are broadcast. Item-level events for the JIT queue shadow playlist are intentionally suppressed.

Event	Fired when	Payload keys
playlist:itemsAdded	Items were inserted into a playlist.	{ playlist, start, count }
playlist:itemsRemoved	Items were removed from a playlist.	{ playlist, oldCount, newCount }
playlist:itemsReordered	Items were reordered within a single playlist.	{ playlist, count }
playlist:selectionChanged	The selection in a playlist changed.	{ playlist }
playlist:focusChanged	The focused item in a playlist changed.	{ playlist, from, to }
playlist:itemsReplaced	Items in a playlist were replaced.	{ playlist, count }
playlist:created	A playlist was created.	{ index, name }
playlist:removed	One or more playlists were removed.	{ oldCount, newCount }
playlist:reordered	The playlist collection was reordered.	{ count }
playlist:activated	The active playlist changed.	{ oldIndex, newIndex }
playlist:renamed	A playlist was renamed.	{ index, name }
playlist:lockChanged	A playlist's lock state changed.	{ playlist, locked }
playlist:defaultFormatChanged	The default playlist format changed.	{}
playlist:addComplete	An asynchronous path-add operation finished.	{ operationId, success, addedCount, totalCount }

from, to, oldIndex, and newIndex are -1 when the corresponding index is unavailable.

playlist.createManagedAutoplaylist

Create an autoplaylist whose query and sorting are managed by this component. Requires foo_ui_webview2 to remain installed. Invalid configuration is rejected before creating the playlist. Success reports the configuration snapshot, not completed track rebuilding or disk persistence.

Parameter	Type	Required	Description
name	string	No	Name of the new playlist; at most 65536 UTF-8 bytes, without NUL. Default: "New Autoplaylist".
query	string	Yes	foobar2000 library query, at most 65536 UTF-8 bytes. Blank text and NUL are rejected.
sort	string	No	Independent Title Formatting sort. Empty uses the query's sorting or the host default. A nonempty value conflicts with explicit SORT BY in the query. At most 65536 UTF-8 bytes, without NUL. Default: "".
keepSorted	boolean	No	Keep tracks sorted and prevent manual reordering. Default: false.

Returns

Field	Type	Description
playlistGuid	string	Unique identifier of the playlist, formatted as {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}. Pass as playlistGuid to reliably target this playlist.
query	string	The provider's query text, unchanged.
sort	string	Independent sort text, unchanged; query-embedded sorting remains in query.
keepSorted	boolean	Current keep-sorted flag read from the autoplaylist manager.
revision	string	Opaque configuration revision, scoped to this provider instance. Not a track-content version.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

playlist.getAutoplaylistConfig

Read the configuration of an autoplaylist managed by this component. Specify exactly one target. Ordinary playlists and playlists from other providers fail with NOT_SUPPORTED (with details.reason).

Parameter	Type	Required	Description
playlist	integer	No	Playlist index; required unless playlistGuid is given. No active-playlist default. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.

Returns

Field	Type	Description
playlistGuid	string	Unique identifier of the playlist, formatted as {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}. Pass as playlistGuid to reliably target this playlist.
query	string	The provider's query text, unchanged.
sort	string	Independent sort text, unchanged; query-embedded sorting remains in query.
keepSorted	boolean	Current keep-sorted flag read from the autoplaylist manager.
revision	string	Opaque configuration revision, scoped to this provider instance. Not a track-content version.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

playlist.setAutoplaylistConfig

Edit configuration of a managed autoplaylist against its expected revision. Omitted fields keep existing values; provide at least one modification. Unchanged values do not advance revision or trigger rebuilds. Stale revisions fail with OPERATION_FAILED (details.reason: 'revisionConflict'). Configuration is validated before write. Host failures may leave changes partially applied: details.state (unchanged, changed, or unknown) covers the configuration only, and details.current is included only when the current state is known. Neither success nor failure indicates disk persistence or finished track rebuilds.

Parameter	Type	Required	Description
playlist	integer	No	Playlist index; required unless playlistGuid is given. No active-playlist default. At least 0.
playlistGuid	string	No	Persistent unique identifier of a playlist (bracketed GUID, case-insensitive), used in place of a mutable index. Mutually exclusive with playlist; passing both or an invalid format fails with INVALID_PARAMS. Fails with NOT_FOUND if the playlist does not exist, never falling back. Invalid-format and not-found failures return the given GUID in details.playlistGuid.
expectedRevision	string	Yes	Opaque revision from the most recent configuration snapshot. Invalid after restart or provider replacement.
query	string	No	New query, at most 65536 UTF-8 bytes. Blank text and NUL are rejected; omitted keeps the query.
sort	string	No	New independent sort; empty clears it, omitted keeps it. Conflicts with query SORT BY when nonempty. At most 65536 UTF-8 bytes, without NUL.
keepSorted	boolean	No	New keep-sorted setting; omitted keeps the current manager flag.

Returns

Field	Type	Description
playlistGuid	string	Unique identifier of the playlist, formatted as {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}. Pass as playlistGuid to reliably target this playlist.
query	string	The provider's query text, unchanged.
sort	string	Independent sort text, unchanged; query-embedded sorting remains in query.
keepSorted	boolean	Current keep-sorted flag read from the autoplaylist manager.
revision	string	Opaque configuration revision, scoped to this provider instance. Not a track-content version.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.