Config API

English API reference for the config family.

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

config

config.export

No parameters.

Returns: {"count":0,"data":"...","json":"...","success":true}

const result = await fb2k.invoke('config.export');

config.get

Parameter	Type	Required	Description
key	string	Yes	Configuration key to read; a missing or empty value returns key is required.
default	json	No	Returned as value when the key is absent.

Returns: {"error":"...","found":"...","key":"...","success":true,"value":"..."}

const { value, found } = await fb2k.invoke('config.get', { key: 'theme' });

config.getActiveDspPreset

No parameters.

Returns: {"index":0,"isActive":true,"name":"..."}

const result = await fb2k.invoke('config.getActiveDspPreset');

config.getAdvancedConfig

Parameter	Type	Required	Description
parentGuid	string	No	Defaults to the advanced-preferences root branch.

Returns: JSON object from the runtime handler.

const entries = await fb2k.invoke('config.getAdvancedConfig');

config.getAdvancedConfigValue

Parameter	Type	Required	Description
guid	string	Yes	Advanced-preferences entry GUID; a missing or empty value fails with guid is required.

Returns: {"guid":"...","name":"...","type":"...","value":"..."}

const entry = await fb2k.invoke('config.getAdvancedConfigValue', { guid: '{some-guid}' });

config.getAll

No parameters.

Returns: {"configs":"...","count":"...","items":"...","success":true}

const result = await fb2k.invoke('config.getAll');

config.getComponents

No parameters.

Returns: JSON object from the runtime handler.

const result = await fb2k.invoke('config.getComponents');

config.getCursorFollowPlayback

No parameters.

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

const result = await fb2k.invoke('config.getCursorFollowPlayback');

config.getDspPresets

No parameters.

Returns: JSON object from the runtime handler.

const result = await fb2k.invoke('config.getDspPresets');

config.getLibraryFilePatterns

No parameters.

Returns: {"images":[],"tracks":[]}

const result = await fb2k.invoke('config.getLibraryFilePatterns');

config.getLibraryStatus

No parameters.

Returns: {"enabled":true,"initialized":"...","itemCount":"..."}

const result = await fb2k.invoke('config.getLibraryStatus');

config.getOutputConfig

No parameters.

Returns: {"bitDepth":"...","bufferLength":"...","deviceId":"...","deviceName":"...","outputId":"...","outputName":"...","useDither":"...","useFades":"..."}

const result = await fb2k.invoke('config.getOutputConfig');

config.getOutputDevices

No parameters.

Returns: JSON object from the runtime handler.

const result = await fb2k.invoke('config.getOutputDevices');

config.getPlaybackFollowCursor

No parameters.

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

const result = await fb2k.invoke('config.getPlaybackFollowCursor');

config.getPreferencesPages

No parameters.

Returns: JSON object from the runtime handler.

const result = await fb2k.invoke('config.getPreferencesPages');

config.getPreferencesStandardGuids

No parameters.

Returns: {"advanced":"...","components":"...","core":"...","display":"...","dsp":"...","hidden":"...","input":"...","keyboardShortcuts":"...","mediaLibrary":"...","output":"...","playback":"...","root":"...","shell":"...","tagWriting":"...","tagging":"...","tools":"...","visualisations":"..."}

const result = await fb2k.invoke('config.getPreferencesStandardGuids');

config.getReplaygainMode

No parameters.

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

const result = await fb2k.invoke('config.getReplaygainMode');

config.getVersionInfo

No parameters.

Returns: {"foobar2000":"...","is64bit":true,"isPortable":true,"plugin":"...","profilePath":"...","version":"...","versionFull":"..."}

const result = await fb2k.invoke('config.getVersionInfo');

config.remove

Parameter	Type	Required	Description
key	string	Yes	Configuration key to delete; a missing or empty value returns key is required.

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

await fb2k.invoke('config.remove', { key: 'theme' });

config.resetAdvancedConfig

Parameter	Type	Required	Description
guid	string	Yes	Advanced-preferences entry GUID; a missing or empty value fails with guid is required.

