Skip to content

Playlist API ​

Playlist management, track operations, autoplaylists, and helpers. 47 APIs.

Parameter compatibility: every Playlist API accepts both playlist and index for the playlist index.

List management ​

playlist.getCount ​

Get the number of playlists.

  • Parameters: none
  • Returns: { "count": 5 }
javascript
const { count } = await fb2k.invoke('playlist.getCount');

playlist.getAll ​

Get information for all playlists.

  • Parameters: none

Returns:

json
[
    {
        "index": 0,
        "name": "Default",
        "trackCount": 150,
        "isActive": true,
        "isPlaying": true,
        "isLocked": false,
        "isAutoplaylist": false
    }
]

Breaking Change (v1.1.18)

playlist.getAll no longer returns duration (avoids loading every track across every playlist). Use playlist.getActive or playlist.getPlaying when you need a single playlist duration.

v1.1.18 added

The isAutoplaylist field is now inlined in playlist.getAll; you no longer need per-playlist playlist.isAutoplaylist calls.

playlist.getActive ​

Get the active playlist. Includes a duration field.

  • Parameters: none

Returns: {"duration":"...","found":true,"index":0,"isActive":true,"isLocked":true,"isPlaying":true,"name":"...","success":true,"trackCount":"..."}

Returns { "success": true, "found": false } when there is no active playlist.

playlist.setActive ​

Set the active playlist.

ParameterTypeRequiredDescription
playlistintegerYesTarget index. There is no active-playlist fallback, so omitting it fails.

Returns: { "success": true }

Unlike most playlist methods, omitting playlist does not fall back to the active playlist — it returns { "success": false, "error": "Invalid playlist index" }.

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

playlist.getPlaying ​

Get the currently playing playlist. Includes a duration field.

  • Parameters: none

Returns: {"duration":"...","found":true,"index":0,"isActive":true,"isLocked":true,"isPlaying":true,"name":"...","success":true,"trackCount":"..."}

Returns { "success": true, "found": false } when nothing is playing.

playlist.create ​

Create a new playlist.

ParameterTypeRequiredDefaultDescription
namestringNoNew Playlist
positionintegerNo—Insert position; appends when omitted.

Returns: { "success": true, "index": 2 }

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

playlist.remove ​

Remove a playlist.

ParameterTypeRequiredDefaultDescription
playlistintegerNoactive playlist

Returns: { "success": true }

A locked playlist cannot be removed and returns { "success": false, "error": "Playlist is locked", "code": "LOCKED" }. Removal can also report a plain success: false with no error when the operation is refused for another reason.

playlist.rename ​

Rename a playlist.

ParameterTypeRequiredDefaultDescription
playlistintegerYes—Target index. There is no active-playlist fallback, so omitting it fails.
namestringNo""New name.

Returns: { "success": true }

As with playlist.setActive, omitting playlist does not fall back to the active playlist — it returns { "success": false, "error": "Invalid playlist index" }.

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

playlist.clear ​

Remove all tracks from a playlist.

ParameterTypeRequiredDefaultDescription
playlistintegerNoactive playlist

Returns:

json
{
    "success": true,
    "playlist": 0,
    "clearedCount": 22,
    "remainingCount": 0
}

playlist.duplicate ​

Duplicate a playlist. The copy is inserted immediately after the source playlist.

ParameterTypeRequiredDefaultDescription
playlistintegerNoactive playlist
namestringNosource name + (Copy)

Returns: { "success": true, "index": 1, "sourcePlaylist": 0, "newPlaylist": 1, "name": "Default (Copy)", "trackCount": 150 }

Track operations ​

playlist.getTrackCount ​

Get the number of tracks in a playlist.

ParameterTypeRequiredDefaultDescription
playlistintegerNoactive playlist
indexintegerNo—Alias for playlist, read only when playlist is absent.

Returns: { "count": 150 }

This method returns no success field. An index that cannot be resolved yields { "count": 0 } rather than an error, so a zero count does not distinguish an empty playlist from an invalid target.

