plman

Functions for managing foobar2000 playlists.

Members

static ActivePlaylist :number
js/foo_spider_monkey_panel.js, line 877

-1 if there is no active playlist.
Examples
console.log(plman.ActivePlaylist);
plman.ActivePlaylist = 1; // Switches to 2nd playlist.

static PlaybackOrder :number
js/foo_spider_monkey_panel.js, line 890

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

static PlayingPlaylist :number
js/foo_spider_monkey_panel.js, line 901

-1 if there is no playing playlist.
Example
console.log(plman.PlayingPlaylist);

static, readonly PlaylistCount :number
js/foo_spider_monkey_panel.js, line 907

static, readonly PlaylistRecycler :FbPlaylistRecycler
js/foo_spider_monkey_panel.js, line 915

A Recycle Bin for playlists.

Methods

static AddItemToPlaybackQueue(handle)
js/foo_spider_monkey_panel.js, line 1372

Parameters:
Name Type Description
handle FbMetadbHandle

static AddLocations(playlistIndex, paths, selectopt)
js/foo_spider_monkey_panel.js, line 931

This operation is asynchronous and may take some time to complete if it's a large array.
Parameters:
Name Type Attributes Default Description
playlistIndex number
paths Array.<string> An array of files/URLs
select boolean <optional>
 false 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.

static AddPlaylistItemToPlaybackQueue(playlistIndex, playlistItemIndex)
js/foo_spider_monkey_panel.js, line 1378

Parameters:
Name Type Description
playlistIndex number
playlistItemIndex number

static ClearPlaylist(playlistIndex)
js/foo_spider_monkey_panel.js, line 939

Parameters:
Name Type Description
playlistIndex number
Example
plman.ClearPlaylist(plman.PlayingPlaylist);

static ClearPlaylistSelection(playlistIndex)
js/foo_spider_monkey_panel.js, line 947

Parameters:
Name Type Description
playlistIndex number
Example
plman.ClearPlaylistSelection(plman.ActivePlaylist);

static CreateAutoPlaylist(playlistIndex, name, query, sortopt, flagsopt) → {number}
js/foo_spider_monkey_panel.js, line 957

Parameters:
Name Type Attributes Default Description
playlistIndex number
name string Name for the new autoplaylist.
query string Title formatting pattern for forming the playlist content.
sort string <optional>
 '' Title formatting pattern for sorting.
flags number <optional>
 0 1 - when set, will keep the autoplaylist sorted and prevent user from reordering it.
Returns:
number - Index of the created playlist.

static CreatePlaylist(playlistIndex, name) → {number}
js/foo_spider_monkey_panel.js, line 972

Parameters:
Name Type Description
playlistIndex number
name string
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');

static DuplicatePlaylist(playlistIndex, nameopt, nullable) → {number}
js/foo_spider_monkey_panel.js, line 982

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:
Name Type Attributes Description
playlistIndex number
name string <optional>
<nullable>
 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.

static EnsurePlaylistItemVisible(playlistIndex, playlistItemIndex)
js/foo_spider_monkey_panel.js, line 990

