wavesurfer logo wavesurfer.js v7 (中文网)
GitHub
基于官方 v7 最新架构重构

用 wavesurfer.js
让音频看得见、控得精。

wavesurfer.js 是一个轻量、交互式的 HTML5 波形渲染与播放库。无需任何复杂配置，即可在 Web 应用中提供极其流畅、高清晰度且极具现代感的波形可视化与编辑能力。

立即体验互动工作站 阅读中文开发文档
Quick Start Demo 
import WaveSurfer from 'wavesurfer.js'

const wavesurfer = WaveSurfer.create({
  container: '#waveform',
  waveColor: '#4F4A85',
  progressColor: '#383351',
  url: '/audio.mp3',
})

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

波形交互调音工作站

实时修改配置参数、管理选区插件、导入自定义音频，并即时同步生成可直接复制的初始化代码。

电子音乐主题 (本地预设 1)

本地音频 - 快速解码加载

00:00 / 00:00

音频区域管理 (Regions Plugin)

允许在波形图上创建并保存特定的选择范围，支持拖拽和拉伸。

当前没有定义任何区域。在波形图上拖拽鼠标，或者点击上方按钮随机创建一个。

选择内置免跨域音频

或拖入本地音频 (免跨域限制)

点击此处或将音频文件拖到这

支持 MP3, WAV, OGG, M4A 等

实时 JavaScript 初始化代码 

          

        


      


    

  


  
  

    

      
      
      

        
1. 快速开始 (Quick Start)

        
        

          

            

              你可以使用包管理器安装 wavesurfer.js，并在你的现代前端工程化项目中导入它。由于库中已经直接携带了完整的 TypeScript 类型声明，因此无需为它安装额外的包。
            

            

              # 使用 npm 安装

              npm install --save wavesurfer.js
            

            
            

              // ESM 代码导入

              import WaveSurfer from 'wavesurfer.js'
            

          

          
          

            

              如果你只想在基础的 HTML 网页中以最快速度验证功能，也可以直接引用 UNPKG 的 UMD 编译好的脚本标签。它会将库导出为全局变量 WaveSurfer。
            

            
            

              <!-- 引入核心库 JS 标签 -->

              <script src="https://unpkg.com/wavesurfer.js@7"></script>
            


            

              <!-- 引入 Regions 插件标签 (可选) -->

              <script src="https://unpkg.com/wavesurfer.js@7/dist/plugins/regions.min.js"></script>
            

          

        

      


      
      

        
2. API 参考 (API Reference)

        

          完整的自动生成 API 参考位于官方文档站 wavesurfer.xyz/docs/api。以下汇总了最常用的核心 API 组成：
        


        

          
          

            

              
            

            
核心配置项

            
通过向 WaveSurfer.create() 传入配置对象来初始化波形图：

            
    
              
  • container: DOM 选择器或元素
    • 
              
  • waveColor: 未播放部分的波形颜色
    • 
              
  • progressColor: 已播放部分的波形颜色
    • 
              
  • barWidth: 波形条的像素宽度
    • 
              
  • barGap: 波形条之间的间隔宽度
    • 
              
  • barRadius: 波形条的圆角弧度
    • 
              
  • url: 音频文件的源文件地址
    • 
            

          


          
          

            

              
            

            
常用控制方法

            
通过 wavesurfer 实例，可以在代码中精确操控播放状态：

            
    
              
  • play(): 开始音频播放
    • 
              
  • pause(): 暂停当前播放
    • 
              
  • playPause(): 播放与暂停状态切换
    • 
              
  • zoom(pxPerSec): 设置波形缩放倍率
    • 
              
  • load(url): 加载并解析新的音频文件
    • 
              
  • destroy(): 销毁实例并解除 DOM 绑定
    • 
              
  • setOptions(opts): 动态更新参数配置
    • 
            

          


          
          

            

              
            

            
事件系统监听

            
你可以通过订阅事件来触发业务逻辑：

            
    
              
  • on('ready'): 当音频解码完成且可以播放时
    • 
              
  • on('play'): 音频开始播放时触发
    • 
              
  • on('pause'): 音频暂停播放时触发
    • 
              
  • on('finish'): 音频播放完毕时触发
    • 
              
  • on('timeupdate'): 播放时间进度改变时
    • 
              
  • on('click'): 点击波形图上的某处以进行寻址
    • 
            

          

        

      


      
      

        
3. 官方插件生态 (Plugins)

        

          wavesurfer.js 团队原生维护了许多插件，允许开发者零成本扩展波形图的高级交互：
        


        

          

            
Regions (区域)

            

              在波形图上叠加可视化的交互选区。支持设置不同的颜色、拖动位置、拉伸大小，常用于音频分段打标、裁剪以及循环区间播放。
            

          

          
          

            
Timeline (时间刻度)

            

              在音频波形的下方或上方显示精细的标尺，显示当前播放的秒数以及刻度，极其适合音频轨道精确定位。
            

          


          

            
Minimap (滚动导航)

            

              当波形图被放大后，Minimap 会在主波形图下方渲染一个全局小图，指示出当前屏幕可见部分的框线，起到类似地图导航的作用。
            

          


          

            
