three.js AudioAnalyser 完全指南:音频频谱分析、FFT 参数原理与可视化实战

原创2026-09-04 19:51:432,513 阅读
文章标签:3D渲染图形学前端VRAR

three.js AudioAnalyser 完全指南:音频频谱分析、FFT 参数原理与可视化实战

本文围绕 three.js 官方 API 文档 AudioAnalyser 展开,讲解 AudioAnalyser 类如何基于 Web Audio API 对场景中的音频做频谱分析:包括 fftSize 参数的作用原理、getFrequencyData() 与 getAverageFrequency() 两个核心方法的源码实现,以及如何把分析数据喂给 DataTexture 驱动着色器、或驱动材质自发光来做音频可视化。读完后你能独立完成从音频加载、信号链路搭建到频谱实时渲染的完整实战方案。

three.js webaudio_visualizer 示例运行截图,音频频谱被渲染为竖向柱状图形

什么是 AudioAnalyser

AudioAnalyser 是 three.js 音频模块中的一个轻量封装类,官方文档给出的定位是:“This class can be used to analyse audio data.”(本类可用于分析音频数据)。它位于 src/audio/AudioAnalyser.js,并通过 src/Three.Core.js 与 AudioListener、Audio、PositionalAudio 等类一起从核心入口统一导出,属于 three 主包的正式 API 而非 addons。

从源码结构看,它做的事情非常聚焦:在 Web Audio 信号链路的“输出增益节点”之后插入一个原生的 AnalyserNode,把频谱数据读入一个可复用的 Uint8Array,并额外提供一个求平均的便捷方法。整个类不到 100 行,全部实现都建立在三件事之上:

  • audio.context.createAnalyser():创建 FFT 分析节点;
  • analyser.getByteFrequencyData(data):读取 0–255 的字节化频域数据;
  • 对数组求算术平均:得到代表“整体响度感”的平均频率值。

快速上手:官方代码示例

下面是官方文档给出的完整示例(与 src/audio/AudioAnalyser.js 头部注释中的示例一致),展示了从创建监听器、加载音频、播放到获取平均频率的全过程:

// 1. 创建 AudioListener 并挂到相机上
const listener = new THREE.AudioListener();
camera.add( listener );

// 2. 创建一个(非空间化的)Audio 音源
const sound = new THREE.Audio( listener );

// 3. 用 AudioLoader 加载音频,设置为 Audio 对象的 buffer
const audioLoader = new THREE.AudioLoader();
audioLoader.load( 'sounds/ambient.ogg', function( buffer ) {
    sound.setBuffer( buffer );
    sound.setLoop( true );
    sound.setVolume( 0.5 );
    sound.play();
} );

// 4. 创建 AudioAnalyser,传入要分析的 sound 与期望的 fftSize
const analyser = new THREE.AudioAnalyser( sound, 32 );

// 5. 获取该声音的平均频率
const data = analyser.getAverageFrequency();

示例中的 sounds/ambient.ogg 是相对路径写法;在当前仓库中,examples/sounds/ 目录下提供了一批可直接用于本地示例的音源文件,例如 Project_Utopia.ogg、376737_Skullbeatz___Bad_Cat_Maste.ogg、button-press.ogg 等,替换成这些真实存在的文件名即可在 examples 环境中直接跑通。

需要说明两个前提:

  • AudioAnalyser 接收的第一个参数必须是 THREE.Audio 实例(或 PositionalAudio,因为它继承自 Audio)。源码中会调用 audio.context 与 audio.getOutput()(见下文),这两个成员只有 Audio 类提供;
  • 由于浏览器自动播放策略,示例仓库中的演示页面(如 examples/webaudio_visualizer.html)都通过“Play”按钮的点击手势触发 init(),即音频初始化放在用户交互之后。这是浏览器自动播放策略下的通用做法。

音频信号链路:AnalyserNode 接在哪一段?

理解 AudioAnalyser 的关键,是弄清它在 Web Audio 图中插入的位置。看构造函数源码(src/audio/AudioAnalyser.js):

constructor( audio, fftSize = 2048 ) {

    this.analyser = audio.context.createAnalyser();   // 创建 AnalyserNode
    this.analyser.fftSize = fftSize;

    this.data = new Uint8Array( this.analyser.frequencyBinCount ); // 预分配数据容器

    audio.getOutput().connect( this.analyser );       // 关键:把 Audio 的输出接到 analyser

}