playlist.getTracks ​

Get a paged list of tracks in a playlist. The response has no success field.

ParameterTypeRequiredDefaultDescription
playlistintegerNoactive playlist
indexintegerNo—Alias for playlist, read only when playlist is absent.
startintegerNo0Page offset.
countintegerNo100Page size.
formatsobjectNo{}Extra TitleFormat columns (see tip below).

Returns:

json
{
    "playlist": 0,
    "start": 0,
    "count": 20,
    "total": 150,
    "tracks": [
        {
            "index": 0,
            "title": "Song 1",
            "artist": "Artist 1",
            "album": "Album 1",
            "albumArtist": "Artist 1",
            "genre": "Rock",
            "date": "2024",
            "trackNumber": 1,
            "discNumber": 1,
            "duration": 180.5,
            "path": "file://C:/Music/song1.flac",
            "absolutePath": "C:\\Music\\song1.flac",
            "fileSize": 25600000,
            "subsong": 0,
            "rating": 5,
            "codec": "FLAC",
            "bitrate": 1411,
            "sampleRate": 44100,
            "channels": 2,
            "composer": "Lennon/McCartney",
            "comment": "",
            "playCount": "15",
            "firstPlayed": "2024-01-15 10:30:00",
            "lastPlayed": "2026-02-10 20:00:00",
            "added": "2024-01-10 08:00:00"
        }
    ]
}

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.

column (formats Parameter)

playlist.getTracks supports formats Parameter TitleFormat column :

javascript
const result = await fb2k.invoke('playlist.getTracks', {
    start: 0, count: 50,
    formats: {
        myRating: '%rating%',
        codec: '%codec%'
    }
});
// Each track object gains the extra myRating and codec fields

Paths

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

playlist.playTrack ​

Play a specific track in a playlist.

ParameterTypeRequiredDefaultDescription
playlistintegerNoactive playlist
indexintegerNo0Track index. Falls back to track, then 0.
trackintegerNo0Legacy alias for index.
deferredbooleanNofalseDeferred start, recommended for streaming sources.
mutedbooleanNofalseMutes before playback starts (see note below).

Returns: { "success": true }

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. An out-of-range index returns { "success": false, "error": "Invalid track index" }.

javascript
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 the specified tracks from a playlist.

ParameterTypeRequiredDefaultDescription
playlistintegerNoactive playlist
indexintegerNo—Alias for playlist, read only when playlist is absent.
itemsarray<integer>No[]Track indices to remove.

Returns: { "success": true }

A locked playlist is rejected with { "success": false, "error": "Playlist is locked", "code": "LOCKED" }.

playlist.removeSelectedTracks ​

Remove the currently selected tracks from a playlist.

ParameterTypeRequiredDefaultDescription
playlistintegerNoactive playlist
indexintegerNo—Alias for playlist, read only when playlist is absent.

Returns: { "success": true }

A locked playlist is rejected with { "success": false, "error": "Playlist is locked", "code": "LOCKED" }.

playlist.moveTracks ​

Move selected tracks by delta. When items is non-empty, those indices become the selection first; when items is empty, the current selection is moved (SMP-compatible).

ParameterTypeRequiredDefaultDescription
playlistintegerNoactive playlist
indexintegerNo—Alias for playlist, read only when playlist is absent.
itemsarray<integer>No[]Empty moves the current selection (SMP-compatible).
deltaintegerNo0Displacement; negative moves up.

Returns: { "success": true }

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

playlist.addPaths ​

Add files or folders to a playlist. Paths are resolved synchronously via playlist_incoming_item_filter and CUE sheets are expanded automatically.

ParameterTypeRequiredDefaultDescription
playlistintegerNoactive playlist
pathsarray<string>Yes—File or folder paths. An empty array fails with No paths specified.

Returns:

json
{
    "success": true,
    "playlist": 0,
    "requestedPaths": 25,
    "addedCount": 25,
    "invalidCount": 0,
    "countBefore": 0,
    "totalCount": 25
}

