Misc API

English API reference for the clipboard, console, log, menu, misc, panel, system, test family.

This page is the primary owner for the namespaces listed below. Method names, parameter keys, and return fields follow the C++ RegisterApi handlers.

clipboard

clipboard.read

Public API method. Runtime authority: src/api/ClipboardApi.cpp:319.

No parameters.

Returns: {"files":[],"hasFiles":true,"hasImage":true,"hasText":true,"success":true,"text":"..."}

const result = await fb2k.invoke('clipboard.read');

clipboard.write

Public API method. Runtime authority: src/api/ClipboardApi.cpp:322.

Parameter	Type	Required	Description
`text`	`string`	No	Optional; default .

Returns: {"error":"...","success":true}

const result = await fb2k.invoke('clipboard.write', { text: /* value */ });

clipboard.writeFiles

Public API method. Runtime authority: src/api/ClipboardApi.cpp:328.

Parameter	Type	Required	Description
`paths`	`array`	Yes	Required.

Returns: {"error":"...","fileCount":"...","success":true}

const result = await fb2k.invoke('clipboard.writeFiles', { paths: /* value */ });

clipboard.writeHTML

Public API method. Runtime authority: src/api/ClipboardApi.cpp:325.

Parameter	Type	Required	Description
`html`	`string`	No	Optional; default .
`plainText`	`string`	No	Optional; default .

Returns: {"error":"...","htmlWritten":"...","success":true,"textWritten":"..."}

const result = await fb2k.invoke('clipboard.writeHTML', { html: /* value */, plainText: /* value */ });

console

console.error

Public API method. Runtime authority: src/api/ConsoleApi.cpp:308.

Provide one of message or args. Empty payloads fail with message is required.

Parameter	Type	Required	Description
`message`	`string`	No	Optional log text. Non-string values are serialized.
`args`	`array`	No	Optional argument list joined with spaces when `message` is omitted.

Returns: {"error":"...","success":true}

const result = await fb2k.invoke('console.error', { message: 'failed to load artwork' });

console.log

Public API method. Runtime authority: src/api/ConsoleApi.cpp:302.

Provide one of message or args. Empty payloads fail with message is required.

Parameter	Type	Required	Description
`message`	`string`	No	Optional log text. Non-string values are serialized.
`args`	`array`	No	Optional argument list joined with spaces when `message` is omitted.

Returns: {"error":"...","success":true}

const result = await fb2k.invoke('console.log', { message: 'track started' });

console.warn

Public API method. Runtime authority: src/api/ConsoleApi.cpp:305.

Provide one of message or args. Empty payloads fail with message is required.

Parameter	Type	Required	Description
`message`	`string`	No	Optional log text. Non-string values are serialized.
`args`	`array`	No	Optional argument list joined with spaces when `message` is omitted.

Returns: {"error":"...","success":true}

const result = await fb2k.invoke('console.warn', { args: ['retry', 3] });

log

log.clear

Public API method. Runtime authority: src/api/ConsoleApi.cpp:317.

No parameters.

Returns: {"error":"...","success":true}

const result = await fb2k.invoke('log.clear');

log.read

Public API method. Runtime authority: src/api/ConsoleApi.cpp:314.

Parameter	Type	Required	Description
`lines`	`integer`	No	Optional; default 100.

Returns: {"content":"...","error":"...","lineCount":"...","lines":"...","success":true,"totalLines":"..."}

const result = await fb2k.invoke('log.read', { lines: /* value */ });

log.write

Public API method. Runtime authority: src/api/ConsoleApi.cpp:311.

Parameter	Type	Required	Description
`message`	`string`	No	Optional; default omitted.
`args`	`array`	No	Optional; default [].
`file`	`string`	No	Optional; default omitted.
`level`	`string`	No	Optional; default info.
`append`	`boolean`	No	Optional; default true.
`timestamp`	`boolean`	No	Optional; default true.

Returns: {"error":"...","path":"...","success":true}

const result = await fb2k.invoke('log.write', { message: /* value */, args: /* value */, append: /* value */, file: /* value */, level: /* value */, timestamp: /* value */ });

Public API method. Runtime authority: src/api/MenuApi.cpp:1141-1146.

