跳到正文

Config API ​

管理持久化配置存储、音频输出设备、DSP 预设、高级偏好设置及播放行为选项。

配置存储 ​

config.get ​

读取指定键下存储的值;键不存在时不报错,返回 found: false,且 value 取 default 传入值(未提供时为 null)

参数类型必填说明
keystring是待读取的存储键名不能为空。
defaultany否目标键不存在时返回的默认兜底值

返回值

字段类型说明
keystring请求读取的存储键名
valueany存储的值;键不存在时返回 default 传入值(未提供时返回 null)
foundboolean目标键是否存在于存储中

成功时 success 为 true;失败时返回 { success: false, error, code },code 见错误码。

目标键不存在时 found 为 false;若传入了 default 则返回该默认兜底值。

javascript
const theme = await fb2k.invoke('config.get', { key: 'theme', default: 'light' });

config.set ​

将指定值存储至本组件专属的持久化键值存储中,覆盖该键原有数据;配置保存在 foobar2000 宿主配置区中,软件重启后依然保留;若存储读取失败或值无法保存则以 OPERATION_FAILED 失败

参数类型必填说明
keystring是存储键名;本组件所有页面共享同一存储空间,建议添加主题特有前缀不能为空。
valueany是待存储的值,支持任意可序列化的 JSON 数据;顶层 null 会被视作无效键值拒绝,清除键请调用 config.remove,嵌套对象或数组内的 null 照常保留

返回值

字段类型说明
keystring成功写入的存储键名

成功时 success 为 true;失败时返回 { success: false, error, code },code 见错误码。

javascript
await fb2k.invoke('config.set', { key: 'volume', value: 0.8 });

config.remove ​

从键值存储中删除指定的键;删除不存在的键仍视为成功,返回 existed: false

参数类型必填说明
keystring是待删除的存储键名不能为空。

返回值

字段类型说明
keystring请求删除的存储键名
existedboolean本次删除操作前该键是否存在于存储中

成功时 success 为 true;失败时返回 { success: false, error, code },code 见错误码。

config.getAll ​

获取持久化存储中的全部键值对数据

无参数。

返回值

字段类型说明
itemsRecord<string, any>包含所有存储键值对的字典对象
configsRecord<string, any>与 items 完全一致的旧名兼容字典
countinteger存储中包含的键值对总数

成功时 success 为 true;失败时返回 { success: false, error, code },code 见错误码。

items 与 configs 返回相同字典(后者为旧版兼容别名)。

javascript
const cfg = await fb2k.invoke('config.getAll');
if (cfg.success === false) throw new Error(cfg.error);
console.log(`配置项数: ${cfg.count}`, cfg.items);

config.export ​

导出持久化存储中的全部配置数据,同时提供对象映射与序列化 JSON 文本两种形式

无参数。

返回值

字段类型说明
dataRecord<string, any>包含所有存储键值对的字典对象,同 config.getAll 的 items
jsonstring将 data 序列化后的紧凑 JSON 字符串
countinteger存储中包含的键值对总数

成功时 success 为 true;失败时返回 { success: false, error, code },code 见错误码。

data 为 JSON 对象,json 为序列化字符串。

javascript
const exported = await fb2k.invoke('config.export');
if (exported.success === false) throw new Error(exported.error);
localStorage.setItem('fb2k_backup', exported.json);

系统信息 ​

config.getVersionInfo ​

获取宿主运行环境版本信息,包括 foobar2000 核心版本、本组件版本、系统架构及配置目录绝对路径

无参数。

返回值

字段类型说明
versionstring核心报告的 foobar2000 版本字符串,包含产品名称
foobar2000string与 version 完全一致的兼容别名字段
versionFullstringSDK core_version_info_v2::get_name() 报告的产品名称(固定为 "foobar2000",并非完整版本字符串)
is64bitboolean是否为 64 位(x64)编译版本
isPortablebooleanfoobar2000 当前是否以便携(Portable)模式运行
pluginobject本 WebView2 UI 组件信息
plugin.namestring固定为 "foo_ui_webview2"
plugin.versionstring本组件版本号,格式为 主.次.修订
profilePathstring用户配置(Profile)目录的显示路径

