最全音频处理WaveSurfer.js配置文档

一、基础使用示例

// 基础用法
const wavesurfer = WaveSurfer.create({
  container: '#waveform',
  waveColor: 'violet',
  progressColor: 'purple'
});

// 加载音频
wavesurfer.load('audio.mp3');

// 事件监听
wavesurfer.on('ready', function() {
  wavesurfer.play();
});

// 控制方法
wavesurfer.play();
wavesurfer.pause();
wavesurfer.stop();
wavesurfer.setVolume(0.5);
wavesurfer.setPlaybackRate(1.5);

二、完整配置参数表格

基础配置参数

参数名	类型	默认值	说明
container	String/HTMLElement	必填	波形图容器（CSS选择器或DOM元素）
height	Number	128	波形图高度（像素）
width	Number	0	波形图宽度，0表示自动填充
responsive	Boolean	true	是否响应式布局
pixelRatio	Number	window.devicePixelRatio	像素比，用于高清屏
fillParent	Boolean	true	是否填充父容器
scrollParent	Boolean	false	是否启用横向滚动
minPxPerSec	Number	0	最小每秒像素数
hideScrollbar	Boolean	false	是否隐藏滚动条

波形样式参数

参数名	类型	默认值	说明
waveColor	String	'#999'	波形颜色
progressColor	String	'#555'	播放进度颜色
cursorColor	String	'#333'	光标颜色
cursorWidth	Number	1	光标宽度（像素）
barWidth	Number	0	条形宽度，0表示自动计算
barHeight	Number	1	条形高度比例（0-1）
barRadius	Number	0	条形圆角半径
barGap	Number	1	条形间距
backgroundColor	String	null	背景颜色
backgroundImage	String	null	背景图片URL
waveBackgroundColor	String	null	波形背景颜色
normalize	Boolean	false	是否归一化波形
splitChannels	Boolean	false	是否分离声道显示
waveShadowColor	String	null	波形阴影颜色
waveShadowBlur	Number	0	阴影模糊度
waveShadowOffsetX	Number	0	阴影X偏移
waveShadowOffsetY	Number	0	阴影Y偏移

交互配置参数

参数名	类型	默认值	说明
interact	Boolean	true	是否启用交互
dragToSeek	Boolean	true	是否允许拖动跳转
autoScroll	Boolean	true	播放时是否自动滚动
autoCenter	Boolean	true	是否自动居中播放位置
hideCursor	Boolean	false	是否隐藏光标
skipLength	Number	2	跳过秒数（键盘快捷键）
showTimePosition	Boolean	true	是否显示时间位置
regionsMinLength	Number	0.01	最小区域长度（秒）
regionsSnapToGrid	Boolean	false	是否对齐网格
removeMediaElementOnDestroy	Boolean	true	销毁时是否移除媒体元素
partialRender	Boolean	false	是否部分渲染
rtl	Boolean	false	是否从右到左布局

音频处理参数

参数名	类型	默认值	说明
backend	String	'WebAudio'	音频后端：'WebAudio' 或 'MediaElement'
mediaType	String	'audio'	媒体类型：'audio' 或 'video'
audioRate	Number	1	播放速度（0.5-4）
volume	Number	1	音量（0-1）
loopSelection	Boolean	true	是否循环选区
sampleRate	Number	0	采样率，0表示自动
audioContext	AudioContext	null	自定义AudioContext
fftSmoothingTimeConstant	Number	0.8	FFT平滑常数
filter	String	'none'	滤波器类型：'lowpass'、'highpass'、'bandpass'
filterFrequency	Number	null	滤波频率
filterQ	Number	null	滤波器Q值

音频加载参数

参数名	类型	默认值	说明
url	String	null	音频URL（可直接在此指定）
xhr	Object	{}	XMLHttpRequest配置
mediaControls	Boolean	false	是否显示浏览器原生控制条
audioBuffer	AudioBuffer	null	预加载的AudioBuffer
peaks	Array	null	预计算的峰值数据
duration	Number	null	音频时长（秒）
forceDecode	Boolean	false	是否强制解码

性能优化参数

参数名	类型	默认值	说明
renderFunction	Function	null	自定义渲染函数
drawingContextAttributes	Object	{alpha: true}	Canvas上下文属性
splitChannels	Boolean	false	是否分离声道处理
mediaContainer	HTMLElement	null	自定义媒体容器
mediaElement	HTMLMediaElement	null	自定义媒体元素
closeAudioContext	Boolean	false	销毁时是否关闭AudioContext

XHR配置参数

参数名	类型	默认值	说明
xhr.cache	String	'default'	缓存策略
xhr.mode	String	'cors'	跨域模式
xhr.credentials	String	'same-origin'	凭证设置
xhr.referrer	String	'client'	引用来源
xhr.timeout	Number	0	超时时间（毫秒）
xhr.headers	Object	{}	请求头