Signals playlist viewers to display the track (e.g. by scrolling to it's position).
Parameters:
Name Type Description
playlistIndex number
playlistItemIndex number

static ExecutePlaylistDefaultAction(playlistIndex, playlistItemIndex) → {boolean}
js/foo_spider_monkey_panel.js, line 999

Starts playback by executing default doubleclick/enter action unless overridden by a lock to do something else.
Parameters:
Name Type Description
playlistIndex number
playlistItemIndex number
Returns:
boolean - -1 on failure.

static FindOrCreatePlaylist(name, unlocked) → {number}
js/foo_spider_monkey_panel.js, line 1010

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:
Name Type Description
name string
unlocked boolean 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.

static FindPlaybackQueueItemIndex(handle, playlistIndex, playlistItemIndex) → {number}
js/foo_spider_monkey_panel.js, line 1386

Parameters:
Name Type Description
handle FbMetadbHandle
playlistIndex number
playlistItemIndex number
Returns:
number - Returns position in queue on success, -1 if track is not in queue.

static FindPlaylist(name) → {number}
js/foo_spider_monkey_panel.js, line 1016

Parameters:
Name Type Description
name string Case insensitive.
Returns:
number - Index of the found playlist on success, -1 on failure.

static FlushPlaybackQueue()
js/foo_spider_monkey_panel.js, line 1389

static GetPlaybackQueueContents() → {Array.<FbPlaybackQueueItem>}
js/foo_spider_monkey_panel.js, line 1401

Returns:
Array.<FbPlaybackQueueItem>
Example
let contents = plman.GetPlaybackQueueContents();
if (contents.length) {
    // access properties of first item
    console.log(contents[0].PlaylistIndex, contents[0].PlaylistItemIndex);
}

static GetPlaybackQueueHandles() → {FbMetadbHandleList}
js/foo_spider_monkey_panel.js, line 1412

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

static GetPlayingItemLocation() → {FbPlayingItemLocation}
js/foo_spider_monkey_panel.js, line 1024

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

static GetPlaylistFocusItemIndex(playlistIndex) → {number}
js/foo_spider_monkey_panel.js, line 1033

Parameters:
Name Type Description
playlistIndex number
Returns:
number - Returns -1 if nothing is selected
Example
let focus_item_index = plman.GetPlaylistFocusItemIndex(plman.ActivePlaylist); // 0 would be the first item

static GetPlaylistItems(playlistIndex) → {FbMetadbHandleList}
js/foo_spider_monkey_panel.js, line 1042

Parameters:
Name Type Description
playlistIndex number
Returns:
FbMetadbHandleList
Example
let handle_list = plman.GetPlaylistItems(plman.PlayingPlaylist);

static GetPlaylistLockedActions(playlistIndex) → {Array.<string>}
js/foo_spider_monkey_panel.js, line 1057

Returns the list of blocked actions
Parameters:
Name Type Description
playlistIndex number
Returns:
Array.<string> - May contain the following:
- 'AddItems'
- 'RemoveItems'
- 'ReorderItems'
- 'ReplaceItems'
- 'RenamePlaylist'
- 'RemovePlaylist'
- 'ExecuteDefaultAction'

static GetPlaylistLockName(playlistIndex) → nullable {string}
js/foo_spider_monkey_panel.js, line 1063

Parameters:
Name Type Description
playlistIndex number
Returns:
string - name of lock owner if there is a lock, null otherwise

static GetPlaylistName(playlistIndex) → {string}
js/foo_spider_monkey_panel.js, line 1072

Parameters:
Name Type Description
playlistIndex number
Returns:
string
Example
console.log(plman.GetPlaylistName(plman.ActivePlaylist));

static GetPlaylistSelectedItems(playlistIndex) → {FbMetadbHandleList}
js/foo_spider_monkey_panel.js, line 1081

Parameters:
Name Type Description
playlistIndex number
Returns:
FbMetadbHandleList
Example
let selected_items = plman.GetPlaylistSelectedItems(plman.ActivePlaylist);

static InsertPlaylistItems(playlistIndex, base, handle_list, selectopt)
js/foo_spider_monkey_panel.js, line 1097

Parameters:
Name Type Attributes Default Description
playlistIndex number
base number Position in playlist
handle_list FbMetadbHandleList Items to insert
select boolean <optional>
 false If true then inserted items will be selected
Examples

Add all library tracks to the beginning of playlist.

let ap = plman.ActivePlaylist;
plman.InsertPlaylistItems(ap, 0, fb.GetLibraryItems());

Add all library tracks to end of playlist.

let ap = plman.ActivePlaylist;
plman.InsertPlaylistItems(ap, plman.PlaylistItemCount(ap), fb.GetLibraryItems());

static InsertPlaylistItemsFilter(playlistIndex, base, handle_list, selectopt)
js/foo_spider_monkey_panel.js, line 1107

Same as plman.InsertPlaylistItems except any duplicates contained in handle_list are removed.
Parameters:
Name Type Attributes Default Description
playlistIndex number
base number Position in playlist
handle_list FbMetadbHandleList Items to insert
select boolean <optional>
 false If true then inserted items will be selected

static IsAutoPlaylist(playlistIndex) → {boolean}
js/foo_spider_monkey_panel.js, line 1113

Parameters:
Name Type Description
playlistIndex number
Returns:
boolean

static IsPlaylistItemSelected(playlistIndex, playlistItemIndex) → {boolean}
js/foo_spider_monkey_panel.js, line 1120

Parameters:
Name Type Description
playlistIndex number
playlistItemIndex number
Returns:
boolean

static IsPlaylistLocked(playlistIndex) → {boolean}
js/foo_spider_monkey_panel.js, line 1133

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:
Name Type Description
playlistIndex number
Returns:
boolean
Deprecated:
  • Yes

static IsRedoAvailable(playlistIndex) → {boolean}
js/foo_spider_monkey_panel.js, line 1143

Returns whether a redo restore point is available for specified playlist.
Related methods: plman.IsUndoAvailable, plman.Redo, plman.Undo, plman.UndoBackup
Parameters:
Name Type Description
playlistIndex number
Returns:
boolean

static IsUndoAvailable(playlistIndex) → {boolean}
js/foo_spider_monkey_panel.js, line 1153

Returns whether an undo restore point is available for specified playlist.
Related methods: plman.IsRedoAvailable, plman.Redo, plman.Undo, plman.UndoBackup
Parameters:
Name Type Description
playlistIndex number
Returns:
boolean

static MovePlaylist(from, to) → {boolean}
js/foo_spider_monkey_panel.js, line 1160

Parameters:
Name Type Description
from number
to number
Returns:
boolean

static MovePlaylistSelection(playlistIndex, delta) → {boolean}
js/foo_spider_monkey_panel.js, line 1171

Parameters:
Name Type Description
playlistIndex number
delta number
Returns:
boolean
Example
// Moves selected items to end of playlist.
plman.MovePlaylistSelection(plman.ActivePlaylist, plman.PlaylistItemCount(plman.ActivePlaylist));

static PlaylistItemCount(playlistIndex) → {number}
js/foo_spider_monkey_panel.js, line 1180

Parameters:
Name Type Description
playlistIndex number
Returns:
number
Example
console.log(plman.PlaylistItemCount(plman.PlayingPlaylist)); // 12

static Redo(playlistIndex)
js/foo_spider_monkey_panel.js, line 1191

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:
Name Type Description
playlistIndex number

static RemoveItemFromPlaybackQueue(index)
js/foo_spider_monkey_panel.js, line 1417

Parameters:
Name Type Description
index number

static RemoveItemsFromPlaybackQueue(affectedItems)
js/foo_spider_monkey_panel.js, line 1422

Parameters:
Name Type Description
affectedItems Array.<number> Array like [1, 3, 5]

static RemovePlaylist(playlistIndex) → {boolean}
js/foo_spider_monkey_panel.js, line 1201

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:
Name Type Description
playlistIndex number
Returns:
boolean

static RemovePlaylistSelection(playlistIndex, cropopt)
js/foo_spider_monkey_panel.js, line 1213

Parameters:
Name Type Attributes Default Description
playlistIndex number
crop boolean <optional>
 false 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);

