# @ai-coustics/aic-sdk 中文文档

规范地址：https://npmcn.com/package/%40ai-coustics/aic-sdk/

版本：0\.26\.0
npm 元数据更新时间：2026-11-05T17:46:09.850Z
中文译文更新时间：2026-11-05T17:53:02.114Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40ai-coustics/aic-sdk
原文对照：https://npmcn.com/package/%40ai-coustics/aic-sdk/?lang=original
项目主页：https://github.com/ai-coustics/aic-sdk-node#readme
源码仓库：https://github.com/ai-coustics/aic-sdk-node

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：105 kB，6 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 18
- 运行依赖：0 个
- 首次发布：2025-10-06T13:12:43.680Z
- 最新版本发布：2026-11-05T17:46:09.452Z
- 近 30 天下载量：130574（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 19 个）

## 中文简介

节点.js 相声软件包 SDK

## 安装

```sh
npm install @ai-coustics/aic-sdk
```

也可以使用：`pnpm add @ai-coustics/aic-sdk`、`yarn add @ai-coustics/aic-sdk`、`bun add @ai-coustics/aic-sdk`

## README

# @ai-coustics/aic-sdk (英语)

节点. js 绑定相声 SDK:语音增强,语音 活动探测和音频分析.

产品文件见 [docs.ai-coustics.com (中文(中国大陆) )](https://docs.ai-coustics.com/)。 。 。 .

> \[注\] 这个SDK需要许可证密钥. 生成一个在 [开发者.ai-coustics.com](https://developers.ai-coustics.com/)。 。 。 .

## 安装

```bash
npm install @ai-coustics/aic-sdk
```

为macOS(x64, arm64),Linux(x64, arm64, glibc and musl)和 视窗 (x64, arm64, MSVC). 原生SDK是静态连接的,所以没有单独的 要安装或设置搜索路径的库.

## 快开始

```javascript
const { Model, Processor } = require('@ai-coustics/aic-sdk')

async function main() {
  // Download a model once, or fetch one manually from https://artifacts.ai-coustics.io
  const modelPath = await Model.download('quail-vf-2.3-s-16khz', './models')
  const model = Model.fromFile(modelPath)

  // Use the model's optimal configuration for the lowest delay
  const sampleRate = model.getOptimalSampleRate()
  const blockSize = model.getOptimalBlockSize(sampleRate)

  const processor = new Processor(model, process.env.AIC_SDK_LICENSE)
  processor.initialize(sampleRate, blockSize)

  // Enhance a mono block in place
  const audio = new Float32Array(blockSize)
  processor.process(audio)
}

main()
```

处理是单一的。 对于多通道音频, 混入到单声道或每声道使用一个处理器 频道. 在传递音频前初始化每个实例 。 区块必须准确包含 `blockSize` 样本。 设定第三个 `initialize` 参数, `variableBlockSize`,改为 `true` 以允许更短的块; 更长的块总是被拒绝。 这也适用于VAD 处理和分析器缓冲.

以下片段假设包含 `async` 函数。 普通JS 文件不支持 顶级 `await`。 。 。 .

用于增强、VAD、分析和全文件处理、同步和 async,已经进入 [`examples/`](https://npmcn.com/package/%40ai-coustics/aic-sdk/examples)。 。 。 .

## 模型

现有型号及其身份证列于 [文物. ai-coustics.io](https://artifacts.ai-coustics.io/)中。每个类别接受模型类型 以下列出并拒绝其他类型:

| 类 | 接受模式 |
| --- | --- |
| `Processor`, (中文(简体) ), `ProcessorAsync` | 增强, 绕行 |
| `Vad`, (中文(简体) ), `VadAsync` | 专用 VAD |
| `Analyzer` | 分析 |

`Model.download` 在Node的libuv线程池上运行,并返回对模型路径的承诺. `Model.fromFile` 内存图文件。 在模型或任何模型时不要修改或删除 从它创造出来的例子还活着.

## 增强

参数可以在音频处理时通过上下文控件更改:

```javascript
const { ProcessorParameter } = require('@ai-coustics/aic-sdk')

const context = processor.getContext()

context.setParameter(ProcessorParameter.EnhancementLevel, 0.8)
context.setParameter(ProcessorParameter.Bypass, 0)

console.log(context.getParameter(ProcessorParameter.EnhancementLevel))

// Get the audio delay in samples to align the output with other streams
console.log(context.getAudioDelay())

// Clear internal state on a stream discontinuity or seek
context.reset()
```

## 自动同步处理

`ProcessorAsync` 财务报告和审定财务报表 `VadAsync` 在节点的 libuv 线程池上运行初始化和处理. 等待这些呼叫,以保持事件循环可供其他工作使用,例如网络请求. 建筑和处置保持同步.

使用 `Processor` 或者说 `Vad` 或用可以阻断的批量脚本 呼叫线。 这些课会处理每个块,没有承诺或输入副本.

```javascript
const { Model, ProcessorAsync } = require('@ai-coustics/aic-sdk')

const processor = await new ProcessorAsync(model, process.env.AIC_SDK_LICENSE).withConfig(sampleRate, blockSize)

// The input remains unmodified; the promise resolves to the enhanced samples.
const audio = new Float32Array(blockSize)
const enhanced = await processor.process(audio)
```

两个ASync班在排队前复制输入并返回新的 `Float32Array`。 。 。 . `ProcessorAsync.process` 返回增强的样本; `VadAsync.process` 返回原始内容 样本。 来电者输入仍未修改.

上下文创建是同步的. 返回上下文的方法是同步的,并且可以 用于处理运行时 :

```javascript
const context = await processor.getContext()
context.setParameter(ProcessorParameter.EnhancementLevel, 0.8)
```

### 运行多条流

每个流使用一个实例并等待每个操作,然后提交下一个 。 同时 无法保证在提交命令中执行对一个案件发出的呼吁。 单独实例 可以同时处理流.

```javascript
const processors = await Promise.all(
  streams.map(() => new ProcessorAsync(model, licenseKey).withConfig(sampleRate, blockSize)),
)

const enhanced = await Promise.all(processors.map((processor, i) => processor.process(blocks[i])))
```

工作运行在节点的 libuv 线程池上, 它默认是四个线程, 并共享到 `fs`, (中文(简体) ), `dns` 财务报告和审定财务报表 `crypto`为平行运行更多的溪流,提高 `UV_THREADPOOL_SIZE` 在此之前 节点开始 :

```bash
UV_THREADPOOL_SIZE=16 node server.js
```

`AIC_NUM_THREADS` 不适用于这些绑定; async音频工作使用libuv.

## 语音活动检测

VAD运行一个专门的VAD模型,并且独立于任何处理器驱动.

```javascript
const { Model, Vad, VadParameter } = require('@ai-coustics/aic-sdk')

const vadModel = Model.fromFile(await Model.download('vad-ms-2.1-xxs-16khz', './models'))
const vad = new Vad(vadModel, process.env.AIC_SDK_LICENSE)

const sampleRate = vadModel.getOptimalSampleRate()
vad.initialize(sampleRate, vadModel.getOptimalBlockSize(sampleRate))

const context = vad.getContext()
context.setParameter(VadParameter.Sensitivity, 0.8)

vad.process(block) // reads the block, does not modify it

if (context.isSpeechDetected()) {
  console.log('speech')
}

// Raw model output, before speech-hold and thresholding
console.log(context.getRawVadProbability())
```

### 在原音频上运行 VAD

当增强和检测一起运行时,将 VAD 输入 **原文** 输入,而不是 处理器输出 。 增强是用来改变信号,所以在输出时检测 意思是在音频上运行 VAD , 它不再符合其模型的预期, 它堆放 处理器在预测延迟之上的延迟。 因为 `vad.process` 保留其输入 不动,在增强前运行它。 配置样本率相同的两个实例和 块大小 :

```javascript
vad.process(block) // reads the block
processor.process(block) // enhances it in place
```

这两次拖延描述了不同的事物,并且是独立的:

```javascript
context.getAudioDelay() // enhanced audio lags the input by this many samples
vadContext.getPredictionDelay() // the VAD decision lags the same input by this many
```

预测延迟不适用于音频. 用它来调整演讲决定 输入音频.

### 以能源为基础的语音活动检测

增强处理器可以在输出相混合前探测到其增强信号中的语音, 不装入单独的 VAD 模型。 处理前创建上下文,然后读取 每个块 :

```javascript
const { VadParameter } = require('@ai-coustics/aic-sdk')

const vadContext = processor.getEnergyVadContext()

// The energy VAD uses 1.0 to 15.0; higher values detect quieter speech.
vadContext.setParameter(VadParameter.Sensitivity, 6.0)

processor.process(block)
console.log(vadContext.isSpeechDetected())

// Equal to the processor's audio delay
console.log(vadContext.getPredictionDelay())

// Clear the prediction on a stream discontinuity or seek
vadContext.reset()
```

一个处理器的上下文共享一个探测器,其方法可以在音频时调用 正在处理中。 处理器处理完毕后上下文仍然有效, 但没有收到 更多音频。 创建上下文即使在处理被绕过或 增强级为 0. `processor.getContext().reset()` 还重放能量VAD. 打开 `ProcessorAsync`, (中文(简体) ), `getEnergyVadContext()` 返回一个承诺.

使用 `Vad` 具有语音概率专用VAD模型(`getRawVadProbability()`)或(或) 不依赖于增强模型的检测.

## 分析

分析模型评分音频质量. 收集音频用 `buffer`,然后用 `analyzeAsync` 或者说 `analyze`。 。 。 .

```javascript
const { Model, Analyzer } = require('@ai-coustics/aic-sdk')

const analysisModel = Model.fromFile(await Model.download('tyto-1.2-l-16khz', './models'))
const analyzer = new Analyzer(analysisModel, process.env.AIC_SDK_LICENSE)

const sampleRate = analysisModel.getOptimalSampleRate()
analyzer.initialize(sampleRate, analysisModel.getOptimalBlockSize(sampleRate))

analyzer.buffer(block)

// Runs the model on a worker thread. `analyze()` does the same on the calling thread.
const result = await analyzer.analyzeAsync()
console.log(result.riskScore, result.noise, result.speakerReverb)
```

`buffer` 是同步的,不获取分析器锁。 音频收藏罐 继续时 `analyzeAsync` 运行在工人线。 使用 `analyze` 当屏蔽时 调用线程是可以接受的,比如在CLI或专职工人中.

分析使用由模型确定的固定音频持续时间. 旧样本被丢弃 随着新的音频到达。 如果收集到的音频不足,则分析台将剩余 以沉默输入.

呼吁 `analyze`, (中文(简体) ), `reset`, (中文(简体) ), `updateBearerToken`, (中文(简体) ), `terminateSession` 财务报告和审定财务报表 `dispose` 获取 分析器锁定并可能在同步分析运行时被屏蔽 . `initialize` 仅配置 那个收藏家.

所有分数从0.0到1.0. 每一个领域,除了 `speakerLoudness`下值 表示问题较少的音频. `riskScore` 预测下游发生故障的可能性 模式如语音对文本,VAD或转接.

## 遥测

遥测学遵循运行时环境(例如. `AIC_SDK_OTEL_ENABLE`) (中文(简体) ). 为了一个 单个实例 :

```javascript
const processor = new Processor(model, licenseKey, {
  enable: true,
  sessionId: 'my-session',
  exportIntervalMs: 60000,
})
```

遥测会话在它的原生对象被破坏后结束 。 使用 `terminateSession()` 改为 请求在特定生命周期中终止。 一旦处理完毕,处理器 和VAD无法再处理音频,分析器也无法再分析缓冲音频. 打开 `ProcessorAsync` 财务报告和审定财务报表 `VadAsync`,终止运行在 libuv 工人线并返回 一个承诺,因为它可能阻碍.

如果您的许可密钥是 JWT, 请刷新它的位置, 而不是重建对象 :

```javascript
context.updateBearerToken(renewedJwt)
```

## 内存管理

`Model`, (中文(简体) ), `Processor`, (中文(简体) ), `ProcessorAsync`, (中文(简体) ), `Vad`, (中文(简体) ), `VadAsync` 财务报告和审定财务报表 `Analyzer` 拥有大型本土 小 JavaScript 对象后面的分配。 具有约束力的报告估计了本地记忆 v8的用法使得垃圾收集器能够对这些分配进行核算. 这影响了 收藏频率,但不保证对象何时释放.

使用 `dispose()` \* 在特定地点释放本地资源,而不是等待 垃圾收集 :

```javascript
const processor = new Processor(model, licenseKey)
try {
  processor.initialize(sampleRate, blockSize)
  processor.process(block)
} finally {
  processor.dispose()
}
```

之后 `dispose()`,所有方法除外 `dispose()` 失败; 重复处理没有效果. Async方法拒绝了他们的诺言. 如果工人持有 处置会阻断呼叫线 本地对象的锁。 处理失败后获得锁的排队工作 .

处置一个模型会发布它对于模型数据的参考. 处理器、 VAD 和分析器 从它创造的,保留了他们自己的参考资料,并且可以使用.

清理时间也会影响本地记忆的使用:

-   对象定稿时, 原生清理在事件循环上运行, 而不是同步 垃圾收集。 决赛者运行在活动启动转弯上,所以批量地创建了许多 这些对象背靠背地持有本土内存,直到循环转向. 一个 `await` 一个 已解约( 微任务) 还不够; 真实的 Aync 边界, 如 I/ O, `setTimeout` 或者说 `setImmediate` 对 一个紧凑的同步环路 创造了上千个 对象在循环期间积累其本地内存; 创建这些 单位工作对象在实际合成边界后,或重复使用单个实例.
-   处置后RSS可能会继续提升,因为分配器可以保留释放的内存 用于再利用。 峰值内存的用法取决于同时活出的次数, 包括待最后确定的物体.

## 发展

建造、测试、设定基准和发布本套材料 [发展.md](https://npmcn.com/package/%40ai-coustics/aic-sdk/DEVELOPMENT.md)。 。 。 .

## 许可证

此节点包装器在Apache 2. 0 许可证下分发(`LICENSE`) (中文(简体) ). 核心的SDK它 根据专有的 AIC- SDK 许可证分发链接 (单位:千美元)`LICENSE.AIC_SDK`) (中文(简体) ).

## 常见问题

### @ai-coustics/aic-sdk 是什么？

节点\.js 相声软件包 SDK

### 如何安装 @ai-coustics/aic-sdk？

在项目目录运行 npm install @ai-coustics/aic-sdk，或使用 pnpm add / yarn add / bun add。

### @ai-coustics/aic-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @ai-coustics/aic-sdk 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @ai-coustics/aic-sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>= 18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @ai-coustics/aic-sdk 可以商用吗？

@ai-coustics/aic-sdk 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @ai-coustics/aic-sdk 的下载量有多少？

根据 npm 官方下载统计，@ai-coustics/aic-sdk 在 2026/10/05 – 2026/11/03 这 30 天内被下载 130,574 次，日均约 4,352 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @ai-coustics/aic-sdk 还在维护吗？

最新版本 0\.26\.0 发布于 2026/11/06（2 天前）；至今共发布 20 个版本，其中过去 12 个月发布了 19 个；首次发布于 2025/10/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。