Additional public APIs ​

playlist.addHandles ​

ParameterTypeRequiredDefaultDescription
playlistintegerNoactive playlist
handlesarray<object | string>Yes—Entries as { path, subsong } objects or path|subsong:N strings.

Returns: {"addedCount":"...","countBefore":"...","error":"...","invalidCount":"...","playlist":"...","requestedCount":"...","success":true,"totalCount":"..."}

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

playlist.addPathsAsync ​

ParameterTypeRequiredDefaultDescription
playlistintegerNoactive playlist
pathsarray<string>Yes—File or folder paths. An empty array fails with No paths specified.

Returns: {"error":"...","invalidCount":"...","operationId":"...","status":"...","success":true,"totalCount":"..."}

js
const { operationId } = await fb2k.invoke('playlist.addPathsAsync', { paths: ['C:\\Music\\Album'] });

playlist.addPathsSequential ​

ParameterTypeRequiredDefaultDescription
playlistintegerNoactive playlist
pathsarray<string>Yes—File or folder paths. An empty array fails with No paths specified.

Returns: {"addedCount":"...","error":"...","order":"...","playlist":"...","success":true}

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

playlist.convertToAutoplaylist ​

ParameterTypeRequiredDefaultDescription
playlistintegerNoactive playlist
querystringYes—Filter expression. An empty value fails with Query is required.
sortstringNo—Titleformat sort pattern.
keepSortedbooleanNofalseKeeps the playlist sorted by sort.

Returns: {"error":"...","playlist":"...","success":true}

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

playlist.createAutoplaylist ​

ParameterTypeRequiredDefaultDescription
namestringNoNew Autoplaylist
querystringYes—Filter expression. An empty value fails with Query is required.
sortstringNo—Titleformat sort pattern.
keepSortedbooleanNofalseKeeps the playlist sorted by sort.

Returns: {"error":"...","index":"...","name":"...","playlist":"...","query":"...","success":true}

js
const { index } = await fb2k.invoke('playlist.createAutoplaylist', { name: 'Rock', query: '%genre% IS Rock' });

playlist.deselectAll ​

ParameterTypeRequiredDefaultDescription
playlistintegerNoactive playlist

Returns: {"success":true}

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

playlist.focusTrack ​

ParameterTypeRequiredDefaultDescription
playlistintegerNoactive playlist
indexintegerNo—Target track; synonym of track, takes precedence. Omitting focuses nothing.
trackintegerNo—Legacy alias for index.

Returns: {"error":"...","success":true}

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

playlist.getAutoplaylistInfo ​

Reports whether a playlist is an autoplaylist, and its sort/source metadata when it is.

ParameterTypeRequiredDefaultDescription
playlistintegerNoactive playlist

Returns — an autoplaylist: { "isAutoplaylist": true, "playlist": 0, "keepSorted": false, "source": "sdk" }. Anything else: { "isAutoplaylist": false, "playlist": 0 }, with keepSorted and source absent.

source is "sdk" or "dui"; keepSorted is always false for a dui source. lockName accompanies a dui source only — an autoplaylist created through the SDK never carries it, even when the playlist is locked. Neither branch returns a success field — test isAutoplaylist instead. An out-of-range playlist returns { "success": false, "error": "Invalid playlist index" }.

js
const info = await fb2k.invoke('playlist.getAutoplaylistInfo', { playlist: 0 });
if (info.isAutoplaylist) console.log(info.source, info.keepSorted);

playlist.getAutoplaylistQuery ​

Reports autoplaylist metadata for a playlist. The query string itself is not retrievable.

ParameterTypeRequiredDefaultDescription
playlistintegerNoactive playlist

Returns — an autoplaylist: { "isAutoplaylist": true, "playlist": 0, "query": null, "keepSorted": false, "source": "sdk", "note": "Query string not exposed by SDK" }. Anything else: { "isAutoplaylist": false, "playlist": 0, "query": null }.