成功时 success 为 true;失败时返回 { success: false, error, code },code 见错误码。

javascript
const info = await fb2k.invoke('config.getVersionInfo');
if (info.success === false) throw new Error(info.error);
console.log(`${info.versionFull} | ${info.is64bit ? '64-bit' : '32-bit'}`);

config.getComponents ​

获取当前已安装的 foobar2000 原生组件列表及其版本与模块文件名

无参数。

返回值

字段类型说明
componentsConfigComponentInfo[]按枚举顺序排列的所有已安装组件信息列表
components[].namestring组件自身报告的显示名称
components[].versionstring组件自身报告的版本号字符串
components[].filenamestring组件对应的 DLL 模块文件名;组件未声明时不返回
components[].fileNamestring与 filename 完全一致的兼容别名字段
countintegercomponents 列表包含的组件总数

成功时 success 为 true;失败时返回 { success: false, error, code },code 见错误码。

fileName 和 filename 相同(后者为兼容别名)。

config.getOutputDevices ​

列出所有输出模块下的音频设备并标记当前生效设备;数据形态为扁平列表,每个设备项均关联其所属模块的 GUID

无参数。

返回值

字段类型说明
devicesConfigOutputDevice[]所有已安装输出模块下的设备列表
devices[].namestring设备显示名称;输出管理器提供时为完整名称,若直接源自输出模块则为 <模块名>: <设备名>
devices[].idstring设备标识符,与 deviceId 相同
devices[].outputIdstring输出模块 GUID,格式形如 {...}
devices[].deviceIdstring设备 GUID,格式形如 {...};单独并不保证全局唯一(模块默认设备全为零 GUID),需以 (outputId, deviceId) 二元组唯一标识
devices[].isCurrentboolean该设备是否为当前系统生效的活动输出设备
countintegerdevices 列表包含的设备总数

成功时 success 为 true;失败时返回 { success: false, error, code },code 见错误码。

javascript
const res = await fb2k.invoke('config.getOutputDevices');
if (res.success === false) throw new Error(res.error);
const { devices } = res;
const current = devices.find(d => d.isCurrent);
console.log(`当前输出: ${current.name}`);

config.setOutputDevice ​

将音频输出切换至指定输出模块下的目标设备;模块与设备 GUID 均通过 config.getOutputDevices 获取

参数类型必填说明
outputIdstring是目标输出模块 GUID,取自 config.getOutputDevices 返回的 outputId不能为空。
deviceIdstring是目标设备 GUID,取自 config.getOutputDevices 返回的 deviceId不能为空。

返回值

成功时 success 为 true;失败时返回 { success: false, error, code },code 见错误码。

javascript
await fb2k.invoke('config.setOutputDevice', { outputId: '{...}', deviceId: '{...}' });

config.getOutputConfig ​

获取当前生效的音频输出配置,包括所属模块、设备 GUID、缓冲长度、输出位深、抖动与淡入淡出设置

无参数。

返回值

字段类型说明
outputIdstring当前生效的输出模块 GUID,格式形如 {...}
deviceIdstring当前生效的设备 GUID,格式形如 {...}
bufferLengthnumber当前配置的输出缓冲长度,单位为秒
bitDepthinteger当前配置的输出位深,单位为比特(bit)
useDitherboolean是否启用了音频抖动处理
useFadesboolean是否启用了淡入淡出效果
outputNamestring当前生效输出模块的显示名称;未匹配到对应模块时不返回
deviceNamestring当前生效输出设备的显示名称;模块未提供时不返回

成功时 success 为 true;失败时返回 { success: false, error, code },code 见错误码。