static RemovePlaylistSwitch(playlistIndex) → {boolean}
js/foo_spider_monkey_panel.js, line 1222

Removes the specified playlist.
This automatically sets another playlist as active if removing the active playlist.
Parameters:
Name Type Description
playlistIndex number
Returns:
boolean

static RenamePlaylist(playlistIndex, name) → {boolean}
js/foo_spider_monkey_panel.js, line 1229

Parameters:
Name Type Description
playlistIndex number
name string
Returns:
boolean

static SetActivePlaylistContext()
js/foo_spider_monkey_panel.js, line 1244

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
   }
}

static SetPlaylistFocusItem(playlistIndex, playlistItemIndex)
js/foo_spider_monkey_panel.js, line 1253

Parameters:
Name Type Description
playlistIndex number
playlistItemIndex number
Example
plman.SetPlaylistFocusItem(plman.ActivePlaylist, 0);

static SetPlaylistFocusItemByHandle(playlistIndex, handle)
js/foo_spider_monkey_panel.js, line 1264

Parameters:
Name Type Description
playlistIndex number
handle FbMetadbHandle
Example
let ap = plman.ActivePlaylist;
let handle = plman.GetPlaylistItems(ap)[1]; // 2nd item in playlist
plman.SetPlaylistFocusItemByHandle(ap, handle);

