Functions for controlling foobar2000 and accessing it's data.

It can be used for displaying the volume from UPnP devices.
It will return a value of -1 when using a normal device and that also indicates that fb.Volume is writable.
When a custom volume control is active, you can not use fb.Volume and must use fb.VolumeUp() / fb.VolumeDown() / fb.VolumeMute().

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

Converts one or more paths to a list of metadb_handles.
The function returns immediately; specified callback on_locations_added receives results when the operation has completed.

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

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

Note: items can then be pasted in other playlist viewers or in Windows Explorer as files.

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

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.

Note: due to the asynchronous nature of event handling, fb.DoDragDrop() might exit before on_drag_drop callback is triggered when dropping data on the same panel as the one that had a call to fb.DoDragDrop().

Related callbacks: on_drag_enter, on_drag_drop, on_drag_over, on_drag_leave

For future development purposes (e.g. verbose console output)

Returns all main menu items recursivley.
It is a JSON array in string form so you need to use JSON.parse on the result.
Every item of the array is object with the following properties:
Checked: boolean
Disabled: boolean
FullPath: string, the same full path you'd supply to fb.RunMainMenuCommand
HiddenByDefault: boolean
Radio: boolean
Type: string ("Fixed" or "Dynamic")
Visible: boolean

Returns array of active DSPs names.

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.

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.
Related methods: fb.SetDSPPreset.

Returns all Media Library items as a handle list.

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

Returns an empty string when used on track not in Media Library

Get handle of the now playing track.

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.
Related methods: fb.SetOutputDevice.

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.

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

Works like fb.GetSelection, but returns a handle list.

Retrieves what the selection type is.

Returns true if the library has already been initialized by this time

Performance note: don't use in on_paint.

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

Registers a main menu item that will be displayed under main menu > File > JSplitter > Script commands > {Current panel name}.
Being main menu item means you can bind it to global keyboard shortcuts, standard toolbar buttons, panel stack splitter buttons and etc.
Execution of the correspoding menu item will trigger on_main_menu_dynamic callback.

Note: JSplitter uses a combination of panel name and command id to identify and bind the command. Hence all corresponding binds will fail if the id or the panel name is changed. This also means that collision WILL occur if there are two panels with the same name.

Related methods: fb.UnregisterMainMenuCommand
Related callbacks: on_main_menu_dynamic

Shows context menu for currently played track.

Shows context menu for supplied tracks.

Available only in foobar2000 v1.4 and above. Throws a script error on v1.3.

Related methods: fb.GetDSPPresets.

Available only in foobar2000 v1.4 and above. Throws a script error on v1.3.

Related methods: fb.GetOutputDevices.

Shows foobar2000 console window or close it (if show=false).

Opens the Library>Search window populated with the query you set.

Opens the image viewer built in to foobar2000 and shows image file specified by image_path

Opens the "Playlist Search" window

Performance note: if you use the same query frequently, try caching FbTitleFormat object (by storing it somewhere), instead of creating it every time.

Unregisters a main menu item.

Related methods: fb.RegisterMainMenuCommand