plman

Functions for managing foobar2000 playlists.

Members

static ActivePlaylist :number

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

static PlaybackOrder :number

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

static PlayingPlaylist :number

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

static, readonly PlaylistCount :number

static, readonly PlaylistRecycler :FbPlaylistRecycler

A Recycle Bin for playlists.

Methods

static AddItemToPlaybackQueue(handle)

Parameters:
Name Type Description
handle FbMetadbHandle

static AddLocations(playlistIndex, paths, selectopt)

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)

Parameters:
Name Type Description
playlistIndex number
playlistItemIndex number

static ClearPlaylist(playlistIndex)

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

static ClearPlaylistSelection(playlistIndex)

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

static CreateAutoPlaylist(playlistIndex, name, query, sortopt, flagsopt) → {number}

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}

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}

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)

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}

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}

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}

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}

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

static FlushPlaybackQueue()

static GetPlaybackQueueContents() → {Array.<FbPlaybackQueueItem>}

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}

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

static GetPlayingItemLocation() → {FbPlayingItemLocation}

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

static GetPlaylistFocusItemIndex(playlistIndex) → {number}

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}

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

static GetPlaylistName(playlistIndex) → {string}

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

static GetPlaylistSelectedItems(playlistIndex) → {FbMetadbHandleList}

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

static InsertPlaylistItems(playlistIndex, base, handle_list, selectopt)

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)

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}

Parameters:
Name Type Description
playlistIndex number
Returns:
boolean

static IsPlaylistItemSelected(playlistIndex, playlistItemIndex) → {boolean}

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

static IsPlaylistLocked(playlistIndex) → {boolean}

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

static MovePlaylist(from, to) → {boolean}

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

static MovePlaylistSelection(playlistIndex, delta) → {boolean}

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}

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

static RemoveItemFromPlaybackQueue(index)

Parameters:
Name Type Description
index number

static RemoveItemsFromPlaybackQueue(affectedItems)

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

static RemovePlaylist(playlistIndex) → {boolean}

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)

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}

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}

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

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

static SetPlaylistFocusItem(playlistIndex, playlistItemIndex)

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

static SetPlaylistFocusItemByHandle(playlistIndex, handle)

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 SetPlaylistSelection(playlistIndex, affectedItems, state)

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)

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}

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}

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}

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)

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

static UndoBackup(playlistIndex)

Saves playlist's current state: 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.
Parameters:
Name Type Description
playlistIndex number