config.setOutputBuffer ​

设置音频输出缓冲长度;支持传入以秒为单位的 bufferLength 或以毫秒为单位的 milliseconds(两者至少传其一,均提供时以 milliseconds 为准且 bufferLength 仍受范围检查)

参数类型必填说明
bufferLengthnumber否缓冲长度,单位为秒;若同时传入 milliseconds 则以此为辅助校验范围,以毫秒值为准取值 0.05 到 2(含端点)。
millisecondsnumber否缓冲长度,单位为毫秒;优先级高于 bufferLength取值 50 到 2000(含端点)。

返回值

成功时 success 为 true;失败时返回 { success: false, error, code },code 见错误码。

高级配置 ​

config.getAdvancedConfig ​

获取 foobar2000 高级首选项树;可从根节点遍历或从指定的 parentGuid 分支节点展开

参数类型必填说明
parentGuidstring否待遍历展开的分支节点 GUID,格式形如 {...};缺省或为空串时从根节点开始展开,格式合法但非分支的 GUID 返回空列表

返回值

字段类型说明
entriesAdvancedConfigItem[]目标分支下一层直接包含的条目列表;子分支项在各自的 children 中嵌套包含
entries[].namestring节点条目的显示名称
entries[].guidstring节点 GUID,格式形如 {...},供读取、修改与重置接口传参使用
entries[].sortPrioritynumber条目声明的排序优先级
entries[].type"branch" | "checkbox" | "radio" | "integer" | "string" | "unknown"高级首选项条目类别:branch 容纳子条目,checkbox 与 radio 存储布尔值,integer 与 string 存储文本,unknown 为其他类型
entries[].valueany条目当前值;checkbox/radio 为布尔值,integer/string 为存储的原始文本(整数条目在此为十进制文本格式,而 config.getAdvancedConfigValue 返回数字),branch 与 unknown 省略此字段
entries[].defaultValueany条目的默认值,数据类型与 value 相同;仅在条目提供默认值时出现
entries[].isSignedboolean是否标记为有符号整数;仅在 integer 与 string 类型条目上提供
entries[].isFilePathboolean是否标记为文件路径属性;仅在 integer 与 string 类型条目上提供
entries[].isFolderPathboolean是否标记为文件夹路径属性;仅在 integer 与 string 类型条目上提供
entries[].childrenAdvancedConfigItem[]分支节点下包含的子条目列表;仅在 branch 类型出现,超过 11 层的深层分支子列表置空截断
countintegerentries 顶层包含的条目总数(不计深层嵌套项)

成功时 success 为 true;失败时返回 { success: false, error, code },code 见错误码。

config.getAdvancedConfigValue ​

根据 GUID 读取单个高级首选项条目;整数类型条目在此方法中直接以数字格式返回,而非十进制文本

参数类型必填说明
guidstring是待查询条目的 GUID,格式形如 {...}不能为空。

返回值

字段类型说明
namestring目标条目的显示名称
guidstring请求中传入的 GUID 原样回显,未做大小写归一化
type"branch" | "checkbox" | "radio" | "integer" | "string" | "unknown"高级首选项条目类别:branch 容纳子条目,checkbox 与 radio 存储布尔值,integer 与 string 存储文本,unknown 为其他类型
valueany目标条目当前值;checkbox/radio 为布尔值,integer 为数字(文本不以数字开头时为 0),string 为字符串,branch/unknown 为 null

成功时 success 为 true;失败时返回 { success: false, error, code },code 见错误码。

config.setAdvancedConfigValue ​

写入单个高级首选项条目的值;传入的值须与条目类型严格匹配:checkbox 与 radio 需传入布尔值,integer 与 string 需传入字符串或数字(数值会以十进制文本保存,integer 舍去小数部分,string 保留六位小数);分支节点(branch)及其他未知类别条目不可写入