query is always null — foobar2000 does not expose the filter expression, so this method cannot be used to read it back. keepSorted, source, and note appear only for an autoplaylist, and lockName only alongside a dui source. Neither branch returns a success field. An out-of-range playlist returns { "success": false, "error": "Invalid playlist index" }.

js
const q = await fb2k.invoke('playlist.getAutoplaylistQuery', { playlist: 0 });
// q.query is null even when q.isAutoplaylist is true

playlist.getAvailableColumns ​

Lists the columns provided by the Default UI, for use as titleformat patterns.

No parameters.

Returns: a bare JSON array — not an envelope, so there is no success field. Each entry carries id, name, pattern, alignment (left / right / center), and numeric; sortPattern is present only when the column defines a distinct sort script. The array is empty when no provider is registered.

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

playlist.getFocusTrack ​

ParameterTypeRequiredDefaultDescription
playlistintegerNoactive playlist

Returns: {"error":"...","index":"...","playlist":"...","success":true}

js
const { index } = await fb2k.invoke('playlist.getFocusTrack', { playlist: 0 });

playlist.getFocusedTrack ​

ParameterTypeRequiredDefaultDescription
playlistintegerNoactive playlist

Returns: {"index":"...","playlist":"...","success":true}

js
const { index } = await fb2k.invoke('playlist.getFocusedTrack', { playlist: 0 });

playlist.getLockInfo ​

ParameterTypeRequiredDefaultDescription
playlistintegerNoactive playlist

Returns: {"error":"...","isLocked":"...","playlist":"...","success":true}

js
const { isLocked } = await fb2k.invoke('playlist.getLockInfo', { playlist: 0 });

playlist.getSelectedTracks ​

ParameterTypeRequiredDefaultDescription
playlistintegerNoactive playlist
indexintegerNo—Alias for playlist, read only when playlist is absent.

Returns: {"error":"...","success":true,"tracks":"..."}

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

playlist.getSelection ​

ParameterTypeRequiredDefaultDescription
playlistintegerNoactive playlist

Returns: {"count":"...","error":"...","items":"...","playlist":"...","success":true}

js
const { items, count } = await fb2k.invoke('playlist.getSelection', { playlist: 0 });

playlist.insertTracks ​

ParameterTypeRequiredDefaultDescription
playlistintegerNoactive playlist
positionintegerNo0Insert position. Falls back to index.
indexintegerNo—Legacy alias for position.
handlesarray<object | string>Yes—Entries as { path, subsong } objects or path|subsong:N strings.

Returns: {"addedCount":"...","countBefore":"...","error":"...","insertIndex":"...","invalidCount":"...","playlist":"...","requestedCount":"...","success":true,"totalCount":"..."}

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

playlist.isAutoplaylist ​

Tests whether a playlist is an autoplaylist.

ParameterTypeRequiredDefaultDescription
playlistintegerNoactive playlist

Returns: { "playlist": 0, "isAutoplaylist": true }

lockName is added whenever the playlist carries a named lock, independently of the result — so unlike the two methods above, it can appear together with isAutoplaylist: false for an ordinary locked playlist. The success path has no success field — test isAutoplaylist instead. An out-of-range playlist returns { "success": false, "error": "Invalid playlist index" }.

js
const { isAutoplaylist } = await fb2k.invoke('playlist.isAutoplaylist', { playlist: 0 });

playlist.isLocked ​

ParameterTypeRequiredDefaultDescription
playlistintegerNoactive playlist

Returns: {"error":"...","isLocked":"...","success":true}

js
const { isLocked } = await fb2k.invoke('playlist.isLocked', { playlist: 0 });

playlist.redo ​

ParameterTypeRequiredDefaultDescription
playlistintegerNoactive playlist

Returns: {"error":"...","success":true}

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

playlist.removeAutoplaylist ​

ParameterTypeRequiredDefaultDescription
playlistintegerNoactive playlist

