# @echogarden/audio-io 中文文档

规范地址：https://npmcn.com/package/%40echogarden/audio-io/

版本：0\.4\.2
npm 元数据更新时间：2025-05-17T09:39:36.775Z
中文译文更新时间：2026-11-13T05:03:37.505Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40echogarden/audio-io
原文对照：https://npmcn.com/package/%40echogarden/audio-io/?lang=original
项目主页：https://github.com/echogarden-project/audio-io#readme
源码仓库：https://github.com/echogarden-project/audio-io

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

- 包体积（解压后）：798 kB，31 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：1 个
- 首次发布：2024-10-24T19:23:37.046Z
- 最新版本发布：2025-05-17T09:39:36.557Z
- 近 30 天下载量：13576（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 0 个）

## 中文简介

通过平台专用API提供低等音频I/O. 包括所有支持的平台的预编译附加.

## 安装

```sh
npm install @echogarden/audio-io
```

也可以使用：`pnpm add @echogarden/audio-io`、`yarn add @echogarden/audio-io`、`bun add @echogarden/audio-io`

## README

# 回声园音频 I/ 欧

一个提供低级音频输出的节点.js软件包(**音频输入尚未执行**用于各种平台的常见音频API:

-   [MME (多媒体扩展)](https://en.wikipedia.org/wiki/Windows_legacy_audio_components) (Wave Out) 在Windows(x64, arm64) 上 :
-   [核心音频](https://en.wikipedia.org/wiki/Core_Audio) (通过低纬度) [音频单位](https://en.wikipedia.org/wiki/Audio_Units))在macOS上(x64,arm64)使用
-   [ALSA (高级 Linux 声音架构)](https://en.wikipedia.org/wiki/Advanced_Linux_Sound_Architecture) 在 Linux (x64, arm64) 上显示

代码非常简陋,不依赖任何外文库,只有直接的系统调用.

每个平台都有一个独立 `cpp` 源文件,它使用Node Addon API(C++)生成一个与给定平台的Node.js运行时间相融合的Node.js addon.

增量作为 **仅预编译二进制**,这意味着软件包不需要安装任何构建时间后处理.

## 安装

```sh
npm install @echogarden/audio-io
```

## 低级音频输出

此示例使用 `createAudioOutput`,并使用回调直接写入音频设备输出缓冲器。 在需要直接、实时控制或进行低频音频处理的情况下,这是有用的.

如果您更有兴趣播放一个已有的音频文件,或音频缓冲器,可以跳过这个,移动到下面的高级操作部分.

```ts
// Import module
import { createAudioOutput } from '@echogarden/audio-io'

// Define an audio output handler function
function audioOutputHandler(outputBuffer: Int16Array) {
    // Write 16-bit signed integer little-endian samples to `outputBuffer`.
    // If there are multiple channels, interleave them, like `LRLRLRLR..` for stereo.
}

// Create audio output, passing a configuration object and the handler
const audioOutput = await createAudioOutput({
    sampleRate: 44100, // Sample rate in Hz, should be an integer like 44100, 22050, 8000
    channelCount: 2, // Channel count, likely 1 (mono), or 2 (stereo)
    bufferDuration: 100.0, // Target audio output buffer duration, in milliseconds. Defaults to 100.0
}, audioOutputHandler)

// ...

// When done, call audioOutput.dispose(),
// which will close the audio output and free any associated memory or handles.
await audioOutput.dispose()
```

**页:1**数字 :

-   目前只支持了16位,已签名的整数,小端,相接的缓冲. 确保音频数据在写入处理器缓冲器前转换为此格式

**说明 `bufferDuration`**数字 :

-   在 MME (Windows) 和 ALSA (Linux) 上 `bufferDuration` 用于直接计算输出缓冲大小
-   在 Core Audio (macOS) 上,它将用于设置最大缓冲大小, 但驱动程序选择的实际缓冲大小可能要小得多

## 高级别回放方法

这些方法包围 `createAudioOutput` 并会在内部创建新的音频输出,播放给定的音频数据,然后处理音频输出.

#### `playWaveData(waveData: Uint8Array, options?: PlaybackOptions, positionCallback?: PositionCallback)`

播放 WAVE 格式字节, 给定为 `Uint8Array`数字 :

```ts
// Import modules
import { readFile } from 'fs/promises`'
import { playWaveData } from '@echogarden/audio-io'

const waveData: Uint8Array = await readFile('test.wav')

await playWaveData(waveData, { bufferDuration: 125 }) // 125ms buffer duration
```

`positionCallback` 参数接受一个在播放音频时会反复调用的回调,并带有样本精确回放位置数据. 例如:

```ts
await playWaveData(waveData, {}, (callbackData) => {
    console.log(`Current audio time position: ${callbackData.timePosition}`)
    console.log(`Current sample offset: ${callbackData.sampleOffset}`)
})
```

`positionCallback` 还被以下所有回放方法所接受.

如果您想要独立使用下方的 WAVE 编码器/解码器, 您可以导入 `@echogarden/wave-codec` 直接将软件包放入您的工程中,参见 [其文档](https://github.com/echogarden-project/wave-codec) 更多细节.

#### `playFloat32Channels(float32Channels: Float32Array[], sampleRate: number, options?: PlaybackOptions, positionCallback?: PositionCallback)`

播放浮点样本,作为数组 `Float32Array`中,每个 `Float32Array` 是一个单独的频道 :

```ts
// Import module
import { playFloat32Channels } from '@echogarden/audio-io'

const float32Channels: Float32Array[] = //... retrieve audio samples

await playFloat32Channels(float32Channels, 44100) // 44100 Hz, default buffer duration
```

#### `playInt16Samples(int16Samples: Int16Array, sampleRate: number, channelCount: number, options?: PlaybackOptions, positionCallback?: PositionCallback)`

游戏签名, 16- bit interleaved, PCM 音频样本, 给定为 `Int16Array`数字 :

```ts
// Import module
import { playInt16Samples } from '@echogarden/audio-io'

const int16Samples: Int16Array = //... retrieve audio samples

await playInt16Samples(int16Samples, 44100, 2) // 44100 Hz, 2 channels, default buffer duration
```

#### `playTestTone(options?: TestToneOptions, positionCallback?: PositionCallback)`

播放立体声测试音调(sine wave),以测试音频输出是否工作正确.

```ts
import { playTestTone } from '@echogarden/audio-io'

await playTestTone({
    totalDuration: 1,
    sampleRate: 48000,
    bufferDuration: 100,
    frequencyLeft: 440,
    frequencyRight: 280,
})
```

## 盖起外加

为所有支持的平台捆绑了预建的附加物.

要重建他们自己,看 [用于构建附加物的指南](https://npmcn.com/package/%40echogarden/audio-io/docs/Building.md)。 。 。 .

## 还是实验性的,需要反馈

所有代码都是从零开始写的,意味着它还没有在众多的系统上进行测试:

-   Windows 添加器只在 Windows 11 上测试过
-   Linux addon只在WSL2(Ubuntu 24.04)和VirtualBox(仅x64)的一款Ubuntu 23.10 VM中测试过
-   macOS addon 仅在VMWare的 macOS 13 VM 中测试过(只有x64)

如果你遇到任何碰撞,出乎意料的错误,或音频问题,如扭曲或文物,它们可能比较容易解决. 开个问题告诉我.

## 未来

-   **音频投入** 一旦音频产出得到足够稳定和测试,将实施
-   列表和选择音频输出设备的选项, 并使用默认设备以外的播放设备
-   通过检测输出设备属性,更好地处理多通道音频(超过2个频道). 如果默认输出设备不支持给定的频道数, 它会出错
-   通过 Windows 添加可选的下等潜伏 I/O [瓦萨皮](https://en.wikipedia.org/wiki/Technical_features_new_to_Windows_Vista#Audio_stack_architecture) API( 支持于 Windows Vista 或更新)

## 许可证

麻省理工学院

## 常见问题

### @echogarden/audio-io 是什么？

通过平台专用API提供低等音频I/O\. 包括所有支持的平台的预编译附加\.

### 如何安装 @echogarden/audio-io？

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

### @echogarden/audio-io 支持 TypeScript 吗？

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

### @echogarden/audio-io 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

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

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

### @echogarden/audio-io 可以商用吗？

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

### @echogarden/audio-io 的下载量有多少？

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

### @echogarden/audio-io 还在维护吗？

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