参数类型必填说明
guidstring是待写入条目的 GUID,格式形如 {...}不能为空。
valueany是待写入的新值;各条目类型可接受的数据格式详见方法说明

返回值

成功时 success 为 true;失败时返回 { success: false, error, code },code 见错误码。

config.resetAdvancedConfig ​

将指定 GUID 的高级首选项条目重置恢复为其默认值

参数类型必填说明
guidstring是待重置条目的 GUID,格式形如 {...}不能为空。

返回值

成功时 success 为 true;失败时返回 { success: false, error, code },code 见错误码。

javascript
// 获取、修改、重置高级配置项
const val = await fb2k.invoke('config.getAdvancedConfigValue', { guid: '{...}' });
await fb2k.invoke('config.setAdvancedConfigValue', { guid: '{...}', value: true });
await fb2k.invoke('config.resetAdvancedConfig', { guid: '{...}' });

偏好设置 ​

config.getPreferencesPages ​

列出所有已注册的首选项页面与分支节点,先按顺序排列常规页面,随后排列分支节点

无参数。

返回值

字段类型说明
pagesConfigPreferencesPage[]所有首选项页面与分支列表,页面在前,分支在后
pages[].namestring首选项页面或分支的显示名称
pages[].guidstring页面或分支自身的 GUID,格式形如 {...}
pages[].parentGuidstring其上级页面或分支的 GUID,格式形如 {...};顶层页面指向标准预设父节点之一
pages[].sortPrioritynumber页面报告的排序优先级,数值越小越靠前,0 按名称字母排序;未声明时默认为 0
pages[].isBranchboolean是否为分支节点;为 true 时为分支,页面项省略此字段
countintegerpages 包含的条目总数

成功时 success 为 true;失败时返回 { success: false, error, code },code 见错误码。

config.getPreferencesStandardGuids ​

获取 foobar2000 内置标准首选项父节点的 GUID 集合;扩展页面与分支以此作为挂载父级

无参数。

返回值

字段类型说明
rootstringpreferences_page::guid_root GUID,代表首选项根节点
hiddenstringpreferences_page::guid_hidden GUID,代表隐藏首选项节点
toolsstringpreferences_page::guid_tools GUID,代表工具类首选项父节点
corestringpreferences_page::guid_core GUID,代表核心类首选项父节点
displaystringpreferences_page::guid_display GUID,代表界面与显示类首选项父节点
playbackstringpreferences_page::guid_playback GUID,代表播放类首选项父节点
visualisationsstringpreferences_page::guid_visualisations GUID,代表可视化类首选项父节点
inputstringpreferences_page::guid_input GUID,代表解码与输入类首选项父节点
tagWritingstringpreferences_page::guid_tag_writing GUID,代表标签写入类首选项父节点
mediaLibrarystringpreferences_page::guid_media_library GUID,代表媒体库类首选项父节点
taggingstringpreferences_page::guid_tagging GUID,代表标签处理类首选项父节点
outputstringpreferences_page::guid_output GUID,代表音频输出类首选项父节点
advancedstringpreferences_page::guid_advanced GUID,代表高级首选项父节点
componentsstringpreferences_page::guid_components GUID,代表组件管理类首选项父节点
dspstringpreferences_page::guid_dsp GUID,代表 DSP 管理类首选项父节点
shellstringpreferences_page::guid_shell GUID,代表系统外壳类首选项父节点
keyboardShortcutsstringpreferences_page::guid_keyboard_shortcuts GUID,代表快捷键设置类首选项父节点

成功时 success 为 true;失败时返回 { success: false, error, code },code 见错误码。

媒体库配置 ​

config.getLibraryStatus ​

获取媒体库状态,包括是否启用、初始化是否就绪以及曲目总数;条目总数每次调用时重新遍历统计

无参数。

返回值

