类: AudioPlayer

约 2183 字大约 7 分钟

2026-08-26

构建固件和导入到JS

在 C++ 里加入以下代码, 然后重新编译构建固件：

// 为了控制固件的尺寸，BeShell 的 module 是按需引入的。
beshell.use<be::media::Audio>() ;

AudioPlayer 类由 audio-player 模块提供：

import { AudioPlayer } from 'audio-player'

简介

音频播放器类，通过 I2S 输出音频。

支持的功能：

MP3 播放（内置 Helix MP3 定点解码器）
WAV 播放（采样率/位宽/声道自动从文件头解析）
裸 PCM 数据播放
暂停 / 恢复 / 停止
音量调节
播放事件通知

播放方法的 source 参数支持两种类型：

文件路径（string）：VFS 路径，如 "/music.mp3"
ArrayBuffer：内存中的完整音频数据，如 fs.readFileSync() 的返回值。播放期间播放器内部会持有该 ArrayBuffer 的引用以防止被 GC 回收，播放结束后自动释放。

播放前需要先通过 serial 模块创建并配置 I2S 通道，例如 serial.i2s0.setup({...})。

事件：

stop: 播放停止时触发，回调参数 finished（number）为非 0 表示文件完整播放结束，0 表示被中途停止

示例：

import * as serial from "serial"
import { AudioPlayer } from "audio-player"

// 初始化 I2S（引脚请按实际接线修改）
serial.i2s0.setup({
    bck: 4,    // BCK 位时钟引脚
    ws: 5,     // WS(LRCK) 字时钟引脚
    dout: 6,   // 数据输出引脚（接功放/解码芯片 DIN）
    rate: 44100,
    bits: 16,
    channels: 2
})

const player = new AudioPlayer()
player.setVolume(80)

// 播放结束（或被停止）时触发
player.on("stop", (finished) => {
    console.log("播放结束, 是否完整播放:", !!finished)
})

player.playMP3("/mp3/music.mp3")

类方法

方法 constructor

原型: constructor (i2sNum:number=0)

构造函数

创建一个新的 AudioPlayer 实例。

示例：

// 使用 I2S 端口 0（默认）
const player = new AudioPlayer()

// 使用 I2S 端口 1
const player1 = new AudioPlayer(1)

参数:

i2sNum
类型number
默认值0
参数说明I2S 端口号。ESP32/S3/P4 可选 0/1，S2/C3/C6/H2 只有 0

异常:

i2s number 必须是 uint32
无效的 i2s 端口号（超出芯片实际 I2S 数量）

返回值:

类型AudioPlayer

说明返回 AudioPlayer 实例

方法 playMP3

原型: playMP3 (source:string|ArrayBuffer, sync:boolean=false)

播放 MP3

播放指定的 MP3 文件或内存中的 MP3 数据。播放为异步进行，可通过 stop 事件获知播放结束。传入 ArrayBuffer 时会自动跳过 MP3 开头的 ID3v2 标签。

建议使用 ffmpeg 转码 MP3 文件，-q:a 选项的值应 >= 7 以降低码率： ffmpeg -i input.mp4 -ac 2 -q:a 7 -map a output.mp3

示例：

// 播放文件
player.playMP3("/mp3/music.mp3")

// 播放内存中的数据（ArrayBuffer）
import * as fs from "fs"
const data = fs.readFileSync("/mp3/music.mp3")  // readFileSync 返回 ArrayBuffer
player.playMP3(data)

// ArrayBuffer 也可以来自其他任何途径，例如网络下载：
// const resp = await fetch("http://example.com/music.mp3")
// player.playMP3(await resp.arrayBuffer())

// 同步播放（阻塞直到播放结束）
player.playMP3("/mp3/music.mp3", true)

参数:

source
类型string, ArrayBuffer
参数说明MP3 文件路径，或内存中的 MP3 数据
sync
类型boolean
默认值false
参数说明是否同步播放，为 true 时阻塞直到播放结束

异常:

播放器正在播放中
路径过长
文件不存在
解码器尚未关闭