Parameter	Type	Required	Default	Description
`reason`	`string`	No	`api`	Optional close reason passed to the overlay host; default `api`.

Returns: {"success":true}

const result = await fb2k.invoke('menu.close', { reason: 'api' });

Public API method. Runtime authority: src/api/MenuApi.cpp:1330.

Parameter	Type	Required	Description
`handles`	`array`	No	Optional; default [].
`i18n`	`boolean`	No	Optional; default true.
`locale`	`string`	No	Optional; default auto.
`mode`	`string`	No	Optional; `auto`, `selection`, `playlist`, `nowPlaying`, or `handles`; default `auto`.
`withAvailability`	`boolean`	No	Optional; default true.

Returns: {"Failed to initialize context menu":"...","error":"...","i18n":"...","items":"...","locale":"...","mode":"...","success":true,"withAvailability":"..."}

const result = await fb2k.invoke('menu.getContextMenu', { i18n: /* value */, locale: /* value */, mode: /* value */, withAvailability: /* value */, handles: /* value */ });

Public API method. Runtime authority: src/api/MenuApi.cpp:1329.

Parameter	Type	Required	Description
`i18n`	`boolean`	No	Optional; default true.
`locale`	`string`	No	Optional; default auto.
`root`	`string`	No	Optional; default .
`withAvailability`	`boolean`	No	Optional; default true.

Returns: {"error":"...","fallback":"...","items":[],"success":true}

const result = await fb2k.invoke('menu.getMainMenu', { i18n: /* value */, locale: /* value */, root: /* value */, withAvailability: /* value */ });

Public API method. Runtime authority: src/api/MenuApi.cpp:1328.

Parameter	Type	Required	Description
`command`	`string`	No	Optional; default .

Returns: {"error":"...","guid":"...","itemCount":"...","success":true}

const result = await fb2k.invoke('menu.runContextCommand', { command: /* value */ });

Public API method. Runtime authority: src/api/MenuApi.cpp:1331.

Parameter	Type	Required	Description
`id`	`integer`	No	Optional; default -1.
`mode`	`string`	No	Optional; default auto.
`handles`	`array`	No	Optional; default [].

Returns: {"Failed to initialize context menu":"...","error":"...","success":true}

const result = await fb2k.invoke('menu.runContextCommandById', { id: /* value */, mode: /* value */, handles: /* value */ });

Public API method. Runtime authority: src/api/MenuApi.cpp:1327.

Parameter	Type	Required	Description
`command`	`string`	No	Optional; default .

Returns: {"error":"...","guid":"...","success":true}

const result = await fb2k.invoke('menu.runMainMenuCommand', { command: /* value */ });

Public API method. Runtime authority: src/api/MenuApi.cpp:1333.

Parameter	Type	Required	Description
`items`	`array`	No	Optional; default omitted.
`x`	`integer`	No	Optional; default -1.
`y`	`integer`	No	Optional; default -1.

Returns: {"error":"...","menuId":"...","success":true}

const result = await fb2k.invoke('menu.show', { items: /* value */, x: /* value */, y: /* value */ });

Public API method. Runtime authority: src/api/MenuApi.cpp:1332.

Parameter	Type	Required	Description
`handles`	`array`	No	Optional; default [].
`mode`	`string`	No	Optional; `auto`, `selection`, `playlist`, `nowPlaying`, or `handles`; default `auto`.

Returns: {"error":"...","success":true}

const result = await fb2k.invoke('menu.showNativePopup', { handles: /* value */, mode: /* value */ });

misc

misc.exit

Public API method. Runtime authority: src/api/MiscApi.cpp:132.

No parameters.

Returns: {"success":true}

const result = await fb2k.invoke('misc.exit');

misc.getComponentPath

Public API method. Runtime authority: src/api/MiscApi.cpp:126.

No parameters.

Returns: {"path":"...","value":"..."}

const result = await fb2k.invoke('misc.getComponentPath');

misc.getFoobarPath

Public API method. Runtime authority: src/api/MiscApi.cpp:124.

No parameters.

Returns: {"path":"...","value":"..."}

const result = await fb2k.invoke('misc.getFoobarPath');