Returns: {"success":true}

await fb2k.invoke('config.resetAdvancedConfig', { guid: '{some-guid}' });

config.set

Parameter	Type	Required	Description
key	string	Yes	Configuration key to write; a missing or empty value returns key is required.
value	json	Yes	Any JSON value.

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

await fb2k.invoke('config.set', { key: 'theme', value: { mode: 'dark' } });

config.setActiveDspPreset

Parameter	Type	Required	Description
index	integer	Yes	Preset index as reported by config.getDspPresets.

Returns: {"success":true}

await fb2k.invoke('config.setActiveDspPreset', { index: 0 });

config.setAdvancedConfigValue

Parameter	Type	Required	Description
guid	string	Yes	Advanced-preferences entry GUID; a missing or empty value fails with guid is required.
value	boolean	Yes	Boolean for checkbox entries; string or number for string/integer entries (numbers are stringified, floats truncated for integer entries).

Returns: {"success":true}

await fb2k.invoke('config.setAdvancedConfigValue', { guid: '{some-guid}', value: true });

config.setCursorFollowPlayback

Parameter	Type	Required	Default	Description
enabled	boolean	No	false
value	boolean	No	false	Compatibility alias of enabled.

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

await fb2k.invoke('config.setCursorFollowPlayback', { enabled: true });

config.setOutputBuffer

Parameter	Type	Required	Default	Description
bufferLength	number	No	0	Buffer in seconds; at least one of the two must be supplied (error otherwise), and milliseconds wins when both are present.
milliseconds	number	No	0	Converted to seconds; effective range 0.05-2.0 s.

Returns: {"success":true}

// milliseconds is converted to seconds; the effective range is 0.05-2.0 seconds
await fb2k.invoke('config.setOutputBuffer', { milliseconds: 1000 });

config.setOutputDevice

Parameter	Type	Required	Description
deviceId	string	Yes	Device GUID; a missing or empty value fails with outputId and deviceId are required.
outputId	string	Yes	Output-driver GUID; a missing or empty value fails with outputId and deviceId are required.

Returns: {"success":true}

await fb2k.invoke('config.setOutputDevice', { outputId: '{output-guid}', deviceId: '{device-guid}' });

config.setPlaybackFollowCursor

Parameter	Type	Required	Default	Description
enabled	boolean	No	false
value	boolean	No	false	Compatibility alias of enabled.

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

await fb2k.invoke('config.setPlaybackFollowCursor', { enabled: true });

config.setReplaygainMode

Parameter	Type	Required	Default	Description
mode	integer	No	-1	Numeric form: 0=none, 1=track, 2=album, 3=byPlaybackOrder.
sourceMode	string	No	—	String form: none, track, album, auto, byPlaybackOrder.
value	integer	No	-1	Compatibility alias of mode.

Returns: {"code":"...","error":"...","mode":"...","success":true,"value":"..."}

await fb2k.invoke('config.setReplaygainMode', { sourceMode: 'album' });

config.showLibraryPreferences

No parameters.

Returns: {"success":true}

const result = await fb2k.invoke('config.showLibraryPreferences');

Storage and preference semantics

config.set, config.get, config.remove, config.getAll, and config.export operate on the component's persistent configuration object. config.get requires key; when the key is absent it returns found: false and uses the optional default value when supplied. config.set requires both key and value; the value can be any JSON value.

Output and advanced-preference methods use foobar2000 services. In particular, config.setOutputDevice requires valid outputId and deviceId GUIDs, while config.setOutputBuffer accepts either seconds in bufferLength or milliseconds in milliseconds. Advanced entries require a valid guid; their accepted value type depends on the entry type rather than a single universal schema.

The cursor-follow and ReplayGain setters accept their documented compatibility forms. For ReplayGain, mode and value are numeric forms, while sourceMode accepts track, album, auto, byPlaybackOrder, or none. The handler returns INVALID_PARAMS for an unknown string source mode.