# @goodboydigital/soundboy 中文文档

规范地址：https://npmcn.com/package/%40goodboydigital/soundboy/

版本：1\.0\.6
npm 元数据更新时间：2024-10-07T21:44:47.871Z
中文译文更新时间：2026-11-16T19:14:08.636Z
软件包许可：ISC

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

原始 npm 页面：https://www.npmjs.com/package/%40goodboydigital/soundboy
原文对照：https://npmcn.com/package/%40goodboydigital/soundboy/?lang=original
项目主页：https://github.com/Goodboy-Digital/soundboy#ReadMe.md
源码仓库：https://github.com/Goodboy-Digital/soundboy

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

- 包体积（解压后）：99.3 kB，26 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2019-07-24T14:19:53.176Z
- 最新版本发布：2020-12-01T14:46:05.096Z
- 近 30 天下载量：4065（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 0 个）

## 中文简介

管理声音的回放

## 安装

```sh
npm install @goodboydigital/soundboy
```

也可以使用：`pnpm add @goodboydigital/soundboy`、`yarn add @goodboydigital/soundboy`、`bun add @goodboydigital/soundboy`

## README

# 声音Boy - 一个新的声音管理器

SoundBoy提供了一个简单的界面,通过它在不同频道(如sfx,vo,音乐)上播放声音,并具有回调和声音回放/控制的灵活性. SoundBoy将在一个SoundChannel上播放SoundInstances. A SoundInstance是一款音频,可以独立控制,循环,在它生命周期的各个点执行完整和发送信号的回调. 在SoundChannel上播放一个声音Instance,它提供了一次控制该频道上所有声音的能力(如音量,暂停,重启,停止).

