HTML5 API：Web Audio API - 完整教程与代码示例

// 创建 AudioContext
const audioCtx = new (window.AudioContext || window.webkitAudioContext)();

// AudioContext 的关键属性
console.log(audioCtx.sampleRate);    // 采样率，通常为 44100Hz 或 48000Hz
console.log(audioCtx.currentTime);   // 当前时间（秒）
console.log(audioCtx.destination);   // 音频输出目标
console.log(audioCtx.state);         // 状态：suspended / running / closed

// 基本音频路由：源 -> 增益 -> 输出
source.connect(gainNode);
gainNode.connect(audioCtx.destination);

// 标准创建方式
const audioCtx = new AudioContext();

// 兼容性创建方式
const audioCtx = new (window.AudioContext || window.webkitAudioContext)();

// 恢复被挂起的 AudioContext（浏览器自动策略）
async function resumeAudioContext() {
    if (audioCtx.state === 'suspended') {
        await audioCtx.resume();
    }
}

// 使用 AudioBuffer 播放音频
async function playAudio(url) {
    const response = await fetch(url);
    const arrayBuffer = await response.arrayBuffer();
    const audioBuffer = await audioCtx.decodeAudioData(arrayBuffer);

    const source = audioCtx.createBufferSource();
    source.buffer = audioBuffer;
    source.connect(audioCtx.destination);
    source.start();
}

// connect() 方法连接节点
sourceNode.connect(nextNode);

// 断开连接
sourceNode.disconnect();

// 一个节点可以连接到多个目标（分路）
sourceNode.connect(gainNode1);
sourceNode.connect(gainNode2);

// 多个节点可以连接到同一个目标（混音）
source1.connect(gainNode);
source2.connect(gainNode);

// 最佳实践：全局共享一个 AudioContext
class AudioManager {
    constructor() {
        this.ctx = null;
    }

    getContext() {
        if (!this.ctx) {
            this.ctx = new (window.AudioContext || window.webkitAudioContext)();
        }
        return this.ctx;
    }

    async resume() {
        const ctx = this.getContext();
        if (ctx.state === 'suspended') {
            await ctx.resume();
        }
        return ctx;
    }

    async close() {
        if (this.ctx) {
            await this.ctx.close();
            this.ctx = null;
        }
    }
}

// 及时断开和清理不再使用的节点
function cleanupAudioNodes(sourceNode, ...connectedNodes) {
    sourceNode.disconnect();
    connectedNodes.forEach(node => {
        if (node.disconnect) {
            node.disconnect();
        }
    });
}

// 使用 AudioBuffer 时注意内存占用
// 一个 5 分钟的立体声音频（44100Hz）约占用 ~21MB
// 长时间播放的音频考虑使用 MediaElementAudioSourceNode

// 1. 使用 AudioWorklet 代替 ScriptProcessorNode
await audioCtx.audioWorklet.addModule('processor.js');
const workletNode = new AudioWorkletNode(audioCtx, 'my-processor');

// 2. 合理设置 FFT 大小
analyser.fftSize = 2048;  // 适合大多数可视化场景

// 3. 减少不必要的节点连接
// 好的做法：source -> filter -> gain -> destination

// 4. 使用 smoothingTimeConstant 平滑分析数据
analyser.smoothingTimeConstant = 0.8;

// 现代浏览器要求用户交互后才能播放音频
// 正确处理方式：在用户点击事件中初始化并恢复 AudioContext
document.getElementById('playBtn').addEventListener('click', async () => {
    if (audioCtx.state === 'suspended') {
        await audioCtx.resume();
    }
    // 播放逻辑...
});

/**
 * Web Audio 引擎封装
 * 提供统一的音频管理、播放、效果处理接口
 */
class WebAudioEngine {
    constructor() {
        this.ctx = null;
        this.masterGain = null;
        this.analyser = null;
        this.sounds = new Map();
        this.activeSources = new Set();
    }

    async init() {
        if (this.ctx) return;
        this.ctx = new (window.AudioContext || window.webkitAudioContext)();
        this.masterGain = this.ctx.createGain();
        this.masterGain.gain.value = 0.8;
        this.analyser = this.ctx.createAnalyser();
        this.analyser.fftSize = 2048;
        this.masterGain.connect(this.analyser);
        this.analyser.connect(this.ctx.destination);
        if (this.ctx.state === 'suspended') {
            await this.ctx.resume();
        }
    }

    async loadSound(name, url) {
        const response = await fetch(url);
        const arrayBuffer = await response.arrayBuffer();
        const audioBuffer = await this.ctx.decodeAudioData(arrayBuffer);
        this.sounds.set(name, audioBuffer);
        return audioBuffer;
    }

    play(name, options = {}) {
        const buffer = this.sounds.get(name);
        if (!buffer) return null;
        const source = this.ctx.createBufferSource();
        source.buffer = buffer;
        const gainNode = this.ctx.createGain();
        gainNode.gain.value = options.volume ?? 1;
        source.connect(gainNode);
        gainNode.connect(this.masterGain);
        if (options.loop) {
            source.loop = true;
        }
        source.start(options.when ?? 0, options.offset ?? 0);
        this.activeSources.add({ source, gainNode });
        source.onended = () => {
            this.activeSources.delete({ source, gainNode });
        };
        return { source, gainNode };
    }

    stopAll(fadeOut = 0) {
        this.activeSources.forEach(({ source, gainNode }) => {
            if (fadeOut > 0) {
                gainNode.gain.linearRampToValueAtTime(0, this.ctx.currentTime + fadeOut);
                source.stop(this.ctx.currentTime + fadeOut);
            } else {
                source.stop();
            }
        });
        this.activeSources.clear();
    }

    async destroy() {
        this.stopAll();
        this.sounds.clear();
        if (this.ctx) {
            await this.ctx.close();
            this.ctx = null;
        }
    }
}