misc.getProfilePath

Public API method. Runtime authority: src/api/MiscApi.cpp:125.

No parameters.

Returns: {"path":"...","value":"..."}

const result = await fb2k.invoke('misc.getProfilePath');

misc.restart

Public API method. Runtime authority: src/api/MiscApi.cpp:131.

No parameters.

Returns: {"success":true}

const result = await fb2k.invoke('misc.restart');

misc.showConsole

Public API method. Runtime authority: src/api/MiscApi.cpp:127.

No parameters.

Returns: {"success":true}

const result = await fb2k.invoke('misc.showConsole');

misc.showLibrarySearch

Public API method. Runtime authority: src/api/MiscApi.cpp:129.

Parameter	Type	Required	Description
`query`	`string`	No	Optional; default .

Returns: {"query":"...","success":true}

const result = await fb2k.invoke('misc.showLibrarySearch', { query: /* value */ });

misc.showPopupMessage

Public API method. Runtime authority: src/api/MiscApi.cpp:130.

Parameter	Type	Required	Description
`message`	`string`	No	Optional; default .
`msg`	`string`	No	Optional; default .
`title`	`string`	No	Optional; default Message.

Returns: {"success":true}

const result = await fb2k.invoke('misc.showPopupMessage', { message: /* value */, msg: /* value */, title: /* value */ });

Owner-family behavior and limits

clipboard.writeFiles accepts media-read-authorized paths. clipboard.writeHTML writes HTML plus a plain-text fallback; clipboard.read reports only formats currently available from the Windows clipboard.
console.log, console.warn, console.error, and log.write require one of message or args. log.write.file, when accepted, is only a leaf .log or .txt filename under the profile directory; paths, traversal and Windows reserved device names are rejected by the runtime.
menu.getContextMenu, menu.runContextCommandById, and menu.showNativePopup use mode to select handles, nowPlaying, selection, or playlist context. auto tries those sources in that order, ending with playlist context. In handles mode, every path is media-access validated before a handle is created. menu.showNativePopup uses screen cursor coordinates and returns before the native menu is displayed.
menu.show opens the self-drawn overlay after resource validation. menu.close only closes the active overlay; menu.__* endpoints are internal and are not public APIs.
misc.showPopupMessage accepts message, falling back to msg, and defaults title to "Message". The restart and exit methods request the corresponding foobar2000 standard command.
panel.setConfig changes only its documented panel fields. system.* reports registered runtime and plugin information; test.* is diagnostic surface rather than application behavior.

misc.showPreferences

Public API method. Runtime authority: src/api/MiscApi.cpp:128.

No parameters.

Returns: {"success":true}

const result = await fb2k.invoke('misc.showPreferences');

panel

panel.getConfig

Public API method. Runtime authority: src/api/WindowApi.cpp:2470.

No parameters.

Returns: {"config":{},"success":true}

const result = await fb2k.invoke('panel.getConfig');

panel.setConfig

Public API method. Runtime authority: src/api/WindowApi.cpp:2471.

Parameter	Type	Required	Description
`enableDragDrop`	`boolean`	No	Optional; default omitted.
`grabFocus`	`boolean`	No	Optional; default omitted.
`panelName`	`string`	No	Optional; default omitted.
`transparentBackground`	`boolean`	No	Optional; default omitted.

Returns: {"changed":"...","error":"...","success":true}

const result = await fb2k.invoke('panel.setConfig', { enableDragDrop: /* value */, grabFocus: /* value */, panelName: /* value */, transparentBackground: /* value */ });

system

system.getApiStats

Public API method. Runtime authority: src/api/PluginRegistry.cpp:490.

No parameters.

Returns: {"registered":"...","success":true}

const result = await fb2k.invoke('system.getApiStats');

system.getApisByNamespace

Public API method. Runtime authority: src/api/PluginRegistry.cpp:454.

Parameter	Type	Required	Description
`namespace`	`string`	No	Optional; default .

Returns: JSON object from the runtime handler.

const result = await fb2k.invoke('system.getApisByNamespace', { namespace: /* value */ });

system.getDPI

Public API method. Runtime authority: src/api/WindowApi.cpp:2426.

No parameters.

