fb

Functions for controlling foobar2000 and accessing it's data.

Members

static AlwaysOnTop :boolean

Example
fb.AlwaysOnTop = !fb.AlwaysOnTop; // Toggles the current value.

static, readonly ComponentPath :string

Example
console.log(fb.ComponentPath); // C:\Users\User\AppData\Roaming\foobar2000\user-components\foo_spider_monkey_panel\

static CursorFollowPlayback :boolean

static, readonly FoobarPath :string

static, readonly IsPaused :boolean

static, readonly IsPlaying :boolean

static PlaybackFollowCursor :boolean

static, readonly PlaybackLength :float

Examples
console.log(fb.PlaybackLength); // 322.843414966166
console.log(Math.round(fb.PlaybackLength)); // 323

static PlaybackTime :float

Example
fb.PlaybackTime = 60; // Jumps to the 1 minute mark.

static, readonly ProfilePath :string

static ReplaygainMode :number

0 - None
1 - Track
2 - Album
3 - Track/Album by Playback Order (only available in foobar2000 v1.3.8 and later)

static StopAfterCurrent :boolean

Example
fb.StopAfterCurrent = !fb.StopAfterCurrent; // Toggles the current value.

static, readonly Version :string

Example
console.log(fb.Version)
// 1.4.1

static Volume :float

Example
fb.Volume = 0; // Sets the volume to max. -100 is the minimum.

Methods

static AcquireUiSelectionHolder() → {FbUiSelectionHolder}

static AddDirectory()

static AddFiles()

static CheckClipboardContents() → {boolean}

Checks Clipboard contents are handles or a file selection from Windows Explorer. Use in conjunction with fb.GetClipboardContents.
Returns:
boolean

static ClearPlaylist()

Clears active playlist.
If you wish to clear a specific playlist, use plman.ClearPlaylist(playlistIndex).

static CopyHandleListToClipboard(handle_list) → {boolean}

Note: items can then be pasted in other playlist viewers or in Windows Explorer as files.
Parameters:
Name Type Description
handle_list FbMetadbHandleList
Returns:
boolean
Examples

Copy playlist items

let handle_list = plman.GetPlaylistSelectedItems(plman.ActivePlaylist);
fb.CopyHandleListToClipboard(handle_list);

Cut playlist items

let ap = plman.ActivePlaylist;
if (!plman.IsPlaylistLocked(ap)) {
   let handle_list = plman.GetPlaylistSelectedItems(ap);
   if (fb.CopyHandleListToClipboard(handle_list)) {
       plman.UndoBackup(ap);
       plman.RemovePlaylistSelection(ap);
   }
 }

static CreateContextMenuManager() → {ContextMenuManager}

Example
// See `samples/basic/MainMenuManager All-In-One.js`, `samples/basic/Menu Sample.js`

static CreateHandleList() → {FbMetadbHandleList}

Returns an empty handle list.
Deprecated: use FbMetadbHandleList constructor instead.
Deprecated:
  • Yes

static CreateMainMenuManager() → {MainMenuManager}

Returns:
MainMenuManager
Example
// See `samples/basic/MainMenuManager All-In-One.js`, `samples/basic/Menu Sample.js`

static CreateProfiler(nameopt) → {FbProfiler}

Parameters:
Name Type Attributes Default Description
name string <optional>
'' Will be shown in console when used with FbProfiler#Print method.
Returns:
FbProfiler

static DoDragDrop(window_id, handle_list, effect, optionsopt) → {number}

