HumanBreak/docs/api/user-client-modules/AudioSource.md

AudioSource API 文档

本文档由 DeepSeek R1 模型生成并微调。

---

类描述

音频系统的源头抽象类，定义了音频播放的核心控制接口。支持多种音频源类型，包括流媒体、HTML 音频元素和静态音频缓冲。

graph LR
    AudioPlayer --> EventEmitter

    click EventEmitter "https://nodejs.org/api/events.html#class-eventemitter"

---

抽象成员说明

成员	类型	说明
output	AudioNode	音频输出节点（必须实现）
duration	number	音频总时长（秒）
currentTime	number	当前播放时间（秒）
playing	boolean	播放状态标识

---

核心方法说明

abstract play

function play(when?: number): void;

启动音频播放时序

参数	类型	说明
when	number	预定播放时间（基于 AudioContext.currentTime）

---

abstract stop

function stop(): number;

停止播放并返回停止时刻

---

abstract connect

function connect(target: IAudioInput): void;

连接至音频处理管线

参数	类型	说明
target	IAudioInput	下游处理节点/效果器

---

abstract setLoop

function setLoop(loop: boolean): void;

设置循环播放模式

---

事件系统

事件名	参数	触发时机
play	-	开始播放时
end	-	自然播放结束时

---

自定义音频源示例

网络实时通话源

class WebRTCAudioSource extends AudioSource {
    private mediaStream: MediaStreamAudioSourceNode;
    output: AudioNode;

    constructor(ac: AudioContext, stream: MediaStream) {
        super(ac);
        this.mediaStream = ac.createMediaStreamSource(stream);
        this.output = this.mediaStream;
    }

    get duration() {
        return Infinity;
    } // 实时流无固定时长
    get currentTime() {
        return this.ac.currentTime;
    }

    play() {
        this.mediaStream.connect(this.output);
        this.playing = true;
        this.emit('play');
    }

    stop() {
        this.mediaStream.disconnect();
        this.playing = false;
        return this.ac.currentTime;
    }

    connect(target: IAudioInput) {
        this.output.connect(target.input);
    }

    setLoop() {} // 实时流不支持循环
}

// 使用示例
navigator.mediaDevices.getUserMedia({ audio: true }).then(stream => {
    const source = new WebRTCAudioSource(audioContext, stream);
    source.connect(effectsChain);
    source.play();
});

---

内置实现说明

AudioStreamSource（流媒体源）

graph LR
    Network[网络数据流] --> Buffer[缓冲区]
    Buffer --> Decoder[音频解码器]
    Decoder --> Output[实时音频节点]

• 支持渐进式加载
• 动态缓冲管理
• 适用于浏览器自身不支持的音频类型

AudioElementSource（HTML 音频元素源）

graph LR
    AudioTag[audio 元素] -->|音频流| Output[媒体元素源节点]

• 基于 HTML5 Audio 元素
• 支持跨域资源
• 自动处理音频格式兼容

AudioBufferSource（静态音频缓冲源）

graph LR
    File[音频文件] --> Decode[解码为 AudioBuffer]
    Decode --> Output[缓冲源节点]

• 完整音频数据预加载
• 精确播放控制
• 支持内存音频播放

---

注意事项

1. 时间精度
   所有时间参数均以 AudioContext.currentTime 为基准，精度可达 0.01 秒