链路是这样搭起来的:

  1. 全局 AudioContext 单例:src/audio/AudioContext.js 中的 AudioContext.getContext() 用模块级变量 _context 缓存全局原生 AudioContext(自动兼容 window.webkitAudioContext 前缀写法),整个应用共享同一个上下文,也支持外部通过 setContext() 注入。
  2. 监听器:src/audio/AudioListener.js 创建后持有该上下文,并创建一个 GainNode 作为主输入:this.gain.connect( this.context.destination ),即“监听器总增益 → 声卡输出”。AudioListener 通常作为相机的子对象,updateMatrixWorld() 会把相机位姿同步给原生 context.listener 以支持空间音频定位。
  3. 音源:src/audio/Audio.js 构造时执行 this.context = listener.context(复用全局上下文),并创建自己的 GainNode:this.gain.connect( listener.getInput() ),即“音源增益 → 监听器输入”。
  4. 分析节点:AudioAnalyser 构造时通过 audio.getOutput().connect( this.analyser ) 把音源增益节点再分出一路接到 AnalyserNode。getOutput() 的实现就是返回这个 GainNode(src/audio/Audio.js)。

因此完整链路为:BufferSource/MediaElementSource →(filters)→ Audio.gain →(一路)listener.gain → destination,同时 Audio.gain →(另一路)AnalyserNode。分析节点是“旁路”接法,不参与实际出声路径,所以接入 AudioAnalyser 不会改变听感;setFilters() 设置的滤波器位于 source 与 gain 之间,analyser 读到的是过滤后的信号。

构造参数详解:fftSize 与 frequencyBinCount

官方文档对构造函数的签名说明为:

new AudioAnalyser( audio : Audio, fftSize : number )

  • audio:The audio to analyze.(要分析的音频,即 Audio 实例)
  • fftSize:The window size in samples that is used when performing a Fast Fourier Transform (FFT) to get frequency domain data.(执行快速傅里叶变换(FFT)以获取频域数据时所用的窗口大小,单位是采样点)。默认值为 2048,这一点与源码中 constructor( audio, fftSize = 2048 ) 的默认参数一致。

fftSize 决定了两个关键量:

  • 频点数量(frequency bins):AnalyserNode.frequencyBinCount = fftSize / 2。源码中 this.data = new Uint8Array( this.analyser.frequencyBinCount ) 正是在构造时按它预分配数组(src/audio/AudioAnalyser.js)。fftSize = 32 时得到 16 个频点,fftSize = 2048 时得到 1024 个频点。
  • 频率覆盖范围与分辨率:官方文档在 getFrequencyData 一节中明确说明,数组中的每一项代表某一特定频率的分贝值,频率从 0 线性铺开到采样率的一半(奈奎斯特频率)。文档给出的例子是:对 48000 的采样率,数组最后一项代表 24000 Hz 的分贝值。换言之,相邻频点间隔约为 sampleRate / fftSize,fftSize 越大频率分辨率越高、但数组越大,计算与渲染开销也越高。

选择 fftSize 的实践建议(结合仓库内两个示例):

场景 示例 fftSize 说明
频谱可视化(柱状条) examples/webaudio_visualizer.html 128 64 个频点,映射为 64×1 纹理,轻量且视觉上足够平滑
用“平均频率”驱动材质 examples/webaudio_sandbox.html 32 只需一个聚合值,频点越少越省
需要精细频谱(如波形合成、精细音高检测) 默认 2048 1024 个频点,默认值

注意 fftSize 在构造时一次性写入 analyser 节点,AudioAnalyser 类没有提供运行期修改的接口;需要不同分辨率时应创建新的 AudioAnalyser 实例。

属性:.analyser 与 .data

官方文档列出两个属性:

.analyser : AnalyserNode

文档原文描述为“The global audio listener.”(文档沿用了这个措辞),从源码看,实际对象是构造时用 audio.context.createAnalyser() 创建的 AnalyserNode 实例(src/audio/AudioAnalyser.js),类型标注为 AnalyserNode。保留这个公开属性意味着你可以直接访问原生 Web Audio 的全部分析能力,例如 analyser.smoothingTimeConstant 平滑系数,或用 getByteTimeDomainData() 拿时域波形——AudioAnalyser 本身只封装了频域数据。

