BeShell 文档

简体中文

English

简体中文

English

外观

模块: AudioPlayer

约 592 字大约 2 分钟

2026-08-26

构建固件和导入到JS

额外组件

该功能需要安装 beshell-AudioPlayer 组件才能使用。

安装方法：

  1. 编辑项目根目录下的 idf_component.yml 文件，添加依赖：
dependencies:
  become-cool/beshell-AudioPlayer: '>=1.0.1'
  1. 或在 ESP-IDF 环境的命令行中执行：
idf.py add-dependency "become-cool/beshell-AudioPlayer>=1.0.1"

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

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

在JS中导入 audio-player module：

在.js文件中
import * as audioPlayer from 'audio-player'

简介

音频播放器模块

通过 I2S 输出音频，支持 MP3 播放（内置 Helix MP3 定点解码器）、WAV/PCM 播放、 暂停/恢复/停止、音量调节和播放事件通知。

模块导出 AudioPlayer 类。

示例：

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")

播放内存中的音频数据（ArrayBuffer）：

import * as fs from "fs"

// readFileSync 返回 ArrayBuffer，播放期间播放器会持有引用防止被 GC 回收
const mp3 = fs.readFileSync("/mp3/music.mp3")
player.playMP3(mp3)

const wav = fs.readFileSync("/test.wav")
player.playWAV(wav)

播放 WAV / 裸 PCM 数据：

// WAV 采样格式自动从文件头解析
player.playWAV("/test.wav")

// 裸 PCM 需要指定采样率、位宽、声道数
const pcm = fs.readFileSync("/test.pcm")
player.playPCM(pcm, 16000, 16, 1)

// 在内存中生成 PCM 播放，例如 1 秒 440Hz 正弦波：
const rate = 16000
const buf = new ArrayBuffer(rate * 2)  // 16bit = 每采样 2 字节
const view = new DataView(buf)
for (let i = 0; i < rate; 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)

播放控制：

player.pause()        // 暂停
player.resume()       // 恢复
player.stop()         // 停止（异步）
player.stop(true)     // 停止（阻塞直到停止完成）

console.log(player.isPlaying())  // 是否正在播放
console.log(player.isPaused())   // 是否处于暂停状态
player.setVolume(50)             // 音量 0-100

同步播放（阻塞直到播放结束）：

player.playMP3("/mp3/music.mp3", true)
console.log("播放完成")