Documentation/plman
namespace

plman

js/foo_uie_jsplitter.js:1037

Functions for managing foobar2000 playlists.

property

ActivePlaylist

js/foo_uie_jsplitter.js:1044
ActivePlaylist: number

-1 if there is no active playlist.

Examples

console.log(plman.ActivePlaylist);
plman.ActivePlaylist = 1; // Switches to 2nd playlist.
property

PlaybackOrder

js/foo_uie_jsplitter.js:1057
PlaybackOrder: number

See PlaybackOrder enum 0 - Default
1 - Repeat (Playlist)
2 - Repeat (Track)
3 - Random
4 - Shuffle (tracks)
5 - Shuffle (albums)
6 - Shuffle (folders)

property

PlayingPlaylist

js/foo_uie_jsplitter.js:1072
PlayingPlaylist: number

-1 if there is no playing playlist.

Example

console.log(plman.PlayingPlaylist);
propertyreadonly

PlaylistCount

js/foo_uie_jsplitter.js:1082
PlaylistCount: number
propertyreadonly

PlaylistRecycler

js/foo_uie_jsplitter.js:1088
PlaylistRecycler: FbPlaylistRecycler

A Recycle Bin for playlists.

method

AddItemToPlaybackQueue

js/foo_uie_jsplitter.js:1629
AddItemToPlaybackQueue(handle)

Parameters

NameTypeDescription
handleFbMetadbHandle
method

AddLocations

js/foo_uie_jsplitter.js:1096
AddLocations(playlistIndex, paths, select)

This operation is asynchronous and may take some time to complete if it's a large array.

Parameters

NameTypeDescription
playlistIndexnumber
pathsArray<string>

An array of files/URLs

select = falseoptionalboolean

If true, the active playlist will be set to the playlistIndex, the items will be selected and focus will be set to the first new item.

Example

plman.AddLocations(plman.ActivePlaylist, ["e:\\1.mp3"]);
// This operation is asynchronous, so any code in your script directly
// after this line will run immediately without waiting for the job to finish.
method

AddPlaylistItemToPlaybackQueue

js/foo_uie_jsplitter.js:1634
AddPlaylistItemToPlaybackQueue(playlistIndex, playlistItemIndex)

Parameters

NameTypeDescription
playlistIndexnumber
playlistItemIndexnumber
method

ClearPlaylist

js/foo_uie_jsplitter.js:1112
ClearPlaylist(playlistIndex)

Parameters

NameTypeDescription
playlistIndexnumber

Example

plman.ClearPlaylist(plman.PlayingPlaylist);
method

ClearPlaylistSelection

js/foo_uie_jsplitter.js:1120
ClearPlaylistSelection(playlistIndex)

Parameters

NameTypeDescription
playlistIndexnumber

Example

plman.ClearPlaylistSelection(plman.ActivePlaylist);
method

CreateAutoPlaylist

js/foo_uie_jsplitter.js:1128
CreateAutoPlaylist(playlistIndex, name, query, sort, flags)

Parameters

NameTypeDescription
playlistIndexnumber
namestring

Name for the new autoplaylist.

querystring

Title formatting pattern for forming the playlist content.

sort = ''optionalstring

Title formatting pattern for sorting.

flags = 0optionalnumber

1 - when set, will keep the autoplaylist sorted and prevent user from reordering it.

Returns

number —

Index of the created playlist.

method

CreatePlaylist

js/foo_uie_jsplitter.js:1138
CreatePlaylist(playlistIndex, name)

Parameters

NameTypeDescription
playlistIndexnumber
namestring

Returns

number —

Index of the created playlist.

Examples

// Creates a new playlist named "New playlist", which is put at the beginning of the current playlists.
plman.CreatePlaylist(0, '');
// Create a new playlist named "my favourites", which is put at the end.
plman.CreatePlaylist(plman.PlaylistCount, 'my favourites');
method

DuplicatePlaylist

js/foo_uie_jsplitter.js:1153
DuplicatePlaylist(playlistIndex, name)

