本地 API 与 SDK - 声核 Audcore

试着控制通道

在运行声核的这台电脑上打开本页，先在声核设置的「API 连接管理」中开启本地 API。点击连接后，在声核中允许「声核官网演示」。

尚未连接

连接并允许后，通道会显示在这里。

开关选中表示通道未静音。声核中的修改会同步到这里。浏览器询问本地网络访问权限时，请允许；断开或关闭页面会取消本次订阅。

开始使用

公开接口是本机 JSON WebSocket，协议版本为 v1。主实例默认地址为 ws://127.0.0.1:38533/api/v1；多开实例请复制各自设置中显示的地址。服务仅供运行声核的本机使用。

直接从官网引入固定版本 SDK：

import { AudcoreClient } from
  'https://audcore.utae.cn/sdk/1.0.0/audcore.mjs';

const audcore = new AudcoreClient({ appName: '我的控制面板' });
audcore.on('authorization-pending', () => {
  console.log('请在声核客户端允许连接');
});
await audcore.connect();
const channels = await audcore.getChannels();
console.log(channels);
await audcore.updateChannel(channels[0].id, { mute: false });

首次连接必须由声核用户允许，允许后 SDK 在当前网页来源保存应用凭证。重新连接无须重复允许；声核用户可以随时撤销。网页凭证绑定实际来源，包括协议、域名和端口；应用名称只是展示名称。

通信协议

资源路径和方法沿用 REST 风格，通过 WebSocket JSON 文本帧传输。请求使用唯一字符串 id 配对响应；状态码是 JSON 字段，不是 HTTP 响应码。

{"id":"1","method":"POST","path":"/connections","body":{"app_name":"我的工具"}}
{"id":"1","status":202,"data":{"connection_id":"1","instance_id":"…","authorized":false}}

首条消息必须申请连接。等待期间禁止查询和控制；用户允许后，当前连接收到私有授权事件：

{"event":"authorized","data":{"token":"应用凭证","instance_id":"…"}}

以后将凭证放入申请消息的 body.token，验证成功返回 200。凭证不要放 URL，不要发布在网页源码或共享给其他来源。等待允许最多 120 秒。

{"id":"2","method":"GET","path":"/channels"}
{"id":"2","status":200,"data":[{"id":"通道标识","index":0,"name":"麦克风","gain_db":0,"mute":false,"color":null}]}

{"id":"3","method":"PATCH","path":"/channels/通道标识","body":{"mute":true}}
{"id":"3","status":200,"data":{"id":"通道标识","index":0,"name":"麦克风","gain_db":0,"mute":true,"color":null}}

资源 ID 都是字符串。通道使用稳定标识，效果器使用实例标识，参数使用效果器暴露的参数 ID；不要用名称或列表位置识别资源。设备查询不触发声卡切换，尚未确认的能力保持未知。

{"id":"4","status":403,"data":{"error":{"code":"authorization_pending","message":"请在声核客户端允许连接"}}}

200 表示成功，201 表示订阅已创建，202 表示等待允许；400 表示请求或值无效，401 表示凭证失效，403 表示未授权，404 表示资源不存在，409 表示资源暂不可用，429 表示请求或订阅数量超过限制。本次更新新增图结构编辑，旧版主程序对新增接口返回 404；仍不开放全局设备切换、音频启停或文件操作。

资源接口

方法	路径	作用
GET / PATCH	/graph	完整图、视觉顺序、输入输出及带版本检查的批量结构编辑（本次新增）
GET	/plugins	允许添加的已安装效果器目录（本次新增）
GET	/info	运行版本、API 版本与实例标识
GET	/devices	输入输出设备、声道及当前选择
GET	/status	运行状态、采样率、缓冲、延迟与欠载次数
GET	/channels	用户通道列表，含 visual_index、align_right、inputs 与 sends；index 为内部标识，不是视觉位置
GET / PATCH	/channels/{id}	读取通道；修改 gain_db（-90 至 12 dB）、mute
GET	/channels/{id}/effects	通道中的效果器列表
GET / PATCH	/effects/{id}	读取实例；修改 bypass
GET	/effects/{id}/parameters	参数列表、名称、单位、默认值、步数、是否可写及当前值
GET / PATCH	/effects/{id}/parameters/{parameterId}	读取参数；修改 normalized（0–1）
GET	/meters	通道电平；id 为通道的 index，peak_l、peak_r、rms 为线性幅度
POST	/subscriptions	订阅资源，设置 frequency_hz
DELETE	/subscriptions/{id}	取消订阅
DELETE	/connections/current	关闭当前连接及全部订阅，保留应用授权