返回值:

类型undefined

方法 playWAV

原型: playWAV (source:string|ArrayBuffer)

播放 WAV

播放指定的 WAV 文件或内存中的 WAV 数据。采样率、位宽、声道数自动从 WAV 文件头解析。播放为异步进行，可通过 stop 事件获知播放结束。

示例：

// 播放文件
player.playWAV("/test.wav")

// 播放内存中的数据（ArrayBuffer）
import * as fs from "fs"
const data = fs.readFileSync("/test.wav")  // readFileSync 返回 ArrayBuffer
player.playWAV(data)

// ArrayBuffer 也可以来自其他任何途径，例如网络下载：
// const resp = await fetch("http://example.com/test.wav")
// player.playWAV(await resp.arrayBuffer())

参数:

source
类型string, ArrayBuffer
参数说明WAV 文件路径，或内存中的 WAV 数据

异常:

播放器正在播放中
路径过长
文件不存在

返回值:

类型undefined

方法 playPCM

原型: playPCM (source:string|ArrayBuffer, sampleRate:number=16000, bits:number=16, channels:number=1)

播放裸 PCM 数据

播放无文件头的裸 PCM 音频数据，采样格式由参数指定。播放为异步进行，可通过 stop 事件获知播放结束。

示例：

import * as fs from "fs"

// 播放 16bit 单声道 16kHz 的 PCM 数据（readFileSync 返回 ArrayBuffer）
const pcm = fs.readFileSync("/test.pcm")
player.playPCM(pcm, 16000, 16, 1)

// 也可以在内存中生成 PCM 数据播放，例如生成 1 秒 440Hz 正弦波：
const rate = 16000, seconds = 1
const buf = new ArrayBuffer(rate * seconds * 2)  // 16bit = 每采样 2 字节
const view = new DataView(buf)
for (let i = 0; i < rate * seconds; i++) {
    const sample = Math.round(Math.sin(2 * Math.PI * 440 * i / rate) * 32767)
    view.setInt16(i * 2, sample, true)  // little-endian
}
player.playPCM(buf, rate, 16, 1)

参数:

source
类型string, ArrayBuffer
参数说明PCM 文件路径，或内存中的 PCM 数据
sampleRate
类型number
默认值16000
参数说明采样率（Hz）
bits
类型number
默认值16
参数说明采样位宽
channels
类型number
默认值1
参数说明声道数

异常:

播放器正在播放中
路径过长
文件不存在

返回值:

类型undefined

方法 pause

原型: pause ()

暂停播放

暂停当前播放，可通过 resume() 恢复。

示例：

player.pause()

返回值:

类型undefined

方法 resume

原型: resume ()

恢复播放

从暂停状态恢复播放。如果当前未处于暂停状态，则不执行任何操作。

示例：

player.resume()

返回值:

类型undefined

方法 stop

原型: stop (sync:boolean=false)

停止播放

停止当前播放。停止后会触发 stop 事件，回调参数 finished 为 0（中途停止）。如果当前未在播放，则不执行任何操作。

示例：

player.stop()

// 同步停止（阻塞直到停止完成）
player.stop(true)

参数:

sync
类型boolean
默认值false
参数说明是否同步停止，为 true 时阻塞直到停止完成

返回值:

类型undefined

方法 isPlaying

原型: isPlaying ()

是否正在播放

示例：

if (player.isPlaying()) {
    console.log("正在播放")
}

返回值:

类型bool

说明是否正在播放

方法 isPaused

原型: isPaused ()

是否处于暂停状态

示例：

if (player.isPaused()) {
    player.resume()
}

返回值:

类型bool

说明是否处于暂停状态

方法 setVolume

原型: setVolume (volume:number)

设置音量

示例：

player.setVolume(80)

参数:

volume
类型number
参数说明音量，取值 0-100

返回值:

类型undefined

方法 printStats

原型: printStats ()

打印音频管道运行状态

向控制台打印音频管道中各节点的运行状态，用于调试。

示例：

player.printStats()

返回值:

类型undefined

控件

类: AudioPlayer