Note: the duplicated playlist gets inserted directly after the source playlistIndex.
It only duplicates playlist content, not the properties of the playlist (e.g. Autoplaylist).

Parameters

NameTypeDescription
playlistIndexnumber
nameoptional?string

A name for the new playlist. If the name is "" or undefined, the name of the source playlist will be used.

Returns

number —

Index of the created playlist.

method

EnsurePlaylistItemVisible

js/foo_uie_jsplitter.js:1163
EnsurePlaylistItemVisible(playlistIndex, playlistItemIndex)

Signals playlist viewers to display the track (e.g. by scrolling to it's position).

Parameters

NameTypeDescription
playlistIndexnumber
playlistItemIndexnumber
method

ExecutePlaylistDefaultAction

js/foo_uie_jsplitter.js:1171
ExecutePlaylistDefaultAction(playlistIndex, playlistItemIndex)

Starts playback by executing default doubleclick/enter action unless overridden by a lock to do something else.

Parameters

NameTypeDescription
playlistIndexnumber
playlistItemIndexnumber

Returns

boolean —

-1 on failure.

method

FindByGUID

js/foo_uie_jsplitter.js:1206
FindByGUID(guid)

Parameters

NameTypeDescription
guidstring

String representing GUID.

Returns

number —

Index of the found playlist on success, -1 on failure.

method

FindOrCreatePlaylist

js/foo_uie_jsplitter.js:1180
FindOrCreatePlaylist(name, unlocked)

Returns playlist index of the named playlist or creates a new one, if not found.
If a new playlist is created, the playlist index of that will be returned.

Parameters

NameTypeDescription
namestring
unlockedboolean

If true, locked playlists are ignored when looking for existing playlists. If false, the playlistIndex of any playlist with the matching name will be returned.

Returns

number —

Index of the found or created playlist.

method

FindPlaybackQueueItemIndex

js/foo_uie_jsplitter.js:1640
FindPlaybackQueueItemIndex(handle, playlistIndex, playlistItemIndex)

Parameters

NameTypeDescription
handleFbMetadbHandle
playlistIndexnumber
playlistItemIndexnumber

Returns

number —

Returns position in queue on success, -1 if track is not in queue.

method

FindPlaylist

js/foo_uie_jsplitter.js:1191
FindPlaylist(name)

Parameters

NameTypeDescription
namestring

Case insensitive.

Returns

number —

Index of the found playlist on success, -1 on failure.

method

FlushPlaybackQueue

js/foo_uie_jsplitter.js:1648
FlushPlaybackQueue()
method

GetGUID

js/foo_uie_jsplitter.js:1197
GetGUID(playlistIndex)

Parameters

NameTypeDescription
playlistIndexnumber

Returns

string

Example

console.log(plman.GetGUID(plman.ActivePlaylist));
method

GetPlaybackQueueContents

js/foo_uie_jsplitter.js:1651
GetPlaybackQueueContents()

Returns

Array<FbPlaybackQueueItem>

Example

let contents = plman.GetPlaybackQueueContents();
if (contents.length) {
    // access properties of first item
    console.log(contents[0].PlaylistIndex, contents[0].PlaylistItemIndex);
}
method

GetPlaybackQueueHandles

js/foo_uie_jsplitter.js:1663
GetPlaybackQueueHandles()

Returns

FbMetadbHandleList

Example

let handles = plman.GetPlaybackQueueHandles();
if (handles.Count > 0) {
   // use "Count" to determine if Playback Queue is active.
}
method

GetPlayingItemLocation

js/foo_uie_jsplitter.js:1212
GetPlayingItemLocation()

Retrieves playlist position of currently playing item.
On failure, the property FbPlayingItemLocation.IsValid will be set to false.

Returns

FbPlayingItemLocation
method

GetPlaylistFocusItemIndex

js/foo_uie_jsplitter.js:1220
GetPlaylistFocusItemIndex(playlistIndex)

Parameters

NameTypeDescription
playlistIndexnumber

Returns

number —

Returns -1 if nothing is selected

Example

let focus_item_index = plman.GetPlaylistFocusItemIndex(plman.ActivePlaylist); // 0 would be the first item
method

GetPlaylistItems

js/foo_uie_jsplitter.js:1229
GetPlaylistItems(playlistIndex)

Parameters

NameTypeDescription
playlistIndexnumber

Returns

FbMetadbHandleList

Example

let handle_list = plman.GetPlaylistItems(plman.PlayingPlaylist);
method

GetPlaylistLockedActions

js/foo_uie_jsplitter.js:1238
GetPlaylistLockedActions(playlistIndex)

Returns the list of blocked actions

Parameters

NameTypeDescription
playlistIndexnumber

Returns

Array<string> —

May contain the following:
- 'AddItems'
- 'RemoveItems'
- 'ReorderItems'
- 'ReplaceItems'
- 'RenamePlaylist'
- 'RemovePlaylist'
- 'ExecuteDefaultAction'

method

GetPlaylistLockName

js/foo_uie_jsplitter.js:1253
GetPlaylistLockName(playlistIndex)

Parameters

NameTypeDescription
playlistIndexnumber

Returns

?string —

name of lock owner if there is a lock, null otherwise

method

GetPlaylistName

js/foo_uie_jsplitter.js:1259
GetPlaylistName(playlistIndex)

Parameters

NameTypeDescription
playlistIndexnumber

Returns

string

Example

console.log(plman.GetPlaylistName(plman.ActivePlaylist));
method

GetPlaylistSelectedIndexes

js/foo_uie_jsplitter.js:1268
GetPlaylistSelectedIndexes(playlistIndex)

Parameters

NameTypeDescription
playlistIndexnumber

Returns

Array<number>

Example

let selected_indexes = plman.GetPlaylistSelectedIndexes(plman.ActivePlaylist);
method

GetPlaylistSelectedItems

js/foo_uie_jsplitter.js:1277
GetPlaylistSelectedItems(playlistIndex)

Parameters

NameTypeDescription
playlistIndexnumber

Returns

FbMetadbHandleList

Example

let selected_items = plman.GetPlaylistSelectedItems(plman.ActivePlaylist);
method

InsertPlaylistItems

js/foo_uie_jsplitter.js:1286
InsertPlaylistItems(playlistIndex, base, handle_list, select)

Parameters

NameTypeDescription
playlistIndexnumber
basenumber

Position in playlist

handle_listFbMetadbHandleList

Items to insert

select = falseoptionalboolean

If true then inserted items will be selected

Examples

<caption>Add all library tracks to the beginning of playlist.</caption>
let ap = plman.ActivePlaylist;
plman.InsertPlaylistItems(ap, 0, fb.GetLibraryItems());
<caption>Add all library tracks to end of playlist.</caption>
let ap = plman.ActivePlaylist;
plman.InsertPlaylistItems(ap, plman.PlaylistItemCount(ap), fb.GetLibraryItems());
method

InsertPlaylistItemsFilter

js/foo_uie_jsplitter.js:1302
InsertPlaylistItemsFilter(playlistIndex, base, handle_list, select)

Same as plman.InsertPlaylistItems except any duplicates contained in handle_list are removed.

Parameters

NameTypeDescription
playlistIndexnumber
basenumber

Position in playlist

handle_listFbMetadbHandleList

Items to insert

select = falseoptionalboolean

If true then inserted items will be selected
method

InvertSelection

js/foo_uie_jsplitter.js:1312
InvertSelection(playlistIndex)

Parameters

NameTypeDescription
playlistIndexnumber
method

IsAutoPlaylist

js/foo_uie_jsplitter.js:1317
IsAutoPlaylist(playlistIndex)

Parameters

NameTypeDescription
playlistIndexnumber

Returns

boolean
method

IsPlaylistItemSelected

js/foo_uie_jsplitter.js:1323
IsPlaylistItemSelected(playlistIndex, playlistItemIndex)

Parameters

NameTypeDescription
playlistIndexnumber
playlistItemIndexnumber

Returns

boolean
methoddeprecated

IsPlaylistLocked

js/foo_uie_jsplitter.js:1330
IsPlaylistLocked(playlistIndex)
Deprecated.

Note: returns true, if the playlist is an autoplaylist. To determine if a playlist is not an autoplaylist, but locked with something like foo_utils or foo_playlist_attributes, use with conjunction of plman.IsAutoPlaylist.
Deprecated: use plman.GetPlaylistLockedActions.

Parameters

NameTypeDescription
playlistIndexnumber

Returns

boolean
method

IsRedoAvailable

js/foo_uie_jsplitter.js:1343
IsRedoAvailable(playlistIndex)

Returns whether a redo restore point is available for specified playlist.
Related methods: plman.IsUndoAvailable, plman.Redo, plman.Undo, plman.UndoBackup

Parameters

NameTypeDescription
playlistIndexnumber

Returns

boolean
method

IsUndoAvailable

js/foo_uie_jsplitter.js:1353
IsUndoAvailable(playlistIndex)

Returns whether an undo restore point is available for specified playlist.
Related methods: plman.IsRedoAvailable, plman.Redo, plman.Undo, plman.UndoBackup

Parameters

NameTypeDescription
playlistIndexnumber

Returns

boolean
method

MovePlaylist

js/foo_uie_jsplitter.js:1363
MovePlaylist(from, to)

Parameters

NameTypeDescription
fromnumber
tonumber

Returns

boolean
method

MovePlaylistSelection

js/foo_uie_jsplitter.js:1370
MovePlaylistSelection(playlistIndex, delta)

Parameters

NameTypeDescription
playlistIndexnumber
deltanumber

Returns

boolean

Example

// Moves selected items to end of playlist.
plman.MovePlaylistSelection(plman.ActivePlaylist, plman.PlaylistItemCount(plman.ActivePlaylist));
method

MovePlaylistSelectionV2

js/foo_uie_jsplitter.js:1381
MovePlaylistSelectionV2(playlistIndex, new_pos)

Unlike plman.MovePlaylistSelection, this has full support for non-contiguous selections and all you have to do is supply the new position index.

Parameters

NameTypeDescription
playlistIndexnumber
new_posnumber
method

PlaylistItemCount

js/foo_uie_jsplitter.js:1389
PlaylistItemCount(playlistIndex)

Parameters

NameTypeDescription
playlistIndexnumber

Returns

number

Example

console.log(plman.PlaylistItemCount(plman.PlayingPlaylist)); // 12
method

Redo

js/foo_uie_jsplitter.js:1398
Redo(playlistIndex)

Reverts specified playlist to the next redo restore point and generates an undo restore point.
Note: revert operation may be not applied if the corresponding action is locked. Use plman.GetPlaylistLockedActions to check if there are any locks present.

Related methods: plman.IsRedoAvailable, plman.IsUndoAvailable, plman.Undo, plman.UndoBackup

Parameters

NameTypeDescription
playlistIndexnumber
method

RemoveItemFromPlaybackQueue

js/foo_uie_jsplitter.js:1674
RemoveItemFromPlaybackQueue(index)

Parameters

NameTypeDescription
indexnumber
method

RemoveItemsFromPlaybackQueue

js/foo_uie_jsplitter.js:1679
RemoveItemsFromPlaybackQueue(affectedItems)

Parameters

NameTypeDescription
affectedItemsArray<number>

Array like [1, 3, 5]
method

RemovePlaylist

js/foo_uie_jsplitter.js:1409
RemovePlaylist(playlistIndex)

Removes the specified playlist.
Note: if removing the active playlist, no playlist will be active after using this. You'll need to set it manually or use plman.RemovePlaylistSwitch instead.

Parameters

NameTypeDescription
playlistIndexnumber

Returns

boolean
method

RemovePlaylistSelection

js/foo_uie_jsplitter.js:1419
RemovePlaylistSelection(playlistIndex, crop)

Parameters

NameTypeDescription
playlistIndexnumber
crop = falseoptionalboolean

If true, then removes items that are NOT selected.

Examples

<Remove selected items from playlist>
plman.RemovePlaylistSelection(plman.ActivePlaylist);
<Remove items that are NOT selected>
plman.RemovePlaylistSelection(plman.ActivePlaylist, true);
method

RemovePlaylistSwitch

js/foo_uie_jsplitter.js:1431
RemovePlaylistSwitch(playlistIndex)

Removes the specified playlist.
This automatically sets another playlist as active if removing the active playlist.

Parameters

NameTypeDescription
playlistIndexnumber

Returns

boolean
method

RenamePlaylist

js/foo_uie_jsplitter.js:1440
RenamePlaylist(playlistIndex, name)

Parameters

NameTypeDescription
playlistIndexnumber
namestring

Returns

boolean
method

ReorderPlaylistItems

js/foo_uie_jsplitter.js:1447
ReorderPlaylistItems(playlistIndex, order)

Reorders all items in the specified playlist according to the supplied permutation.
The order array must contain exactly one entry for each playlist item. Each value specifies the old item index that should appear at the corresponding new position.
The array must:
- have the same length as the playlist item count
- contain only valid item indices
- contain each item index exactly once

Parameters

NameTypeDescription
playlistIndexnumber

zero-based playlist index

orderArray<number>

permutation describing the new playlist item order

Returns

boolean —

true if the playlist was reordered successfully

Throws

Error —

If playlistIndex is invalid or order is not a valid permutation

Example

// Changes the order from [A, B, C] to [C, A, B]
const success = ReorderPlaylistItems(0, [2, 0, 1])
method

ReplacePlaylistItem

js/foo_uie_jsplitter.js:1466
ReplacePlaylistItem(playlistIndex, playlistItemIndex, handle_or_handles)

Parameters

NameTypeDescription
playlistIndexnumber
playlistItemIndexnumber
handle_or_handlesFbMetadbHandle|FbMetadbHandleList
method

SelectQueryItems

js/foo_uie_jsplitter.js:1473
SelectQueryItems(playlistIndex, query)

This selects playlist items in a similar manner to the foobar2000 native playlist search.

Parameters

NameTypeDescription
playlistIndexnumber
querystring

Returns

Array<number> —

Array of selected indexes

method

SetActivePlaylistContext

js/foo_uie_jsplitter.js:1482
SetActivePlaylistContext()

Workaround so you can use the Edit menu or run fb.RunMainMenuCommand("Edit/Something...") when your panel has focus and a dedicated playlist viewer doesn't.

Example

plman.SetActivePlaylistContext(); // once on startup

function on_focus(is_focused) {
   if (is_focused) {
       plman.SetActivePlaylistContext(); // When the panel gets focus but not on every click
   }
}
method

SetPlaylistFocusItem

js/foo_uie_jsplitter.js:1497
SetPlaylistFocusItem(playlistIndex, playlistItemIndex)

Parameters

NameTypeDescription
playlistIndexnumber
playlistItemIndexnumber

Example

plman.SetPlaylistFocusItem(plman.ActivePlaylist, 0);
method

SetPlaylistFocusItemByHandle

js/foo_uie_jsplitter.js:1506
SetPlaylistFocusItemByHandle(playlistIndex, handle)

Parameters

NameTypeDescription
playlistIndexnumber
handleFbMetadbHandle

Example

let ap = plman.ActivePlaylist;
let handle = plman.GetPlaylistItems(ap)[1]; // 2nd item in playlist
plman.SetPlaylistFocusItemByHandle(ap, handle);
method

SetPlaylistLockedActions

js/foo_uie_jsplitter.js:1517
SetPlaylistLockedActions(playlistIndex, lockedActions)

Blocks requested actions.
Note: the lock can be changed only if there is no lock or if it's owned by foo_uie_jsplitter. The owner of the lock can be checked via plman.GetPlaylistLockName.

Parameters

NameTypeDescription
playlistIndexnumber
lockedActionsArray<string>

May contain the following:
- 'AddItems'
- 'RemoveItems'
- 'ReorderItems'
- 'ReplaceItems'
- 'RenamePlaylist'
- 'RemovePlaylist'
- 'ExecuteDefaultAction'
method

SetPlaylistSelection

js/foo_uie_jsplitter.js:1534
SetPlaylistSelection(playlistIndex, affectedItems, state)

Parameters

NameTypeDescription
playlistIndexnumber
affectedItemsArray<number>

An array of item indexes.

stateboolean

Example

// Selects first, third and fifth tracks in playlist. This does not affect other selected items.
plman.SetPlaylistSelection(plman.ActivePlaylist, [0, 2, 4], true);
method

SetPlaylistSelectionSingle

js/foo_uie_jsplitter.js:1545
SetPlaylistSelectionSingle(playlistIndex, playlistItemIndex, state)

Parameters

NameTypeDescription
playlistIndexnumber
playlistItemIndexnumber
stateboolean

Examples

// Deselects first playlist item. Only works when it is already selected!
plman.SetPlaylistSelectionSingle(plman.ActivePlaylist, 0, false);
let ap = plman.ActivePlaylist;
// Selects last item in playlist. This does not affect other selected items.
plman.SetPlaylistSelectionSingle(ap, plman.PlaylistItemCount(ap) - 1, true);
method

ShowAutoPlaylistUI

js/foo_uie_jsplitter.js:1561
ShowAutoPlaylistUI(playlistIndex)

Shows popup window letting you edit certain autoplaylist properties.
Before using, check if your playlist is an autoplaylist by using plman.IsAutoPlaylist;

Parameters

NameTypeDescription
playlistIndexnumber

Returns

boolean

Example

fb.ShowAutoPlaylistUI(plman.ActivePlaylist);
method

ShowPlaylistLockUI

js/foo_uie_jsplitter.js:1573
ShowPlaylistLockUI(playlistIndex)

Shows popup window letting you set various locks on playlist with specified index

Parameters

NameTypeDescription
playlistIndexnumber

Example

fb.ShowPlaylistLockUI(plman.ActivePlaylist);
method

SortByFormat

js/foo_uie_jsplitter.js:1583
SortByFormat(playlistIndex, pattern, selected_items_only)

Parameters

NameTypeDescription
playlistIndexnumber

Index of playlist to alter.

patternstring

Title formatting pattern to sort by. Set to "" to randomise the order of items.

selected_items_only = falseoptionalboolean

Returns

boolean —

true on success, false on failure (playlist locked etc).

method

SortByFormatV2

js/foo_uie_jsplitter.js:1591
SortByFormatV2(playlistIndex, pattern, direction)

Parameters

NameTypeDescription
playlistIndexnumber

Index of playlist to alter.

patternstring

Title formatting pattern to sort by.

direction = 1optionalnumber

1 - ascending
-1 - descending

Returns

boolean
method

SortPlaylistsByName

js/foo_uie_jsplitter.js:1601
SortPlaylistsByName(direction)

Parameters

NameTypeDescription
direction = 1optionalnumber

1 - ascending
-1 - descending
method

Undo

js/foo_uie_jsplitter.js:1608
Undo(playlistIndex)

Reverts specified playlist to the last undo restore point and generates a redo restore point.
Note: revert operation may be not applied if the corresponding action is locked. Use plman.GetPlaylistLockedActions to check if there are any locks present.

Related methods: plman.IsRedoAvailable, plman.IsUndoAvailable, plman.Redo, plman.UndoBackup

Parameters

NameTypeDescription
playlistIndexnumber
method

UndoBackup

js/foo_uie_jsplitter.js:1619
UndoBackup(playlistIndex)

Creates an undo restore point for the specified playlist. This will enable Edit>Undo menu item after calling other plman methods that change playlist content.
Note: this method should be called before performing modification to the playlist.

Related methods: plman.IsRedoAvailable, plman.IsUndoAvailable, plman.Redo, plman.Undo

Parameters

NameTypeDescription
playlistIndexnumber