Returns: {"error":"...","note":"...","playlist":"...","source":"...","success":true}

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

playlist.reorder ​

ParameterTypeRequiredDefaultDescription
playlistintegerNoactive playlist
newOrderarray<integer>Yes—A full permutation of the playlist's track indices. Its length must equal the current item count.

Returns: {"error":"...","expected":"...","got":"...","index":"...","itemCount":"...","playlist":"...","success":true}

js
// 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 ​

ParameterTypeRequiredDescription
newOrderarray<integer>YesA full permutation of the playlist indices. Its length must equal the playlist count.

Returns: {"count":"...","error":"...","expected":"...","got":"...","index":"...","success":true}

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

playlist.replaceAllAndPlay ​

ParameterTypeRequiredDefaultDescription
playlistintegerNoactive playlist
pathsarray<string>Yes—File or folder paths. An empty array fails with No paths specified.
playIndexintegerNo0Track to start playing after the add.
stopFirstbooleanNotrueStops current playback before adding.
autoPlaybooleanNotrueStarts playback after adding.

Returns: {"addedCount":"...","clearedCount":"...","error":"...","invalidCount":"...","playIndex":"...","playlist":"...","success":true,"totalCount":"..."}

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

playlist.reverse ​

ParameterTypeRequiredDefaultDescription
playlistintegerNoactive playlist

Returns: {"success":true}

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

playlist.selectAll ​

ParameterTypeRequiredDefaultDescription
playlistintegerNoactive playlist

Returns: {"success":true}

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

playlist.setFocusedTrack ​

ParameterTypeRequiredDefaultDescription
playlistintegerNoactive playlist
indexintegerNo—Target track; omitting focuses nothing.

Returns: {"error":"...","success":true}

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

playlist.setSelection ​

ParameterTypeRequiredDefaultDescription
playlistintegerNoactive playlist
indexintegerNo—Alias for playlist, read only when playlist is absent.
indicesarray<integer>No[]Track indices to select.
clearOthersbooleanNotrueClears the existing selection first.

Returns: {"error":"...","success":true}

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

playlist.shuffle ​

ParameterTypeRequiredDefaultDescription
playlistintegerNoactive playlist
indexintegerNo—Alias for playlist, read only when playlist is absent.

Returns: {"error":"...","success":true}

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

playlist.sort ​

ParameterTypeRequiredDefaultDescription
playlistintegerNoactive playlist
indexintegerNo—Alias for playlist, read only when playlist is absent.
patternstringNo%title%Titleformat sort pattern.
descendingbooleanNofalseSort descending.
selectedOnlybooleanNofalseSort only the selected tracks.

Returns: {"error":"...","success":true}

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

playlist.undo ​

ParameterTypeRequiredDefaultDescription
playlistintegerNoactive playlist

Returns: {"error":"...","success":true}

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

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

EventFired whenPayload keys
playlist:itemsAddedItems were inserted into a playlist.{ playlist, start, count }
playlist:itemsRemovedItems were removed from a playlist.{ playlist, oldCount, newCount }
playlist:itemsReorderedItems were reordered within a single playlist.{ playlist, count }
playlist:selectionChangedThe selection in a playlist changed.{ playlist }
playlist:focusChangedThe focused item in a playlist changed.{ playlist, from, to }
playlist:itemsReplacedItems in a playlist were replaced.{ playlist, count }
playlist:createdA playlist was created.{ index, name }
playlist:removedOne or more playlists were removed.{ oldCount, newCount }
playlist:reorderedThe playlist collection was reordered.{ count }
playlist:activatedThe active playlist changed.{ oldIndex, newIndex }
playlist:renamedA playlist was renamed.{ index, name }
playlist:lockChangedA playlist's lock state changed.{ playlist, locked }
playlist:defaultFormatChangedThe default playlist format changed.{}
playlist:addCompleteAn asynchronous path-add operation finished.{ operationId, success, addedCount, totalCount }

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