.data : Uint8Array

文档说明:“Holds the analyzed data.”(保存分析得到的数据)。源码中它在构造时按 frequencyBinCount 预分配:

this.data = new Uint8Array( this.analyser.frequencyBinCount );

这个数组是 getByteFrequencyData() 的复用缓冲区,两个重要含义:

  1. 零拷贝复用:getFrequencyData() 每帧把 FFT 结果写回同一个数组,不会每次新建对象,适合放在渲染循环里高频调用;
  2. 可直接作为纹理数据:正因为 data 本身就是 Uint8Array,它可以原样传给 THREE.DataTexture 的构造器,作为 RedFormat 的红通道上传 GPU——这是官方 visualizer 示例的核心技巧,下节展开。

方法:.getFrequencyData() 与 .getAverageFrequency()

.getFrequencyData() : Uint8Array

官方文档:

Returns an array with frequency data of the audio. Each item in the array represents the decibel value for a specific frequency. The frequencies are spread linearly from 0 to 1/2 of the sample rate. For example, for 48000 sample rate, the last item of the array will represent the decibel value for 24000 Hz.

实现只有两行(src/audio/AudioAnalyser.js):

getFrequencyData() {

    this.analyser.getByteFrequencyData( this.data );

    return this.data;

}

返回值就是上文 .data 属性指向的同一个 Uint8Array,每项为 0–255 的字节值。文档称其为“decibel value”——按 Web Audio getByteFrequencyData 的语义,这是把对数刻度(dB)频谱映射到字节区间后的值,可直接当作“该频段的能量强度”使用,不必再做 0–1 归一化之外的处理(需要归一化时除以 255 即可)。

.getAverageFrequency() : number

官方文档:

Returns the average of the frequencies returned by getFrequencyData(). Returns: The average frequency.

源码实现(src/audio/AudioAnalyser.js)是对整个频点数组求算术平均:

getAverageFrequency() {

    let value = 0;
    const data = this.getFrequencyData();

    for ( let i = 0; i < data.length; i ++ ) {

        value += data[ i ];

    }

    return value / data.length;

}

返回值范围是 0–255(理论闭区间),它不是“主音频率”,而是全部频点能量的平均强度,非常适合作为“声音响度”的单一标量信号。注意它内部会先调用一次 getFrequencyData() 刷新数据,所以每帧调用一次 getAverageFrequency() 就足够,无需再额外调 getFrequencyData()。

实战一:频谱柱状可视化(webaudio_visualizer)

仓库中最典型的 AudioAnalyser 应用是 examples/webaudio_visualizer.html:把频谱数据写进 DataTexture,用一段极短的分片着色器把每个频点的能量渲染成竖条(即上文文章头图的运行效果)。其核心代码:

const fftSize = 128;

const listener = new THREE.AudioListener();
const audio = new THREE.Audio( listener );

// iPad/iPhone/iPod 走 AudioLoader + setBuffer;
// 其他平台走 HTMLMediaElement + setMediaElementSource
// (源码中对 iOS 做了 UA 判断分支)

analyser = new THREE.AudioAnalyser( audio, fftSize );

// 关键:analyser.data 直接作为纹理数据,宽度 = fftSize / 2
uniforms = {
    tAudioData: { value: new THREE.DataTexture( analyser.data, fftSize / 2, 1, THREE.RedFormat ) }
};

// ShaderMaterial + PlaneGeometry(1, 1) 铺满 NDC 全屏

动画循环里只做了两件事:

function animate() {

    analyser.getFrequencyData();              // 刷新 analyser.data

    uniforms.tAudioData.value.needsUpdate = true; // 重新上传纹理

    renderer.render( scene, camera );

}

分片着色器逻辑(同一文件内联定义)是:采样纹理得到该列的频率能量 f,用两次 step 构造出“从底部 0 高度到 f 高度”的矩形条:

float f = texture2D( tAudioData, vec2( vUv.x, 0.0 ) ).r;
float i = step( vUv.y, f ) * step( f - 0.0125, vUv.y );
gl_FragColor = vec4( mix( backgroundColor, color, i ), 1.0 );