Invokes drag-n-drop operation (see https://docs.microsoft.com/en-us/windows/win32/api/ole2/nf-ole2-dodragdrop).

Quick tips:
- If you need only to drag from your panel with copy (i.e. without physically moving them): use only fb.DoDragDrop(handles, DROPEFFECT_COPY | DROPEFFECT_LINK).
- If you need only to receive drop to your panel with copy: handle `on_drop_*()` callbacks, while setting action.effect argument to (DROPEFFECT_COPY | DROPEFFECT_LINK).

Full drag-n-drop interface description:
- Drag-n-drop interface is based on Microsoft IDropSource and IDropTarget interfaces, so a lot of info (including examples) could be gathered from MSDN (IDropSource, IDropTarget, DoDragDrop, DROPEFFECT).
- Drag operation is started with DoDragDrop (whether it is called by your panel, or externally) with okEffects argument supplied.
- DoDragDrop blocks code execution until the drag operation is finished (callbacks will be called properly though). It returns effect from Action.Effect from on_drag_drop after completion.
- (Spider Monkey Panel specific) Drag operation is canceled when any mouse button is pressed.
- (Spider Monkey Panel specific) All mouse callbacks are suppressed during drag operation (including on_mouse_lbtn_up, but excluding on_mouse_mbtn_up and on_mouse_rbtn_up).
- Every drag callback receives Action argument. Action.Effect contains okEffects from DoDragDrop call. Action.Effect should be changed to the desired effect in the callback. If the returned Action.Effect was not in okEffects or is equal to DROPEFFECT_NONE (=== 0), then drop will be denied: cursor icon will be changed, on_drag_drop won't be called after releasing lmbtn, on_drag_leave will be called instead.
- DROPEFFECT_LINK should be used as fallback in case effect argument does not have DROPEFFECT_COPY (===1), since some external drops only allow DROPEFFECT_LINK effect.
- Changing effect on key modifiers is nice (to be in line with native Windows behaviour): see the example below.
Parameters:
Name Type Attributes Description
window_id number unused
handle_list FbMetadbHandleList
effect number Allowed effects.
options object <optional>
Customization options for the data displayed in the drag window.
Properties
Name Type Attributes Default Description
show_text boolean <optional>
true If true, will add track count text.
use_album_art boolean <optional>
true If true, will use album art of the focused item from dragged tracks (if available)
use_theming boolean <optional>
true If true, will use Windows drag window style. Album art and custom image are resized to fit when Windows style is active.
custom_image GdiBitmap <optional>
<nullable>
Custom dragging image. Will be also displayed if use_album_art is true, but there is no album art available.
Returns:
number - Effect that was returned in on_drag_drop.
Example
// See `samples/basic/DragnDrop.js`

static Exit()

static GetClipboardContents(window_idopt) → {FbMetadbHandleList}

Note: clipboard contents can be handles copied to the clipboard in other components, from fb.CopyHandleListToClipboard or a file selection, from Windows Explorer and etc.

Performance note: validate clipboard content with fb.CheckClipboardContents before calling this method.
Parameters:
Name Type Attributes Default Description
window_id number <optional>
0 unused
Example
function on_mouse_rbtn_up(x, y) {
   let ap = plman.ActivePlaylist;
   let menu = window.CreatePopupMenu();
   menu.AppendMenuItem(!plman.IsPlaylistLocked(ap) && fb.CheckClipboardContents() ? MF_STRING : MF_GRAYED, 1, "Paste"); // see Flags.js for MF_* definitions
   let idx = menu.TrackPopupMenu(x, y);
   if (idx == 1) {
       let handle_list  = fb.GetClipboardContents();
       plman.InsertPlaylistItems(ap, plman.PlaylistItemCount(ap), handle_list );
   }
   return true;
}

static GetDSPPresets() → {string}

Available only in foobar2000 v1.4 and above. Throws a script error on v1.3. *
Returns a JSON array in string form so you need to use JSON.parse() on the result.
Returns:
string
Example
let str = fb.GetDSPPresets();
let arr = JSON.parse(str);
console.log(JSON.stringify(arr, null, 4));
// [
//     {
//         "active": false,
//         "name": "High Filter"
//     },
//     {
//         "active": true,
//         "name": "R128 Compressor"
//     },
//     {
//         "active": false,
//         "name": "7.1 upmix"
//     }
// ]

static GetFocusItem(forceopt) → {FbMetadbHandle}

Parameters:
Name Type Attributes Default Description
force boolean <optional>
true When true, it will use the first item of the active playlist if it is unable to get the focus item.
Returns:
FbMetadbHandle

static GetLibraryItems() → {FbMetadbHandleList}

Returns all Media Library items as a handle list.

static GetLibraryRelativePath(handle) → {string}

Note: do not use this while looping through a handle list. Use FbMetadbHandleList#GetLibraryRelativePaths instead.

Returns an empty string when used on track not in Media Library
Parameters:
Name Type Description
handle FbMetadbHandle
Returns:
string
Example
// The foobar2000 Media Library is configured to watch "D:\Music" and the
// path of the now playing item is "D:\Music\Albums\Artist\Some Album\Some Song.flac"
let handle = fb.GetNowPlaying();
console.log(fb.GetLibraryRelativePath(handle)); // Albums\Artist\Some Album\Some Song.flac*

static GetNowPlaying()nullable {FbMetadbHandle}

Get handle of the now playing track.
Returns:
FbMetadbHandle - null, if nothing is being played.

static GetOutputDevices() → {string}

Available only in foobar2000 v1.4 and above. Throws a script error on v1.3. *
Returns a JSON array in string form so you need to use JSON.parse() on the result.
Returns:
string
Example
let str = fb.GetOutputDevices();
let arr = JSON.parse(str);
console.log(JSON.stringify(arr, null, 4));
// [
//     {
//         "active": false,
//         "device_id": "{5243F9AD-C84F-4723-8194-0788FC021BCC}",
//         "name": "Null Output",
//         "output_id": "{EEEB07DE-C2C8-44C2-985C-C85856D96DA1}"
//     },
//     {
//         "active": true,
//         "device_id": "{00000000-0000-0000-0000-000000000000}",
//         "name": "Primary Sound Driver",
//         "output_id": "{D41D2423-FBB0-4635-B233-7054F79814AB}"
//     },
//     {
//         "active": false,
//         "device_id": "{1C4EC038-97DB-48E7-9C9A-05FDED46847B}",
//         "name": "Speakers (Sound Blaster Z)",
//         "output_id": "{D41D2423-FBB0-4635-B233-7054F79814AB}"
//     },
//     {
//         "active": false,
//         "device_id": "{41B86272-3D6C-4A5A-8907-4FE7EBE39E7E}",
//         "name": "SPDIF-Out (Sound Blaster Z)",
//         "output_id": "{D41D2423-FBB0-4635-B233-7054F79814AB}"
//     },
//     {
//         "active": false,
//         "device_id": "{9CDC0FAE-2870-4AFA-8287-E86099D69076}",
//         "name": "3 - BenQ BL3200 (AMD High Definition Audio Device)",
//         "output_id": "{D41D2423-FBB0-4635-B233-7054F79814AB}"
//     }
// ]
// As you can see, only one of the items in the array has "active"
// set to true so that is the device you'd want to display the name of
// or mark as selected in a menu.

static GetQueryItems(handle_list, query) → {FbMetadbHandleList}

Note: use try/catch to handle invalid queries. An empty handle list will be returned if the query is valid but there are no results.
Parameters:
Name Type Description
handle_list FbMetadbHandleList
query string
Returns:
FbMetadbHandleList - Unsorted results.
Examples
let a = fb.GetQueryItems(plman.GetPlaylistItems(plman.ActivePlaylist), "rating IS 5");
let b = fb.GetQueryItems(fb.GetLibraryItems(), "rating IS 5");

static GetSelection()nullable {FbMetadbHandle}

Gets now playing or selected item according to settings in "File>Preferences>Display>Selection viewers".
Returns:
FbMetadbHandle

static GetSelections(flagsopt) → {FbMetadbHandleList}

Works like fb.GetSelection, but returns a handle list.
Parameters:
Name Type Attributes Default Description
flags number <optional>
0 1 - no now playing

static GetSelectionType() → {number}

Retrieves what the selection type is.
Returns:
number - Possible values:
0 - undefined (no item)
1 - active_playlist_selection
2 - caller_active_playlist
3 - playlist_manager
4 - now_playing
5 - keyboard_shortcut_list
6 - media_library_viewer

static IsLibraryEnabled() → {boolean}

Returns:
boolean

static IsMainMenuCommandChecked(command) → {boolean}

Performance note: don't use in `on_paint`.
Parameters:
Name Type Description
command string Path to main menu item
Returns:
boolean - true, if the item is checked.
Example
fb.RunMainMenuCommand("Playback/Scrobble Tracks"); // available with foo_scrobble

static IsMetadbInMediaLibrary(handle) → {boolean}

Parameters:
Name Type Description
handle FbMetadbHandle
Returns:
boolean
Example
let np = fb.GetNowplaying();
console.log(fb.IsMetadbInMediaLibrary(np)); // If false, playing track is not in Media Library.

static LoadPlaylist()

Loads playlist from file. Equivalent to `File`>`Load Playlist...`.

static Next()

static Pause()

static Play()

static PlayOrPause()

static Prev()

static Random()

static RunContextCommand(command, flagsopt) → {boolean}

Shows context menu for currently played track.
Parameters:
Name Type Attributes Default Description
command string
flags number <optional>
0 0 - default (depends on whether SHIFT key is pressed, flag_view_reduced or flag_view_full is selected)
4 - flag_view_reduced
8 - flag_view_full. This can be useful if you need to run context commands the user may have hidden using File>Preferences>Display>Context Menu
Returns:
boolean
Example
fb.RunContextCommand("Properties");

static RunContextCommandWithMetadb(command, handle_or_handle_list, flagsopt) → {boolean}

Shows context menu for supplied tracks.
Parameters:
Name Type Attributes Description
command string
handle_or_handle_list FbMetadbHandle | FbMetadbHandleList Handles on which to apply context menu
flags number <optional>
Same flags as fb.RunContextCommand
Returns:
boolean

static RunMainMenuCommand(command) → {boolean}

Parameters:
Name Type Description
command string
Returns:
boolean
Example
fb.RunMainMenuCommand("File/Add Location...");

static SavePlaylist()

static SetDSPPreset(idx)

Available only in foobar2000 v1.4 and above. Throws a script error on v1.3.
See fb.GetDSPPresets.
Parameters:
Name Type Description
idx number
Example
let str = fb.GetDSPPresets();
let arr = JSON.parse(str);
let idx; // find the required DSP from `arr` and assign it to `idx`
fb.SetDSPPreset(idx);

static SetOutputDevice(output, device)

Available only in foobar2000 v1.4 and above. Throws a script error on v1.3.
See fb.GetOutputDevices.
Parameters:
Name Type Description
output string
device string
Example
// To actually change device, you'll need the device_id and output_id
// and use them with fb.SetOutputDevice.
let str = fb.GetOutputDevices();
let arr = JSON.parse(str);
// Assuming same list from above, switch output to the last device.
fb.SetOutputDevice(arr[4].output_id, arr[4].device_id);

static ShowConsole()

static ShowLibrarySearchUI(query)

Opens the Library>Search window populated with the query you set.
Parameters:
Name Type Description
query string

static ShowPopupMessage(message, titleopt)

Parameters:
Name Type Attributes Default Description
message string
title string <optional>
'Spider Monkey Panel'

static ShowPreferences()

static Stop()

static TitleFormat(expression) → {FbTitleFormat}

Performance note: if you use the same query frequently, try caching FbTitleFormat object (by storing it somewhere), instead of creating it every time.
Parameters:
Name Type Description
expression string
Returns:
FbTitleFormat

static VolumeDown()

static VolumeMute()

static VolumeUp()