参数实际值 plain 和显示文字 display 由插件提供；不保证每个参数都有。写入使用归一化值，离散参数按插件步数取整，响应返回实际接受的值。只读参数不可写，离线或未加载效果器不能读取参数。

节点图与显示顺序

新增 GET /graph 返回 revision、图状态 sequence、visual_order、inputs、outputs 及完整 graph。visual_order 按普通通道在前、右侧常驻通道在后的规则列出资源 ID；通道的 visual_index 表示显示位置，不能用内部 index 代替。端点包含 pair_index、channel_offset、独立 device 和 primary_device；通道 inputs、rack、sends 分别对应输入、效果顺序和发送目标。

使用固定 SDK 的通用 request 方法调用 PATCH /graph，提交原 revision 和 edits。支持空通道新增、删除、order_chains、set_rack、set_sends 及名称和输入编辑；隐藏通道须保留，新效果器只可来自 /plugins。结构操作在音频运行时生效并进入原生撤销历史；版本冲突返回 409，加载失败会尝试恢复原有配置，恢复失败另行明确报错。音量、静音、旁通和参数沿用专用接口。

订阅 /graph 后，初次完整快照之后只推送 edits；每个增量含 base_revision、revision 和图状态 sequence。节流合并使用 changes 数组，必须依次应用，不得只取最后一项；按图状态 sequence 跳过已经确认的旧增量。图内整数 ID 与通道资源的字符串 ID 不可混用。

完整字段和请求格式见本地 API 文档。

实时订阅

{"id":"5","method":"POST","path":"/subscriptions","body":{"resource":"/channels","frequency_hz":10}}
{"id":"5","status":201,"data":{"subscription_id":"sub-1","frequency_hz":10}}
{"event":"snapshot","subscription_id":"sub-1","resource":"/channels","sequence":0,"data":[…]}
{"event":"update","subscription_id":"sub-1","resource":"/channels/通道标识","sequence":1,"data":{"id":"通道标识","name":"麦克风","index":0,"gain_db":0,"mute":true,"color":null}}
{"event":"removed","subscription_id":"sub-1","resource":"/channels/通道标识","sequence":2,"data":null}

订阅先收到一次 snapshot，随后收到子资源的 update 或 removed。例如订阅通道列表后，单个通道变化只推送该通道；只处理与自己功能相关的资源路径。初始快照可能先于创建响应到达，SDK 已处理这一顺序。

频率默认 10 Hz，范围为 1–30 Hz，表示连续变化的最大发送频率，同一资源期间合并为最新值。资源删除立即发送。原生效果器编辑器、声核界面和其他客户端的操作都会同步；仅能同步插件主动报告给宿主的参数变化。

const subscription = await audcore.subscribe(
  '/channels', { frequencyHz: 10 },
  (data, event) => console.log(event.event, event.resource, data)
);
await subscription.unsubscribe();
await audcore.disconnect();

连接断开自动取消全部订阅；SDK 默认自动重连并重新订阅，每次重新接收快照。撤销授权或拒绝连接后停止重连。服务端通过 WebSocket 心跳识别失联连接，最长约 45 秒清理；正常关闭立即清理。每连接最多 32 个订阅，消息上限 64 KiB，每秒最多 120 条请求；过慢的接收端会断开并通过重连恢复快照。

SDK 与版本

JavaScript SDK 当前版本为 1.0.0，独立于声核客户端版本和 API 协议版本。无运行依赖，可在浏览器直接使用，附带 TypeScript 类型声明。

使用时必须固定完整版本号。已发布版本的内容保持不变，修复或新增功能发布新版本，不提供自动切换版本的 latest 入口。

下载 JavaScript SDK 1.0.0 下载 TypeScript 声明查看演示源码

SDK 提供 getDevices()、getChannels()、updateChannel()、getEffects()、getParameters()、setParameter() 和 subscribe()；也可用 request(method, path, body) 访问协议资源。

使用本机脚本时传入 WebSocket 实现和自己的凭证存储适配器。网页可使用 on('state', callback)、on('authorization-pending', callback) 和 on('error', callback) 显示状态；forgetAuthorization() 清除本网页保存的凭证并断开，彻底撤销应用授权应在声核设置中操作。