Returns: {"dpi":"...","scale":"..."}

const result = await fb2k.invoke('system.getDPI');

system.getLocale

Public API method. Runtime authority: src/api/WindowApi.cpp:2429.

No parameters.

Returns: {"country":"...","language":"...","locale":"..."}

const result = await fb2k.invoke('system.getLocale');

system.getRegisteredPlugins

Public API method. Runtime authority: src/api/PluginRegistry.cpp:496.

No parameters.

Returns: {"registered":"...","success":true}

const result = await fb2k.invoke('system.getRegisteredPlugins');

system.getTheme

Public API method. Runtime authority: src/api/WindowApi.cpp:2425.

No parameters.

Returns: {"accentColor":"...","darkMode":"...","isDark":"...","transparency":"..."}

const result = await fb2k.invoke('system.getTheme');

system.isPluginRegistered

Public API method. Runtime authority: src/api/PluginRegistry.cpp:509.

Parameter	Type	Required	Description
`namespace`	`string`	No	Optional; default .

Returns: {"registered":"...","success":true}

const result = await fb2k.invoke('system.isPluginRegistered', { namespace: /* value */ });

system.listAvailableApis

Public API method. Runtime authority: src/api/PluginRegistry.cpp:438.

Parameter	Type	Required	Description
`includeExternal`	`boolean`	No	Optional; default true.
`includeInternal`	`boolean`	No	Optional; default true.

Returns: JSON object from the runtime handler.

const result = await fb2k.invoke('system.listAvailableApis', { includeExternal: /* value */, includeInternal: /* value */ });

system.searchApis

Public API method. Runtime authority: src/api/PluginRegistry.cpp:472.

Parameter	Type	Required	Description
`query`	`string`	No	Optional; default .

Returns: JSON object from the runtime handler.

const result = await fb2k.invoke('system.searchApis', { query: /* value */ });

test

test.echo

Public API method. Runtime authority: src/api/PlaybackApi.cpp:697.

Parameter	Type	Required	Description
`message`	`json`	No	Optional; default omitted.

Returns: {"echo":"...","input":"...","success":true}

const result = await fb2k.invoke('test.echo', { message: /* value */ });

test.ping

Public API method. Runtime authority: src/api/PlaybackApi.cpp:698.

No parameters.

Returns: {"pong":"...","timestamp":"..."}

const result = await fb2k.invoke('test.ping');

Contract supplements

The sections below close public-contract findings from the strict parameter audit without replacing existing explanations.

Contract supplement: `log.write`

Verified contract supplement. Runtime authority: src/api/ConsoleApi.cpp:140-221.

Parameter	Type	Required	Default	Description
`message`	`string`	No	omitted	Optional; default omitted.
`args`	`array`	No	`[]`	Optional; default [].
`file`	`string`	No	omitted	Optional; default omitted.
`level`	`string`	No	`info`	Optional; default info.
`append`	`boolean`	No	`true`	Optional; default true.
`timestamp`	`boolean`	No	`true`	Optional; default true.

Return fields

Field	Type	Optional
`error`	`string`	Yes
`success`	`boolean`	No
`path`	`json`	No

Semantics: omitted optional parameters use handler defaults; failure branches and error fields are defined by this source file.

const result = await fb2k.invoke('log.write', { message: /* value */, args: /* value */, file: /* value */, level: /* value */, append: /* value */, timestamp: /* value */ });

Contract supplement: `menu.getContextMenu`

Verified contract supplement. Runtime authority: src/api/MenuApi.cpp:980-1024.

Parameter	Type	Required	Default	Description
`handles`	`array`	No	`[]`	Optional; default [].
`i18n`	`boolean`	No	`true`	Optional; default true.
`locale`	`string`	No	`auto`	Optional; default auto.
`mode`	`string`	No	`auto`	Optional; default auto.
`withAvailability`	`boolean`	No	`true`	Optional; default true.

Return fields

Field	Type	Optional
`error`	`string`	Yes
`success`	`boolean`	No
`i18n`	`json`	No
`items`	`json`	No
`locale`	`json`	No
`mode`	`json`	No
`withAvailability`	`json`	No