它现在使用 [(原始内容存档于2018-09-26). Howler.js](https://howlerjs.com/) 然而,对于音频后端来说,这种依赖被隔离为两个类别,一个是SoundFactory,一个是SoundInstance执行,提供SoundBoy和Howler之间的桥梁——所有SoundBoy逻辑和特性都是独立于基础音频库而执行的.

# 使用量

## 注册声音

声音以声音可选对象注册,其中包含将创建所有声音实例的基础数据.

```js
SoundBoy.registerSound({
    // id and src are required
    id: 'laser',
    src: 'assets/audio/laser.wav',
    // optional (default values shown)
    preload: false, // set to true to immediately start loading the sound
    stream: false, // set to true to enable sound to start playing before fully loaded
    loop: false, // set to true to loop indefinitely
    volume: 1 // this is the base volume of the sound, the actual sound volume will be the product of this, the sound instance volume, and the volume of the channel the sound is played on
})
```

## 播放声音

```js
// just play a sound effect
const laserSound = SoundBoy.playSfx('laser');
// sound can be controlled independently:
laserSound.volume = 0.5;

// play some vo with a callback
SoundBoy.playVo('instructions', {
    callback: ()=> this.startGame()
});
```

## 声道

声音在SoundChannel上播放,默认有 sfx,音乐和语音的频道,但您可以任意创建尽可能多的频道,它们被独特的字符串id引用:

```js
SoundBoy.addChannel('animals');
SoundBoy.playOnChannel('woof', 'animals');
```

一个声音通道可以将它上的所有声音作为一个组来控制,提供 api 来控制 `mute`, (中文(简体) ), `volume`, (中文(简体) ), `pause`, (中文(简体) ), `resume` 财务报告和审定财务报表 `stop`,以及一个 `forEach` 在频道目前所有声音实例上访问和履行任何功能的方法.

声音频道有一个 `singleFile` 属性,如果设置为真,将限制频道只在任何时间播放单个声音。 如果一个声音在频道被要求播放一个声音时已经播放,它会在两个声音之间交叉. 默认情况下,vo和音乐频道会被设定为以这种方式行事,而音乐频道则拥有更长的交叉法时间.

## 声音实例

每次播放一个声音,都会创造出一个新的声音Instance. A SoundInstance 会将声音播放到结尾,然后循环或停止,这取决于声音选项在注册声音时的设置以及播放声音时使用的(可选)声音Instance选项.

```js
SoundBoy.playSfx('footstep', {
    // these are all optional, default values are shown:
    volume: 1,
    loops: 1,
    panning: 0,
    rate: 1,
    callback: undefined,
    callbackScope: undefined,
    wontInterrupt: false // if true, the sound won't interrupt an existing sound on a singleFile SoundChannel
    callbackOnInterrupt: false, // if true, execute callback if this sound is subsequently interrupted on a singleFile SoundChannel
})
```

当一个声音完整(它一直播放到结尾,而且没有再播放回路)时,它会停下来,从播放的声道中取出,并被处理 - 声音Instance不再使用,除非一个回调或Conflete处理器通过重启,提示或寻求实例来保持声音活性.

## 声音实例调用

这个 `callback` 属性在播放声音时使用的 SoundInstance Options 上,可用于指定声音完成播放时要调用的函数。 回调应是一种约束或箭头功能,以避免范围问题。 或者 `callbackScope` 也可以在 SoundInstance 选项上指定 `this` 应下定决心进入回调.

默认情况下,只有在一个声音完成时才执行回调,而不执行停止的声音,除非有明确的指示:

```js
const laserSound1 = SoundBoy.playSfx('laser', {
    callback: () => console.log('laser1 callback!');
});

const laserSound2 = SoundBoy.playSfx('laser', {
    callback: ()=> console.log('laser2 callback!')
});
laserSound1.stop(); // callback will not be called
laserSound2.stop(true); // callback will still be called
```

同样,对于播放在 `singleFile` 频道,调用符如果一个声音被中断将不会执行,除非在用于播放该声音的 SoundInstance 选项中明确指示:

```js
// the vo channel only plays one sound at a time...
const vo1 = SoundBoy.playVo('vo1', {
   callback: () => console.log('vo1 callback!')
});

// vo2 will interrupt vo1 as the vo channel is `singleFile`, vo1's callback will not execute as it has not yet completed
const vo2 = SoundBoy.playVo('vo2', {
   callback: () => console.log('vo2 callback'),
   callbackOnInterrupt: true
});

// vo3 will interrupt vo2, vo2's callback _will_ execute because `callbackOnInterrupt` is true in it's SoundInstanceOptions
const vo3 = SoundBoy.playVo('vo3', {
   callback: () => console.log('vo3 callback!')
});
// vo3's callback will execute if and when it completes

const vo4 = SoundBoy.playVo('vo4', {
   wontInterrupt: true; // vo4 won't play because vo3 is already playing
})


```

注意一个回调只会执行一次, 即使声音实例被回调重新启动—— 如果这不是所希望的行为, 请使用声音实例的 complete 信号 :

```js
//contrived example:
const vo = SoundBoy.playVo('vo');
vo.onComplete.add( ( sound ) => sound.restart() ); // sound will loop indefinitely
```

声音实例也有 `onLoop` 信号,它每次发出一个声音到达尾声(也发出之前) `onComplete` 在最后循环的结尾.

## 控制声音实例和频道

在回放时,声音事件可以独立控制,或者作为一个团体通过正在播放的频道进行. 实例和频道状态是独立的,例如一个被暂停的频道上的暂停声音实例在频道恢复时仍将被暂停. SoundBoy本身也有一些全局控制,用于变形、挖掘和恢复一切,以及系统控制,以基于系统级别事件设定暂停和/或变形状态,例如程序或浏览器标签进入背景.

### 共同属性

从系统通过SoundBoy,SoundChannels和SoundInstances,所有层次的Soundboy等级,都具有一些相似的属性. 每个对象存储它自己的状态,同时也将计算到的状态(基于它的状态和它的父母的状态)赋予对象更下层的等级——在这条路径的末尾,SoundInstance会注意确保实际的声音反映这个计算状态.

-   `volume: number` - (范围:0至1)(你也许可以超过1,但准备扭曲),默认为1
-   `muted: boolean` - 默认是虚假的
-   `paused: boolean` - 默认是虚假的

### 通用方法

常见 `paused` 财务报告和审定财务报表 `muted` 属性可以直接设置或通过:

-   `pause(value: boolean = true)`
-   `mute(value: boolean = true)`

### 声音实例控制

#### 属性 :

-   `panning: number` - (范围: -1 至 1) - 从左 (-1) 到右 ( 1) 的立体平板化,默认为 0
-   `rate: number` - (范围:0向上) - 回放速度,默认为 1

#### 方法:

-   `restart()` - 从一开始就重新启动声音
-   `seek(seconds: number)` - 进入指定的位置和游戏
-   `cue(seconds: number)` - 进入指定位置并暂停

### 声道控制

#### 属性 :

-   `singleFile: boolean` - 设定为真实, 只允许在频道上每次发出一个声音
-   `crossFadeDuration: number` - 交叉时间(以秒计)从现有声音到新声音在a上消失 `singleFile` 频道,默认为 0

#### 方法:

-   `restart()` - 重新启动频道上的所有声音
-   `stop()` - 停止频道的所有声音
-   `forEach( callback: (sound: SoundInstance) => void )` - 对频道中的所有声音执行回调

### 声音控件 :

所有共同特性和方法以及:

-   `systemMuted: boolean`
-   `systemMute(value: boolean = true)`

## 常见问题

### @goodboydigital/soundboy 是什么？

管理声音的回放

### 如何安装 @goodboydigital/soundboy？

在项目目录运行 npm install @goodboydigital/soundboy，或使用 pnpm add / yarn add / bun add。

### @goodboydigital/soundboy 支持 TypeScript 吗？

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

### @goodboydigital/soundboy 支持 ESM 还是 CommonJS？

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

### @goodboydigital/soundboy 可以商用吗？

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

### @goodboydigital/soundboy 的下载量有多少？

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

### @goodboydigital/soundboy 还在维护吗？

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

