从播放器到编辑器：wavesurfer.js 打造高颜值音频可视化与交互

wavesurfer.js 带你用最少的代价搞定网页音频可视化与播放控制。

为什么选择 wavesurfer.js？

• 可视化波形：开箱即用的波形渲染与交互，省去自己绘图的复杂度。
• 插件生态：时间轴、标记、区域、缩略图、频谱等常见能力，一个库就能搞定。
• 轻量灵活：核心小而精，按需加载插件；移动端事件也支持得不错。
• 易集成：原生 JS、不绑框架；在 Vue/React 中照样顺滑使用。
• 适合场景： – 音频可视化 – 音频播放器 – 音频编辑器

快速开始

安装

npm add wavesurfer.js

基础使用

下面是最小可用的播放与波形渲染示例。它支持本地文件或在线音频地址，加载后自动渲染波形，并能响应点击播放。

<template>
  <div class="wavesurfer-demo">
    <div ref="waveform"></div>
  </div>
</template>

<script setup>
  import { ref, onMounted, onBeforeUnmount } from "vue";
  import WaveSurfer from "wavesurfer.js";

  const waveform = ref(null);
  let wavesurfer = null;

  onMounted(() => {
    if (!waveform.value) return;

    wavesurfer = WaveSurfer.create({
      container: waveform.value, // 容器
      waveColor: "gray", // 波形颜色
      progressColor: "rgb(100, 0, 100)", // 进度条颜色
      url: "/test.mp3", // 音频地址
    });

    wavesurfer.on("click", () => {
      wavesurfer && wavesurfer.play();
    });
  });

  onBeforeUnmount(() => {
    if (wavesurfer) {
      wavesurfer.destroy();
      wavesurfer = null;
    }
  });
</script>

常用配置 options

参数名	说明
container	渲染波形的 DOM 容器或选择器
waveColor	波形未播放部分的颜色
progressColor	已播放进度的颜色
url	要播放的音频地址
height	波形高度；越高越清晰
width	画布宽度；通常随容器自适应
cursorColor	播放指针（光标）颜色
cursorWidth	播放指针宽度
barWidth	条形模式下的单条宽度
barHeight	条形模式的高度比例
barGap	条形之间的间距
barRadius	条形圆角大小

常用事件 events

事件名	说明
audioprocess	解码/播放过程中持续回调
click	点击波形区域
dblclick	双击波形区域
load	开始加载音频
loading	加载进度变化
play	调用播放后、开始播放
pause	调用暂停后、暂停播放
finish	播放自然结束
drag	在波形上拖拽中
dragstart	开始拖拽
dragend	结束拖拽

常用插件

时间轴 Timeline

在波形下方显示时间刻度与标签，便于对齐定位与时间参考。

import Timeline from "wavesurfer.js/dist/plugins/timeline.esm.js";

const timeline = Timeline.create({
  container: "#timeline",
  primaryLabelInterval: 1,
  style: { fontSize: "12px", color: "#6b7280" },
});
wavesurfer.registerPlugin(timeline);

<div id="timeline"></div>;

区域标记 Regions

支持拖拽选择/编辑区间，可用于标注片段、循环播放、剪辑定位。

import Regions from "wavesurfer.js/dist/plugins/regions.esm.js";

const regions = Regions.create({
  dragSelection: true,
});
wavesurfer.registerPlugin(regions);

// 音频解码完成后再添加区域
wavesurfer.on("ready", () => {
  regions.addRegion({
    start: 2,
    end: 5,
    color: "rgba(99,102,241,0.2)",
    drag: true,
    resize: true,
  });
});

缩略图 Minimap

提供全局小地图视图，快速导航长音频并查看整体进度。

import Minimap from "wavesurfer.js/dist/plugins/minimap.esm.js";

const minimap = Minimap.create({
  height: 36,
  waveColor: "#c7d2fe",
  progressColor: "#818cf8",
});

wavesurfer.registerPlugin(minimap);

频谱图 Spectrogram

展示频率随时间的能量分布，用于噪声分析、音色观察与特征定位。

import Spectrogram from "wavesurfer.js/dist/plugins/spectrogram.esm.js";

const spectrogram = Spectrogram.create({
  labels: true,
});

wavesurfer.registerPlugin(spectrogram);

常见问题

• 移动端不能自动播放：受浏览器策略限制，必须先有用户手势（点击、触摸）才能 play()；或尝试将音量设为 0，并结合 muted autoplay 的 <audio> 方案。
• 跨域/206 分片失败：确保音频资源服务器返回正确的 CORS 响应头，同时开启 Accept-Ranges: bytes 以支持分片请求。
• 波形不显示或全 0：检查音频是否可解码、是否同源、是否正确传入 peaks 与采样率是否匹配。
• 内存/CPU 较高：尝试启用 barWidth（条形波形）、partialRender，或预计算 peaks；降低 height；去掉不必要的阴影/渐变。
• 事件不触发：确认所用版本的 API 名称是否匹配；建议先绑定 on 再进行 load；必要时打印 wavesurfer 实例核对可用事件。
• 销毁不彻底导致重复波形：组件卸载时务必 destroy() 并清空引用，避免重复创建实例。

总结

Wavesurfer.js 是一个既强大又上手快的音频可视化库。通过核心能力 + 插件扩展，你可以用很少的代码完成从“能播能看”到“可标注、可导航、可分析”的全链路体验。保留灵活性的同时，把复杂度交给库来承担。