Semantics: omitted optional parameters use handler defaults; failure branches and error fields are defined by this source file.

const result = await fb2k.invoke('menu.getContextMenu', { handles: /* value */, i18n: /* value */, locale: /* value */, mode: /* value */, withAvailability: /* value */ });

Contract supplement: `menu.runContextCommandById`

Verified contract supplement. Runtime authority: src/api/MenuApi.cpp:1024-1045.

Parameter	Type	Required	Default	Description
`id`	`integer`	No	`-1`	Optional; default -1.
`mode`	`string`	No	`auto`	Optional; default auto.
`handles`	`array`	No	`[]`	Optional; default [].

Return fields

Field	Type	Optional
`error`	`string`	Yes
`success`	`boolean`	No

Semantics: omitted optional parameters use handler defaults; failure branches and error fields are defined by this source file.

const result = await fb2k.invoke('menu.runContextCommandById', { id: /* value */, mode: /* value */, handles: /* value */ });

Contract supplement: `misc.showPopupMessage`

Verified contract supplement. Runtime authority: src/api/MiscApi.cpp:97-105.

Parameter	Type	Required	Default	Description
`message`	`string`	No	``	Optional; default .
`msg`	`string`	No	``	Optional; default .
`title`	`string`	No	`Message`	Optional; default Message.

Return fields

Field	Type	Optional
`success`	`boolean`	No

Semantics: omitted optional parameters use handler defaults; failure branches and error fields are defined by this source file.

const result = await fb2k.invoke('misc.showPopupMessage', { message: /* value */, msg: /* value */, title: /* value */ });

Misc API ​

clipboard ​

clipboard.read ​

clipboard.write ​

clipboard.writeFiles ​

clipboard.writeHTML ​

console ​

console.error ​

console.log ​

console.warn ​

log ​

log.clear ​

log.read ​

log.write ​

menu ​

menu.close ​

menu.getContextMenu ​

menu.getMainMenu ​

menu.runContextCommand ​

menu.runContextCommandById ​

menu.runMainMenuCommand ​

menu.show ​

menu.showNativePopup ​

misc ​

misc.exit ​

misc.getComponentPath ​

misc.getFoobarPath ​

misc.getProfilePath ​

misc.restart ​

misc.showConsole ​

misc.showLibrarySearch ​

misc.showPopupMessage ​

Owner-family behavior and limits ​

misc.showPreferences ​

panel ​

panel.getConfig ​

panel.setConfig ​

system ​

system.getApiStats ​

system.getApisByNamespace ​

system.getDPI ​

system.getLocale ​

system.getRegisteredPlugins ​

system.getTheme ​

system.isPluginRegistered ​

system.listAvailableApis ​

system.searchApis ​

test ​

test.echo ​

test.ping ​

Contract supplements ​

Contract supplement: log.write ​

Return fields ​

Contract supplement: menu.getContextMenu ​

Return fields ​

Contract supplement: menu.runContextCommandById ​

Return fields ​

Contract supplement: misc.showPopupMessage ​

Return fields ​

Misc API

clipboard

clipboard.read

clipboard.write

clipboard.writeFiles

clipboard.writeHTML

console

console.error

console.log

console.warn

log

log.clear

log.read

log.write

menu

menu.close

menu.getContextMenu

menu.getMainMenu

menu.runContextCommand

menu.runContextCommandById

menu.runMainMenuCommand

menu.show

menu.showNativePopup

misc

misc.exit

misc.getComponentPath

misc.getFoobarPath

misc.getProfilePath

misc.restart

misc.showConsole

misc.showLibrarySearch

misc.showPopupMessage

Owner-family behavior and limits

misc.showPreferences

panel

panel.getConfig

panel.setConfig

system

system.getApiStats

system.getApisByNamespace

system.getDPI

system.getLocale

system.getRegisteredPlugins

system.getTheme

system.isPluginRegistered

system.listAvailableApis

system.searchApis

test

test.echo

test.ping

Contract supplements

Contract supplement: `log.write`

Return fields

Contract supplement: `menu.getContextMenu`

Return fields

Contract supplement: `menu.runContextCommandById`

Return fields

Contract supplement: `misc.showPopupMessage`

Return fields