# @descript/web-audio-js 中文文档

规范地址：https://npmcn.com/package/%40descript/web-audio-js/

版本：0\.15\.3-patched\.6
npm 元数据更新时间：2026-08-06T18:31:39.110Z
中文译文更新时间：2026-11-12T01:00:37.111Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40descript/web-audio-js
原文对照：https://npmcn.com/package/%40descript/web-audio-js/?lang=original
项目主页：https://github.com/descriptinc/web-audio-js/
源码仓库：https://github.com/descriptinc/web-audio-js

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

- 包体积（解压后）：2.6 MB，536 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 12\.0\.0
- 运行依赖：6 个
- 首次发布：2019-12-13T01:12:33.652Z
- 最新版本发布：2023-04-01T01:18:47.189Z
- 近 30 天下载量：15212（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 0 个）

## 中文简介

纯JS实施网络音频 API

## 安装

```sh
npm install @descript/web-audio-js
```

也可以使用：`pnpm add @descript/web-audio-js`、`yarn add @descript/web-audio-js`、`bun add @descript/web-audio-js`

## README

# @descript/web-audio-js (英语)

![Node CI](https://github.com/descriptinc/web-audio-js/workflows/Node%20CI/badge.svg) [![NPM Version](https://img.shields.io/npm/v/@descript/web-audio-js.svg)](https://www.npmjs.org/package/@descript/web-audio-js) [![License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](https://mohayonao.mit-license.org/)

> 《公约》执行情况 [网络音频 API](https://www.w3.org/TR/webaudio/)

叉子为 [莫哈约瑙/网络-音频-引擎](https://github.com/mohayonao/web-audio-engine) 修改如下:

-   使用类型脚本并修正一些类型( T)[5号](https://github.com/descriptinc/web-audio-js/pull/5)(中文(简体) )
    -   删除 `BaseAudioContext.suspend()` (单位:千美元)[6号](https://github.com/descriptinc/web-audio-js/pull/6)(中文(简体) )
-   添加新内容 `RawDataAudioContext` (单位:千美元)[5号](https://github.com/descriptinc/web-audio-js/pull/5)(中文(简体) )
-   添加对支持 `DynamicsCompressorNode` (单位:千美元)[1号](https://github.com/descriptinc/web-audio-js/pull/1)(中文(简体) )
-   错误修正
    -   用于 `BiquadFilterNode` 财务报告和审定财务报表 `DelayNode` (单位:千美元)[8号](https://github.com/descriptinc/web-audio-js/pull/8)(中文(简体) )
    -   修复 WAVE 文件解码( E)[5号](https://github.com/descriptinc/web-audio-js/pull/5)(中文(简体) )
    -   修补 `AudioNode.disconnect(x)` 不断开( n)[7号](https://github.com/descriptinc/web-audio-js/pull/7)(中文(简体) )

## 安装

```
npm install --save web-audio-engine
```

## API 密码

`web-audio-engine` 提供一些 `AudioContext` 每个使用大小写:音频播放、渲染和模拟.

### 类: StreamAudio Context

`StreamAudioContext` 将原始 PCM 音频数据写入可写入的节点流 。 它可用于实时回放音频.

##### 新建 StreamAudio Context( 选择? : 对象)

创建新的 StreamAudioContext 实例 .

-   `opts.sampleRate: number` 音频样本率(以赫兹为单位) - _默认: 44100_
-   `opts.numberOfChannels: number` 音频频道(如2:立体声) - _默认: 2_
-   `opts.blockSize: number` 每个渲染量子样本 - _默认: 128_
-   `opts.bitDepth: number` 每个样本的位数 - _默认: 16_
-   `opts.float: boolean` 使用浮点值 - _默认: 假_

##### 上下文.pipe(目的地:流. 写作:溪. 可写

: 构造_工人: TODO: 书面诽谤_

```js
import { StreamAudioContext as AudioContext } from 'web-audio-engine';
const context = new AudioContext();

// Set the output for audio streaming
context.pipe(process.stdout);

// If you want to playback sound directly in this process, you can use 'node-speaker'.
// const Speaker = require("speaker");
// context.pipe(new Speaker());

// Start to render audio
context.resume();

// composeWith(context);
```

### 类: 提交审计文本

`RenderingAudioContext` 记录音频数据并进行分步处理。 它用于导出到 wav 文件或测试网络音频应用程序.

##### 新建音频文本( 选择 ? : 对象)

创建新 `RenderingAudioContext` 举个例子.

-   `opts.sampleRate: number` 音频样本率(以赫兹为单位) - _默认: 44100_
-   `opts.numberOfChannels: number` 音频频道(如2:立体声) - _默认: 2_
-   `opts.blockSize: number` 每个渲染量子样本 - _默认: 128_

##### 上下文. processTo( 时间: 数字- 字符串)

执行渲染过程直到提供的时间.

-   `time`:例如:. `10` (10秒钟), `"01:30.500"` (转换为90.5秒)

##### 上下文. exportAsAudioData (: AudioData) : 音频数据

将数据导出为 `AudioData` 格式.

##### 上下文.encode AudioData(自动数据: AudioData, 选择?:obobject):承诺 < ArrayBuffer >

将音频数据编码为二进制格式.

-   `audioData: AudioData`
-   `opts.bitDepth: number` 每个样本的位数 - _默认: 16_
-   `opts.float: boolean` 使用浮点值 - _默认: 假_

```js
import fs from 'fs';
import { RenderingAudioContext as AudioContext } from 'web-audio-engine';
const context = new AudioContext();

// composeWith(context);

context.processTo('00:01:30.000');
// context.currentTime -> 90.00054421768708

context.processTo('00:02:00.000');
// context.currentTime -> 120.00072562358277

const audioData = context.exportAsAudioData();

context.encodeAudioData(audioData).then((arrayBuffer) => {
  fs.writeFile('output.wav', new Buffer(arrayBuffer));
});
```

### 类: RawDataAudio Context

`RawDataAudioContext` 允许您同步步入音频Context。 用于流出输出 控制费率

##### 新建 RawDataAudioContext( 选择? : 对象)

创建新 `RenderingAudioContext` 举个例子.

-   `opts.sampleRate: number` 音频样本率(以赫兹为单位) - _默认: 44100_
-   `opts.numberOfChannels: number` 音频频道(如2:立体声) - _默认: 2_
-   `opts.blockSize: number` 每个渲染量子样本 - _默认: 128_

##### 上下文. process(channelData: Float32Array\[\],相左:数字=0)

下一个 `blockSize` 音频样本输入 `channelData`。 。 。 .

```js
import { RawDataAudioContext } from 'web-audio-engine';
const context = new RawDataAudioContext();
const { blockSize } = context;
const channelData = [
  new Float32Array(blockSize),
  new Float32Array(blockSize),
];

for (let i = 0; i < 100_000; i += blockSize)
  context.process(channelData);
  // Do something with channeLData
}
```

### 类: Web AudioContext

: 构造_工人: TODO: 书面诽谤_

##### 新 WebAudioContext( 选择? : 对象)

创建新 `WebAudioContext` 举个例子.

-   `opts.context?: AudioContext` 本地网络音频 API 音频连接实例
-   `opts.destination?: AudioNode` - 说吧 _默认: 选择. context.destination_
-   `opts.numberOfChannels: number` 音频频道(如2:立体声) - _默认: 2_
-   `opts.blockSize: number` 每个渲染量子样本 - _默认: 128_

```html
<script src="/path/to/web-audio-engine.js"></script>
<script>
  var context = new WebAudioEngine.WebAudioContext({
    context: new AudioContext(),
  });

  // composeWith(context);

  context.resume();
</script>
```

### 类: 离线审计文本

此上下文兼容 Natvie Web 音频 API `OfflineAudioContext`。 。 。 .

```js
import { OfflineAudioContext } from 'web-audio-engine';
const context = new OfflineAudioContext(2, 44100 * 10, 44100);

// composeWith(context);

context.startRendering().then((audioBuffer) => {
  console.log(audioBuffer);
});
```

### 接口:音频数据

```
interface AudioData {
  numberOfChannels?: number;
  length?: number;
  sampleRate: number;
  channelData: Float32Array[];
}
```

### 解码器

默认解码器 `web-audio-engine` 只支持“wav”格式。 如果您需要支持其他音频格式,您需要自己准备解码器.

##### decoder.get(类型:字符串):函数

返回当前设置的解码功能.

##### decoder.set(类型:字符串,解码Fn:函数)

设置解码功能.

-   `decodeFn: (audioData: ArrayBuffer, opts?: object) => Promise< AudioData >` 解码来用.

##### decoder.decode (autioData: ArrayBuffer, 选取? 对象):承诺 < AudioData >

执行解码.

-   `audioData: ArrayBuffer`

###### mp3 解码器示例

```js
import wae from 'web-audio-engine';
import mp3decoder from '/path/to/mp3decoder';
import fs from 'fs';
wae.decoder.set('mp3', mp3decoder);
const AudioContext = wae.RenderingAudioContext;
const context = new AudioContext();
const audioData = fs.readFileSync('amen.mp3');

context.decodeAudioData(audioData).then((audioBuffer) => {
  console.log(audioBuffer);
});
```

### 编码器

默认编码器 `web-audio-engine` 只支持“wav”格式。 如果您需要支持其他音频格式, 您需要自己准备编码器 .

##### 编码器.get(类型:字符串):函数

返回当前设置的编码函数 .

##### 编码器. set(类型:字符串,编码Fn:函数)

设置编码功能.

-   `encodeFn: (audioData: AudioData, opts?: object) => Promise< ArrayBuffer >` 所用编码.

##### encoder.encode(audioData: AudioData, options?: object): 保证 < ArrayBuffer >

执行编码.

-   `audioData: AudioData`
-   `opts.type: string` 音频格式类型 - _默认: "wav"_

###### mp3 编码器示例

```js
import wae from 'web-audio-engine';
import mp3encoder from '/path/to/mp3encoder';
import fs from 'fs';
wae.encoder.set('mp3', mp3encoder);
const AudioContext = wae.RenderingAudioContext;
const context = new AudioContext();
const audioData = context.exportAsAudioData();

context.encodeAudioData(audioData, { type: 'mp3' }).then((arrayBuffer) => {
  fs.writeFile('output.mp3', new Buffer(arrayBuffer));
});
```

## 已执行 API

-   `AnalyserNode`
-   `AudioBuffer`
-   `AudioBufferSourceNode`
-   `AudioContext`
-   `AudioDestinationNode`
-   `AudioNode`
-   `AudioParam`
-   `BiquadFilterNode` (不支持自动率参数)
-   `ChannelMergerNode`
-   `ChannelSplitterNode`
-   `DelayNode` (无声
-   `DynamicsCompressorNode`
-   `GainNode`
-   `IIRFIlterNode`
-   `OscillatorNode` (使用波状合成,不使用周期波)
-   `PeriodicWave`
-   `ScriptProcessorNode`
-   `StereoPannerNode`
-   `WaveShaperNode`
-   其他未执行的节点将不加修改地将其输入传递给其输出.
-   见: [比较 已执行节点图](https://github.com/mohayonao/web-audio-engine/wiki/Compatibility-Comparison)

## 示例

```js
import Speaker from 'speaker';
import { StreamAudioContext as AudioContext } from 'web-audio-engine';
const context = new AudioContext();

const osc = context.createOscillator();
const amp = context.createGain();

osc.type = 'square';
osc.frequency.setValueAtTime(987.7666, 0);
osc.frequency.setValueAtTime(1318.5102, 0.075);
osc.start(0);
osc.stop(2);
osc.connect(amp);
osc.onended = () => {
  context.close().then(() => {
    process.exit(0);
  });
};

amp.gain.setValueAtTime(0.25, 0);
amp.gain.setValueAtTime(0.25, 0.075);
amp.gain.linearRampToValueAtTime(0, 2);
amp.connect(context.destination);

context.pipe(new Speaker());
context.resume();
```

## 在线演示

在线演示在这里。 在这个网站,你可以比较 `web-audio-engine` 和本地网络音频 API.

-   [https://mohayonao.github.io/web-audio-engine/demo/ (英语)](https://mohayonao.github.io/web-audio-engine/demo/)

## 离线演示

```
$ git clone git@github.com:mohayonao/web-audio-engine.git
$ cd web-audio-engine
$ npm install && npm run build
$ cd demo
$ npm install
$ node demo --help
```

最简单的游戏演示 `node-speaker`。 。 。 .

```
$ node demo sines
```

渲染并导出到 wav 文件 .

```
$ node demo -o out.wav sines
```

## 在线基准

目前,这个基准在Chrome或Safari都行不通,请使用Firefox.

-   [https://mohayonao.github.io/web-audio-engine/benchmark/ 页面存档备份,存于互联网档案馆](https://mohayonao.github.io/web-audio-engine/benchmark/)

## 离线基准

```
$ git clone git@github.com:mohayonao/web-audio-engine.git
$ cd web-audio-engine
$ npm install && npm run build
$ cd benchmark
$ npm install
$ node .
```

## 许可证

麻省理工学院

## 常见问题

### @descript/web-audio-js 是什么？

纯JS实施网络音频 API

### 如何安装 @descript/web-audio-js？

在项目目录运行 npm install @descript/web-audio-js，或使用 pnpm add / yarn add / bun add。

### @descript/web-audio-js 支持 TypeScript 吗？

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

### @descript/web-audio-js 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @descript/web-audio-js 需要什么版本的 Node\.js？

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

### @descript/web-audio-js 可以商用吗？

@descript/web-audio-js 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @descript/web-audio-js 的下载量有多少？

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

### @descript/web-audio-js 还在维护吗？

最新版本 0\.15\.3-patched\.6 发布于 2023/04/01（3 年前）；至今共发布 12 个版本，其中过去 12 个月发布了 0 个；首次发布于 2019/12/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。