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

QINS
361 阅读5分钟

# 最全音频处理WaveSurferjs事件配置文档

一、基础使用示例

// 基础用法
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);

二、完整配置参数表格

基础配置参数

参数名类型默认值说明
containerString/HTMLElement必填波形图容器（CSS选择器或DOM元素）
heightNumber128波形图高度（像素）
widthNumber0波形图宽度，0表示自动填充
responsiveBooleantrue是否响应式布局
pixelRatioNumberwindow.devicePixelRatio像素比，用于高清屏
fillParentBooleantrue是否填充父容器
scrollParentBooleanfalse是否启用横向滚动
minPxPerSecNumber0最小每秒像素数
hideScrollbarBooleanfalse是否隐藏滚动条

波形样式参数

参数名类型默认值说明
waveColorString'#999'波形颜色
progressColorString'#555'播放进度颜色
cursorColorString'#333'光标颜色
cursorWidthNumber1光标宽度（像素）
barWidthNumber0条形宽度，0表示自动计算
barHeightNumber1条形高度比例（0-1）
barRadiusNumber0条形圆角半径
barGapNumber1条形间距
backgroundColorStringnull背景颜色
backgroundImageStringnull背景图片URL
waveBackgroundColorStringnull波形背景颜色
normalizeBooleanfalse是否归一化波形
splitChannelsBooleanfalse是否分离声道显示
waveShadowColorStringnull波形阴影颜色
waveShadowBlurNumber0阴影模糊度
waveShadowOffsetXNumber0阴影X偏移
waveShadowOffsetYNumber0阴影Y偏移

交互配置参数

参数名类型默认值说明
interactBooleantrue是否启用交互
dragToSeekBooleantrue是否允许拖动跳转
autoScrollBooleantrue播放时是否自动滚动
autoCenterBooleantrue是否自动居中播放位置
hideCursorBooleanfalse是否隐藏光标
skipLengthNumber2跳过秒数（键盘快捷键）
showTimePositionBooleantrue是否显示时间位置
regionsMinLengthNumber0.01最小区域长度（秒）
regionsSnapToGridBooleanfalse是否对齐网格
removeMediaElementOnDestroyBooleantrue销毁时是否移除媒体元素
partialRenderBooleanfalse是否部分渲染
rtlBooleanfalse是否从右到左布局

音频处理参数

参数名类型默认值说明
backendString'WebAudio'音频后端：'WebAudio' 或 'MediaElement'
mediaTypeString'audio'媒体类型：'audio' 或 'video'
audioRateNumber1播放速度（0.5-4）
volumeNumber1音量（0-1）
loopSelectionBooleantrue是否循环选区
sampleRateNumber0采样率，0表示自动
audioContextAudioContextnull自定义AudioContext
fftSmoothingTimeConstantNumber0.8FFT平滑常数
filterString'none'滤波器类型：'lowpass'、'highpass'、'bandpass'
filterFrequencyNumbernull滤波频率
filterQNumbernull滤波器Q值

音频加载参数

参数名类型默认值说明
urlStringnull音频URL（可直接在此指定）
xhrObject{}XMLHttpRequest配置
mediaControlsBooleanfalse是否显示浏览器原生控制条
audioBufferAudioBuffernull预加载的AudioBuffer
peaksArraynull预计算的峰值数据
durationNumbernull音频时长（秒）
forceDecodeBooleanfalse是否强制解码

性能优化参数

参数名类型默认值说明
renderFunctionFunctionnull自定义渲染函数
drawingContextAttributesObject{alpha: true}Canvas上下文属性
splitChannelsBooleanfalse是否分离声道处理
mediaContainerHTMLElementnull自定义媒体容器
mediaElementHTMLMediaElementnull自定义媒体元素
closeAudioContextBooleanfalse销毁时是否关闭AudioContext

XHR配置参数

参数名类型默认值说明
xhr.cacheString'default'缓存策略
xhr.modeString'cors'跨域模式
xhr.credentialsString'same-origin'凭证设置
xhr.referrerString'client'引用来源
xhr.timeoutNumber0超时时间（毫秒）
xhr.headersObject{}请求头

分离声道配置参数

参数名类型默认值说明
splitChannelsOptions.overlayBooleanfalse是否叠加显示
splitChannelsOptions.channelColorsObject{}各声道颜色配置
splitChannelsOptions.filterChannelsArray[]过滤显示的声道
splitChannelsOptions.relativeNormalizationBooleanfalse相对归一化

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

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.fftSizeNumber2048FFT大小
analyserOptions.smoothingTimeConstantNumber0.8平滑时间常数
analyserOptions.minDecibelsNumber-100最小分贝值
analyserOptions.maxDecibelsNumber-30最大分贝值

六、Canvas上下文属性

参数名类型默认值说明
drawingContextAttributes.alphaBooleantrue是否启用透明度
drawingContextAttributes.desynchronizedBooleanfalse是否启用异步渲染

七、完整配置示例

// 完整的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 以提升性能
avatar
文章
阅读
粉丝