分离声道配置参数

参数名	类型	默认值	说明
splitChannelsOptions.overlay	Boolean	false	是否叠加显示
splitChannelsOptions.channelColors	Object	{}	各声道颜色配置
splitChannelsOptions.filterChannels	Array	[]	过滤显示的声道
splitChannelsOptions.relativeNormalization	Boolean	false	相对归一化

三、分离声道颜色配置示例

splitChannelsOptions: {
  overlay: false,
  channelColors: {
    0: { // 左声道
      waveColor: 'rgba(255, 0, 0, 0.5)',
      progressColor: 'rgba(255, 100, 100, 0.8)'
    },
    1: { // 右声道
      waveColor: 'rgba(0, 0, 255, 0.5)',
      progressColor: 'rgba(100, 100, 255, 0.8)'
    }
  },
  filterChannels: [0, 1],
  relativeNormalization: true
}

四、XHR配置示例

xhr: {
  cache: 'default',
  mode: 'cors',
  credentials: 'same-origin',
  referrer: 'client',
  timeout: 30000,
  headers: {
    'Authorization': 'Bearer token',
    'Content-Type': 'audio/mpeg'
  }
}

五、分析器配置参数

参数名	类型	默认值	说明
analyserOptions.fftSize	Number	2048	FFT大小
analyserOptions.smoothingTimeConstant	Number	0.8	平滑时间常数
analyserOptions.minDecibels	Number	-100	最小分贝值
analyserOptions.maxDecibels	Number	-30	最大分贝值

六、Canvas上下文属性

参数名	类型	默认值	说明
drawingContextAttributes.alpha	Boolean	true	是否启用透明度
drawingContextAttributes.desynchronized	Boolean	false	是否启用异步渲染

七、完整配置示例

// 完整的WaveSurfer配置示例
const wavesurfer = WaveSurfer.create({
  // 基础配置
  container: '#waveform',
  height: 200,
  width: 0,
  responsive: true,
  pixelRatio: window.devicePixelRatio,
  fillParent: true,
  scrollParent: false,
  
  // 波形样式
  waveColor: '#4A90E2',
  progressColor: '#2D5BA3',
  cursorColor: '#1A3D7C',
  cursorWidth: 2,
  barWidth: 3,
  barHeight: 1,
  barRadius: 3,
  barGap: 2,
  backgroundColor: '#F5F7FA',
  normalize: true,
  
  // 交互配置
  interact: true,
  dragToSeek: true,
  autoScroll: true,
  autoCenter: true,
  hideCursor: false,
  skipLength: 5,
  
  // 音频处理
  backend: 'WebAudio',
  audioRate: 1.0,
  volume: 0.8,
  loopSelection: true,
  sampleRate: 44100,
  
  // 音频加载
  xhr: {
    cache: 'default',
    mode: 'cors',
    credentials: 'same-origin',
    timeout: 30000
  },
  
  // 性能优化
  partialRender: false,
  closeAudioContext: true,
  removeMediaElementOnDestroy: true,
  
  // 分析器配置
  analyserOptions: {
    fftSize: 2048,
    smoothingTimeConstant: 0.8,
    minDecibels: -100,
    maxDecibels: -30
  },
  
  // Canvas配置
  drawingContextAttributes: {
    alpha: true,
    desynchronized: false
  }
});

八、不同场景推荐配置

音乐播放器配置

{
  height: 150,
  waveColor: '#c1d8ff',
  progressColor: '#4a7dff',
  cursorColor: '#1e3a8a',
  barWidth: 3,
  barGap: 2,
  barRadius: 4,
  normalize: true,
  audioRate: 1,
  volume: 0.8,
  responsive: true
}

语音分析配置

{
  height: 100,
  waveColor: '#f0f0f0',
  progressColor: '#4CAF50',
  cursorColor: '#333',
  barWidth: 1,
  barGap: 1,
  normalize: false,
  minPxPerSec: 100,
  splitChannels: true
}

大文件优化配置

{
  partialRender: true,
  pixelRatio: 1,
  barWidth: 0,
  minPxPerSec: 20,
  forceDecode: false,
  xhr: {
    cache: 'force-cache'
  }
}

九、注意事项

1. 必填参数 ：container 是唯一必须提供的参数
2. 后端选择 ：backend 默认为 'WebAudio'，支持更多功能
3. 响应式 ：responsive 和 fillParent 通常一起使用
4. 性能 ：大文件建议启用 partialRender
5. 兼容性：确保浏览器支持 Web Audio API
6. 移动端 ：在移动设备上适当降低 pixelRatio 以提升性能