Record (录音)

            

              允许通过用户的麦克风直接实时进行录音，并随着音量的接收即时绘制出当前的声波图，常用于实时音视频采集应用中。
            

          


          

            
Hover (悬停定位)

            

              当用户的鼠标滑过波形图时，会在光标下方绘制一条高亮的时间垂线，并浮现出悬停位置所对应的具体秒数，提升交互的严谨度。
            

          


          

            
Spectrogram (频谱图)

            

              不仅仅展示时域音量，还会结合快速傅里叶变换 (FFT) 渲染出频域频谱图，完美地分析音频不同频率段的能量分布情况。
            

          

        

      


      
      

        
4. CSS 样式微调 (CSS Styling)

        

          wavesurfer.js v7 被渲染至隔离的 Shadow DOM 树中。这使用户网页中原有的 CSS 样式无法干扰波形图元素。

          不过，你可以使用 CSS 的 ::part() 伪元素选择器，选择并定制 Shadow DOM 中带有 part 属性的各种元素。
        


        

          

            

              
样式覆盖示例

              

                在网页全局 CSS 文件中，你可以直接通过 container 的 ID 或者 class 穿透自定义波形的光标、选区背景与样式。
              

            

            
            
/* 修改波形图寻址光标 */
#waveform ::part(cursor):before {
  content: '🏄';
}

/* 修改 Regions 音频选区的字体家族 */
#waveform ::part(region) {
  font-family: fantasy;
}

          


          

            

              
关于 DOM 结构的说明

              

                你可以使用浏览器的开发者工具 (F12) 审查波形图的容器。在 #shadow-root 内部，每个带有 part="..." 属性的 DOM 节点都是合法的穿透定位点。
              

            

            

              
part="wrapper" - 最外层波形图容器

              
part="canvas-container" - 绘图 Canvas 所在的盒子

              
part="cursor" - 随时间播放而滑动的垂直定位光标线

              
part="region" - 当开启选区插件后，对应的选区覆盖层 DOM

            

          

        

      


      
      

        
5. 常见问题解答 (FAQ)

        
        

          
          

            
            

              

                Wavesurfer 会通过 Ajax 去获取音频文件的数据并在浏览器端直接解码。这意味着你的服务器必须支持并配置了正确的 CORS 跨域请求响应头（Access-Control-Allow-Origin）。如果音频放在第三方的 CDN 上，请务必确保其响应头上包含允许你域名访问的参数。在网页端 JS 中，你是无法绕过该安全机制的。建议本地开发时启动如 Live Server 类似的本地服务器，而非直接双击 HTML 文件运行。
              

            

          


          
          

            
            

              

                由于解码音频的 Web Audio API 会将完整的音频数据解压并占用较多的内存，若读取极长的音频（例如长达数小时的录音），可能导致浏览器标签页内存溢出崩溃。对此，建议使用“预解码峰值数据 (Pre-decoded Peaks)”方案。你可以通过使用后台工具（如 audiowaveform）预先提取出音频的波形包络 JSON 数据，然后在初始化 wavesurfer时作为 peaks 参数直接渲染，此时 wavesurfer 不需要下载并解码音频，极大地节约了网络与内存。
              

            

          


          
          

            
            

              

                对于在线流媒体，因为音频文件是一个源源不断流进来的数据，wavesurfer 在解码完毕前是拿不到未来的波形数据的。流式音频仅在**配合使用预解码的峰值数据与明确的时长**时才受支持，否则将仅展示正在缓存和已播放部分的临时波形。
              

            

          


          
          

            
            

              

                如果音频使用了 VBR (可变比特率 Variable Bit Rate) 压缩格式，不同时间段的数据量不一样，解压缩后的物理采样位置可能会计算不准导致音画偏差。建议将音频文件转换为 CBR (恒定比特率 Constant Bit Rate) 音频重新尝试。此外，你也可以在 wavesurfer 初始化时，使用更精准的 Web Audio API 垫片 (webaudio-shim.js) 来强行校正。
              

            

          


          
          

            
            

              

                Wavesurfer.js 本质上是一个附带音频波形渲染的可视化播放器。它并不是为了成为一个完整的 Web Audio DAW 音频工作站而设计的。它允许你通过导出其内部的 AudioElement 来将其接入 Web Audio 复杂的路由图中，但它本身没有、也不打算支持剪辑音频、裁剪轨道、多轨混音或直接向音频中写入音效的能力。
              

            

          

        

      


      
      

        
6. 本地开发与测试 (Development)

        
        

          

            
开发流程

            

              

                # 安装依赖

                yarn
              

              
              

                # 启动热重载服务器 (端口 9090)

                yarn start
              

            

          


          

            
测试套件

            

              测试采用了 Cypress 框架，混合了标准的 API 端到端 (E2E) 功能测试与高精度的像素级视觉回归测试。
            

            

              

                # 构建生产产物

                yarn build
              

              
              

                # 启动 Cypress 进行自动化测试

                yarn cypress