字段类型说明
enabledboolean媒体库是否已启用(foobar2000 以至少配置了一个媒体库文件夹为准)
itemCountinteger媒体库当前包含的音频条目总数,每次调用时重新遍历统计
initializedboolean媒体库是否已载入初始化完成;宿主无法获知时默认为 true

成功时 success 为 true;失败时返回 { success: false, error, code },code 见错误码。

config.getLibraryFilePatterns ​

获取媒体库在新编码、复制或移动操作时归档曲目与专辑封面的目标路径规则;未配置的规则不会出现在结果中,两者均未配置时仅返回成功信封

无参数。

返回值

字段类型说明
tracksConfigLibraryFilePattern针对新编码、复制或移动的曲目归档命名规则;未配置时不返回
tracks.directorystring配置的目标存储文件夹路径
tracks.formatstring用于生成子文件夹与文件名的标题格式化(Titleformat)模式串
imagesConfigLibraryFilePattern针对新编码、复制或移动的专辑封面归档命名规则;未配置时不返回
images.directorystring配置的目标存储文件夹路径
images.formatstring用于生成子文件夹与文件名的标题格式化(Titleformat)模式串

成功时 success 为 true;失败时返回 { success: false, error, code },code 见错误码。

config.showLibraryPreferences ​

弹出并定位到 foobar2000 的媒体库(Media Library)首选项设置窗口

无参数。

返回值

成功时 success 为 true;失败时返回 { success: false, error, code },code 见错误码。

  • 返回值: { "success": true }

DSP 预设 ​

config.getDspPresets ​

获取用户配置目录中已保存的 DSP 预设列表;宿主不支持 DSP 预设时返回空列表

无参数。

返回值

字段类型说明
presetsConfigDspPreset[]所有已保存的 DSP 预设条目列表,保持列表排序
presets[].indexinteger预设在列表中的位置索引,供 config.setActiveDspPreset 传参调用
presets[].namestring预设配置名称
countintegerpresets 列表包含的预设总数

成功时 success 为 true;失败时返回 { success: false, error, code },code 见错误码。

javascript
const res = await fb2k.invoke('config.getDspPresets');
if (res.success === false) throw new Error(res.error);
const { presets } = res;
presets.forEach(p => console.log(`${p.index}: ${p.name}`));

config.getActiveDspPreset ​

获取当前生效选中的 DSP 预设;未选中预设或预设功能不可用时,index 与 name 返回 null 且 isActive 为 false

无参数。

返回值

字段类型说明
indexinteger | null当前激活选中的 DSP 预设索引;未选中预设时为 null
namestring | null当前激活选中的 DSP 预设名称;未选中预设时为 null
isActiveboolean是否有 DSP 预设处于激活生效状态

成功时 success 为 true;失败时返回 { success: false, error, code },code 见错误码。

无激活预设时 index 和 name 为 null,isActive 为 false。

config.setActiveDspPreset ​

根据索引激活指定的 DSP 预设并整体替换当前活动 DSP 链(效果等同于调用 dsp.applyPreset 传入索引);激活后无法通过此接口恢复为未选中状态

参数类型必填说明
indexinteger是待激活的 DSP 预设在 config.getDspPresets 中的位置索引不小于 0。

返回值

成功时 success 为 true;失败时返回 { success: false, error, code },code 见错误码。

播放行为配置 ​

config.getCursorFollowPlayback ​

查询 foobar2000 的「光标跟随播放(Cursor Follows Playback)」开关状态

无参数。

返回值

字段类型说明
enabledboolean「光标跟随播放」是否已开启
valueboolean与 enabled 完全一致的兼容别名字段

成功时 success 为 true;失败时返回 { success: false, error, code },code 见错误码。

config.setCursorFollowPlayback ​

设置 foobar2000 的「光标跟随播放(Cursor Follows Playback)」启用状态

参数类型必填说明
enabledboolean是是否开启「光标跟随播放」;true 为开启,false 为关闭

返回值

