wavesurfer.js快速上手指南：5个步骤在网页中渲染可交互的音频波形-平芜编程栈

wavesurfer.js快速上手指南：5个步骤在网页中渲染可交互的音频波形

【免费下载链接】wavesurfer.jsAudio waveform player项目地址: https://gitcode.com/gh_mirrors/wa/wavesurfer.js

wavesurfer.js 是一个轻量级的音频波形播放库，能让你在网页中快速渲染可交互的音频波形：加载音频、显示波形、点击跳转、拖拽播放，几行代码即可搞定。本文面向新手，用 5 个步骤带你完成第一个网页音频波形项目，无需深厚的前端经验也能跟着做。

1. 安装 wavesurfer.js 音频波形库

如果本地开发，先克隆仓库（仓库为只读，建议本地拷贝后再运行）：

git clone https://gitcode.com/gh_mirrors/wa/wavesurfer.js

在项目中安装：

npm install --save wavesurfer.js

然后在代码中导入：

import WaveSurfer from 'wavesurfer.js'

💡 不喜欢构建工具？也可以在 HTML 中直接引入 UMD 脚本，它会暴露全局变量WaveSurfer。

2. 创建波形实例并加载音频

核心就一行WaveSurfer.create()，传入容器和音频地址：

const wavesurfer = WaveSurfer.create({ container: '#waveform', // 波形渲染到的 HTML 元素 waveColor: '#4F4A85', // 未播放部分的颜色 progressColor: '#383351', // 已播放部分的颜色 url: '/audio.mp3', // 音频文件地址 })

HTML 中只需要一个空容器：

<div id="waveform"></div>

加载完成后，浏览器会自动解码音频并画出波形。完整最小示例可参考 basic.js，核心配置项说明见 src/wavesurfer.ts。

3. 美化波形：颜色、柱状与高度

wavesurfer.js 内置多种视觉风格，不需要写任何 CSS：

配置项	效果
`barWidth: 2`	把波形渲染成 SoundCloud 风格的柱状条 ▁▂▇▃▅
`barGap`/`barRadius`	控制柱间距与圆角
`height: 128`	波形高度（像素）
`normalize: true`	拉伸波形填满整个高度
`splitChannels`	立体声双通道分别渲染

WaveSurfer.create({ container: '#waveform', url: '/audio.mp3', barWidth: 2, barGap: 1, barRadius: 2, height: 128, })

柱状效果的完整写法见 bars.js。

4. 添加交互：点击播放与跳转

波形天生就是"可点"的——点击任意位置即可跳到对应时间。只需监听interaction事件：

wavesurfer.on('interaction', () => { wavesurfer.play() })

常用 API 速查：

play()/pause()：播放与暂停
setTime(seconds)：跳转到指定秒数
setVolume(0~1)：调节音量
zoom(pxPerSec)：缩放波形，查看细节

事件系统（decode、audioprocess、finish等）在 src/event-emitter.ts 中实现，播放逻辑见 src/player.ts。

5. 启用官方插件：区域标注与频谱图

wavesurfer.js 提供 8 个官方插件，位于 src/plugins/ 目录，可显著增强表现力：

Regions：在波形上叠加可拖拽、可缩放的区域标注，支持循环播放片段
Spectrogram：在波形下方渲染频率频谱图，语言学、音效分析利器
Timeline / Minimap / Envelope / Record / Zoom / Hover：时间刻度、小地图滚动、淡入淡出包络、麦克风录制等

以 Regions 为例，几行代码就能给波形"打标签"：

import RegionsPlugin from 'wavesurfer.js/dist/plugins/regions.esm.js' const regions = RegionsPlugin.create() const ws = WaveSurfer.create({ container: '#waveform', url: '/audio.mp3', plugins: [regions], }) ws.on('decode', () => { regions.addRegion({ start: 0, end: 8, content: 'Intro', color: 'rgba(200,0,200,0.5)' }) })

完整示例见 regions.js 与插件源码 regions.ts。

再来看 Spectrogram 插件渲染出的"波形 + 频谱"效果（配置示例见 spectrogram.js，源码 spectrogram.ts）：