这个示例印证了前面两个要点:fftSize / 2 与纹理宽度必须一致(128 → 64 像素宽);analyser.data 因为与纹理共享同一块 Uint8Array,getFrequencyData() 写入后只要置 needsUpdate = true 即可,CPU 到 GPU 只有一次纹理上传。

three.js webaudio_sandbox 示例运行截图,多个立方体随空间音频的强度改变自发光

实战二:用平均频率驱动材质(webaudio_sandbox)

第二个示例 examples/webaudio_sandbox.html 展示了 getAverageFrequency() 的用法:场景中有多个随 PositionalAudio 发声的立方体,每个音源各挂一个 AudioAnalyser,每帧把平均频率映射到材质自发光强度:

// 每个音源一个分析器,fftSize = 32
analyser1 = new THREE.AudioAnalyser( sound1, 32 );
analyser2 = new THREE.AudioAnalyser( sound2, 32 );
analyser3 = new THREE.AudioAnalyser( sound3, 32 );

// 渲染循环内:
material1.emissive.b = analyser1.getAverageFrequency() / 256;
material2.emissive.b = analyser2.getAverageFrequency() / 256;
material3.emissive.b = analyser3.getAverageFrequency() / 256;

这里 / 256 是把 0–255 的字节均值归一到约 0–1 的浮点值,直接乘到 emissive.b(蓝色通道)上,形成“声音越大、方块越亮”的联动效果。同一个页面还演示了 AudioAnalyser 与 setNodeSource(OscillatorNode 音源)、setMediaElementSource(<audio> 元素音源)等不同 sourceType 的兼容:只要走的是 Audio 类的 gain 输出,任何来源的音频都能被分析。

使用注意事项与适用限制

结合源码与示例,使用 AudioAnalyser 时有几个值得留意的点:

  1. 数据是“拉”模式:AnalyserNode 不会主动推送数据,getFrequencyData() 读到的总是“当前时刻”的快照。把调用放在 setAnimationLoop 渲染回调里,才能保证可视化与画面同帧刷新(两个官方示例均如此)。
  2. 数组是共享复用的:analyser.data 是构造时按 frequencyBinCount 预分配的 Uint8Array,每帧被覆写。如果需要保存历史帧(例如做频谱瀑布图),要自行 slice() 或拷贝,不能直接持有旧引用期待它不变。
  3. fftSize 不可运行期更改:AudioAnalyser 未暴露修改 fftSize 的接口,构造参数即终值;需要多分辨率时请创建多个实例(webaudio_sandbox 中一个页面就同时创建了 3 个 AudioAnalyser,互不干扰)。
  4. 多音源要各接各的:每个 AudioAnalyser 只分析传入的那一个 Audio 的 gain 输出。想分析多个音源就为每个音源各建一个分析器;若需要“总线分析”(分析全部声音的混合结果),由于 AudioAnalyser 的构造只接受单个 Audio 对象,从源码结构看需要自行把相关 getOutput() 连接到自建的 AnalyserNode。
  5. 频率分辨率由采样率共同决定:频点间隔约 sampleRate / fftSize。文档以 48000 Hz 为例说明末项对应 24000 Hz;如果你的 AudioContext 实际采样率是 44100 Hz,末项则对应 22050 Hz——按文档描述的“线性铺开到采样率一半”规律换算即可。
  6. 浏览器自动播放策略:音频上下文需要用户手势才能启动,仓库示例统一把 init()(含 AudioListener、Audio、AudioAnalyser 的创建)放在“Play”按钮点击之后,生产环境建议沿用此模式。

小结

AudioAnalyser 是 three.js 音频模块中负责“把声音变成数据”的一环:构造时通过 audio.getOutput().connect( this.analyser ) 在音源增益之后挂一个 AnalyserNode,fftSize(默认 2048)决定频点数量与分辨率,.data 预分配的 Uint8Array 承载 getByteFrequencyData() 的结果,getFrequencyData() 供逐频点使用、getAverageFrequency() 供整体强度使用。配合 examples/webaudio_visualizer.html 的 DataTexture 方案与 examples/webaudio_sandbox.html 的材质驱动方案,它可以支撑从频谱柱状图到音频联动特效的常见需求。更完整的音频能力(AudioListener、PositionalAudio、AudioLoader 等)可继续参考同目录下的官方文档页面(docs/pages/)与 src/audio/ 源码。

登录后查看全文
three.js