static SetPlaylistLockedActions(playlistIndex, lockedActions)
js/foo_spider_monkey_panel.js, line 1282

Blocks requested actions.
Note: the lock can be changed only if there is no lock or if it's owned by `foo_spider_monkey_panel`. The owner of the lock can be checked via plman.GetPlaylistLockName.
Parameters:
Name Type Description
playlistIndex number
lockedActions Array.<string> May contain the following:
- 'AddItems'
- 'RemoveItems'
- 'ReorderItems'
- 'ReplaceItems'
- 'RenamePlaylist'
- 'RemovePlaylist'
- 'ExecuteDefaultAction'

static SetPlaylistSelection(playlistIndex, affectedItems, state)
js/foo_spider_monkey_panel.js, line 1293

Parameters:
Name Type Description
playlistIndex number
affectedItems Array.<number> An array of item indexes.
state boolean
Example
// Selects first, third and fifth tracks in playlist. This does not affect other selected items.
plman.SetPlaylistSelection(plman.ActivePlaylist, [0, 2, 4], true);

static SetPlaylistSelectionSingle(playlistIndex, playlistItemIndex, state)
js/foo_spider_monkey_panel.js, line 1309

Parameters:
Name Type Description
playlistIndex number
playlistItemIndex number
state boolean
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);

static ShowAutoPlaylistUI(playlistIndex) → {boolean}
js/foo_spider_monkey_panel.js, line 1321

Shows popup window letting you edit certain autoplaylist properties.
Before using, check if your playlist is an autoplaylist by using plman.IsAutoPlaylist;
Parameters:
Name Type Description
playlistIndex number
Returns:
boolean
Example
fb.ShowAutoPlaylistUI(plman.ActivePlaylist);

static SortByFormat(playlistIndex, pattern, selected_items_onlyopt) → {boolean}
js/foo_spider_monkey_panel.js, line 1329

Parameters:
Name Type Attributes Default Description
playlistIndex number Index of playlist to alter.
pattern string Title formatting pattern to sort by. Set to "" to randomise the order of items.
selected_items_only boolean <optional>
 false
Returns:
boolean - true on success, false on failure (playlist locked etc).

static SortByFormatV2(playlistIndex, pattern, directionopt) → {boolean}
js/foo_spider_monkey_panel.js, line 1339

Parameters:
Name Type Attributes Default Description
playlistIndex number Index of playlist to alter.
pattern string Title formatting pattern to sort by.
direction number <optional>
 1 1 - ascending
-1 - descending
Returns:
boolean

static SortPlaylistsByName(directionopt)
js/foo_spider_monkey_panel.js, line 1346

Parameters:
Name Type Attributes Default Description
direction number <optional>
 1 1 - ascending
-1 - descending

static Undo(playlistIndex)
js/foo_spider_monkey_panel.js, line 1357

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:
Name Type Description
playlistIndex number

static UndoBackup(playlistIndex)
js/foo_spider_monkey_panel.js, line 1367

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:
Name Type Description
playlistIndex number