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

Access to the main foobar2000 application window. See FbWindow for global state, multi-panel ownership and UI-specific behavior.

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.

Relative filesystem paths are resolved as described in utils.ReadTextFile. URLs and foobar2000 URI paths are passed through unchanged. Each filesystem location is resolved before the asynchronous operation starts.

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.

Returns PCM data from the foobar2000 visualisation stream.
The stream is created lazily. A negative offset requests data before the current visualisation time; JSplitter automatically maintains the native backlog required for that offset. The first stream initialization may briefly synchronize with the foobar2000 main thread.
For repeated real-time processing, prefer fb.GetAudioChunkTo to write directly into a reusable Float32Array without creating a transient FbAudioChunk. CopyDataTo remains useful when a chunk object is already required, while Data preserves its legacy allocating Array behaviour for compatibility.

Writes interleaved PCM samples from the foobar2000 visualisation stream directly into an existing Float32Array. Unlike fb.GetAudioChunk, this method does not create an FbAudioChunk; after the first sufficiently large native scratch buffer has been established, repeated calls can reuse both the native scratch storage and the JavaScript destination buffer.
A negative offset has the same backlog semantics as fb.GetAudioChunk. If info is supplied, it is updated in place with SampleCount, ChannelCount, SampleRate and ChannelConfig.

Returns the audio streams exposed by the input decoder for handle as array of AudioStreamInfo objects.
Returns an empty array when the file's input decoder does not expose stream information. Related methods: fb.SetAudioStream.

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

Returns unique Media Library root paths inferred from the current Media Library contents.
Each root is reconstructed from the absolute path and library-relative path of a library item.
Configured library folders that contain no library items cannot be returned.

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.

Selects an audio stream for handle and stores it as the user's stream preference.
Available only in foobar2000 v2.0 and above. Throws an Error when API is unavailable, the file does not support stream selection, or index is out of bounds.
If the file is currently playing and the effective selection changes, playback is restarted so the new stream is applied immediately.

Related methods: fb.GetAudioStreams.

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. Pass an image file path, or an FbMetadbHandle; with a handle, AlbumArtId defaults to AlbumArtId.front. Album art is resolved by foobar2000 and may be embedded or external.

Relative filesystem paths are resolved as described in utils.ReadTextFile. This applies to the image-file argument; track handles use foobar2000 artwork lookup.

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