字段类型说明
enabledboolean成功设置后的「光标跟随播放」状态

成功时 success 为 true;失败时返回 { success: false, error, code },code 见错误码。

config.getPlaybackFollowCursor ​

查询 foobar2000 的「播放跟随光标(Playback Follows Cursor)」开关状态

无参数。

返回值

字段类型说明
enabledboolean「播放跟随光标」是否已开启
valueboolean与 enabled 完全一致的兼容别名字段

成功时 success 为 true;失败时返回 { success: false, error, code },code 见错误码。

config.setPlaybackFollowCursor ​

设置 foobar2000 的「播放跟随光标(Playback Follows Cursor)」启用状态

参数类型必填说明
enabledboolean是是否开启「播放跟随光标」;true 为开启,false 为关闭

返回值

字段类型说明
enabledboolean成功设置后的「播放跟随光标」状态

成功时 success 为 true;失败时返回 { success: false, error, code },code 见错误码。

config.getReplaygainMode ​

以数值编号形式获取当前 ReplayGain 音源模式(replaygain.getMode 提供同项设置的字符串名称)

无参数。

返回值

字段类型说明
modeinteger音源模式数值编号:0 为无,1 为音轨,2 为专辑,3 为按播放顺序
valueinteger与 mode 完全一致的兼容别名字段

成功时 success 为 true;失败时返回 { success: false, error, code },code 见错误码。

mode 值含义
0none
1track
2album
3byPlaybackOrder (auto)

config.setReplaygainMode ​

设置 ReplayGain 音源模式;支持传入数值编号 mode 或字符串名称 sourceMode(两者至少传其一,均提供时以 mode 优先,亦可通过 replaygain.setMode 修改)

参数类型必填说明
modeinteger否以数值编号指定的音源模式(取值同 config.getReplaygainMode),优先级高于 sourceMode取值 0 到 3(含端点)。
sourceMode"none" | "track" | "album" | "byPlaybackOrder" | "auto"否以名称字符串指定的音源模式:"none" (0)、"track" (1)、"album" (2)、"byPlaybackOrder" / "auto" (3);仅在未提供 mode 时生效

返回值

字段类型说明
modeinteger成功应用后的生效音源模式数值编号
valueinteger与 mode 完全一致的兼容别名字段

成功时 success 为 true;失败时返回 { success: false, error, code },code 见错误码。

传入无法识别的 sourceMode 字符串时返回 { "error": "...", "code": "INVALID_PARAMS" }。注意该失败响应不含 success 字段,请勿使用 result.success === false 做判定。传入负数 mode 时静默按 none (0) 处理并返回成功;传入大于 3 的数值不会被校验,直接原样写入并回显。

javascript
await fb2k.invoke('config.setReplaygainMode', { mode: 1 });
// 或
await fb2k.invoke('config.setReplaygainMode', { sourceMode: 'track' });

存储与偏好设置语义 ​

config.set、config.get、config.remove、config.getAll 与 config.export 操作组件专属的持久化配置对象。config.get 必填 key;键不存在时返回 found: false,若 提供了可选的 default 则返回该值。config.set 必须同时提供 key 与 value,值支持任意可序列化 JSON 数据。

音频输出与高级偏好设置方法经由 foobar2000 服务执行。其中 config.setOutputDevice 要求有效的 outputId 与 deviceId GUID;config.setOutputBuffer 支持以秒为单位的 bufferLength 或以毫秒为单位的 milliseconds。高级设置项要求传入有效 guid,其可接受的 value 类型取决于条目类型,不存在统一 schema。

光标跟随与 ReplayGain 的修改方法支持文档记载的兼容传参形式。ReplayGain 的 mode 与 value 为数值格式,sourceMode 支持 track、album、auto、byPlaybackOrder 或 none。 传入无法识别的 sourceMode 字符串时,handler 返回 INVALID_PARAMS 错误。