<img src="https://yellow-cdn.veclightyear.com/835a84d5/42951427-e705-409a-8d8e-271e42e00e43.png" alt="logo" height="60" valign="middle" /> wavesurfer.js

Wavesurfer.js 是一个交互式波形渲染和音频播放库，非常适合网络应用。它利用现代网络技术提供了强大且视觉上引人入胜的音频体验。

黄金赞助商 💖 Closed Caption Creator

开始使用

安装并导入包：

npm install --save wavesurfer.js

import WaveSurfer from 'wavesurfer.js'

或者，插入一个UMD脚本标签，将库作为全局变量 WaveSurfer 导出：

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

创建一个wavesurfer实例并传入各种选项：

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

要导入插件，例如Regions插件：

import Regions from 'wavesurfer.js/dist/plugins/regions.esm.js'

或者作为脚本标签导出 WaveSurfer.Regions：

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

包中已包含TypeScript类型定义，因此无需安装 @types/wavesurfer.js。

查看更多示例。

API参考

请参阅我们网站上的wavesurfer.js文档：

插件

我们维护了一些官方插件，添加了各种额外功能：

Regions – 音频区域的视觉叠加和标记
Timeline – 在波形下方显示刻度和时间标签
Minimap – 作为主波形滚动条的小型波形
Envelope – 用于添加淡入淡出效果和控制音量的图形界面
Record – 从麦克风录制音频并渲染波形
Spectrogram – 音频频谱可视化（由@akreal编写）
Hover – 在波形悬停时显示垂直线和时间戳

CSS样式

wavesurfer.js v7渲染到Shadow DOM树中。这将其CSS与网页的其他部分隔离。然而，仍然可以通过 ::part() 伪选择器使用CSS来设置各种wavesurfer.js元素的样式。例如：

#waveform ::part(cursor):before {
  content: '🏄';
}
#waveform ::part(region) {
  font-family: fantasy;
}

你可以在DOM检查器中查看可以设置样式的元素 – 它们会有一个 part 属性。查看此示例来尝试样式设置。

问题

对在您的网站上集成wavesurfer.js有疑问吗？请随时在我们的讨论论坛中提问。

但请记住，这个论坛专门用于wavesurfer相关问题。如果你是JavaScript新手，需要帮助解决一般基础问题（如导入NPM模块），请考虑先询问ChatGPT或StackOverflow。

常见问题

<details> <summary>我遇到了CORS问题</summary> Wavesurfer从你指定的URL获取音频以进行解码。确保这个URL允许从你的域名获取数据。在浏览器JavaScript中，你只能从<b>同一域名</b>或者另一个启用了<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS">CORS</a>的域名获取数据。因此，如果你的音频文件在外部域名上，请确保该域名发送正确的Access-Control-Allow-Origin头。从请求方（即你的JS代码）无法对此做任何处理。 </details> <details> <summary>wavesurfer支持大文件吗？</summary> 由于wavesurfer使用Web Audio在浏览器中完全解码音频，大型音频可能会由于内存限制而无法解码。我们建议对大文件使用预解码的峰值（参见<a href="https://wavesurfer.xyz/examples/?predecoded.js">这个示例</a>）。你可以使用像<a href="https://github.com/bbc/audiowaveform">bbc/audiowaveform</a>这样的工具来生成峰值。 </details> <details> <summary>流媒体音频怎么样？</summary> 流媒体音频仅支持<a href="https://wavesurfer.xyz/examples/?predecoded.js">预解码的峰值和持续时间</a>。 </details> <详细信息> <摘要>我的音频与波形不匹配。如何修复？</摘要> 如果您使用的是VBR（可变比特率）音频文件，音频和波形之间可能会出现不匹配。可以通过将文件转换为CBR（固定比特率）来解决这个问题。 <p>或者，您可以使用<a href="https://wavesurfer.xyz/examples/?webaudio-shim.js">Web Audio垫片</a>，它的精确度更高。</p> </详细信息>

<详细信息> <摘要>如何将wavesurfer.js连接到Web Audio效果？</摘要> 通常，wavesurfer.js并不旨在成为所有Web Audio相关功能的封装器。它只是一个带有波形可视化的播放器。它确实允许通过导出其音频元素来连接到Web Audio图（参见<a href="https://wavesurfer.xyz/examples/?4436ec40a2ab943243755e659ae32196">此示例</a>），但仅此而已。请不要期望wavesurfer能够以任何方式剪切、添加效果或处理您的音频。 </详细信息>

v7 – 全新的TypeScript版本

Wavesurfer.js v7是wavesurfer.js的TypeScript重写版本，带来了几项改进：

类型化API，提供更好的开发体验
增强的解码和渲染性能
新的和改进的插件

从v6升级

大多数选项、事件和方法与之前的版本相似。

主要区别

默认使用HTML音频播放（以前是通过backend: "MediaElement"选择加入）
移除了标记插件 – 您应该使用只有startTime的区域插件
没有麦克风插件 – 被新的具有更多功能的录音插件取代
光标插件被悬停插件取代

移除的选项

audioContext、closeAudioContext、audioScriptProcessor
autoCenterImmediately – 除非音频正在播放，否则autoCenter现在始终立即生效
backgroundColor、hideCursor – 可以通过CSS轻松设置
mediaType – 您应该在media选项中传递整个媒体元素。示例
partialRender – 默认执行
pixelRatio – 默认使用window.devicePixelRatio
renderer – 目前只有一个渲染器，所以不需要此选项
responsive – 默认启用响应式
scrollParent – 如果将minPxPerSec设置为更高的值，容器将滚动
skipLength – 不再有skipForward和skipBackward方法
splitChannelsOptions – 现在应使用splitChannels传递通道选项。传递height: 0以隐藏通道。参见此示例
drawingContextAttributes、maxCanvasWidth、forceDecode – 为减少代码复杂性而移除
xhr - 请改用fetchParams
barMinHeight - 最小条高度现在默认为1像素

移除的方法

getFilters、setFilter – 参见Web Audio示例
drawBuffer – 要重绘波形，请使用setOptions并传递新的渲染选项
cancelAjax – 您可以在fetchParams中传递AbortSignal
skipForward、skipBackward、setPlayEnd – 可以使用setTime(time)实现
exportPCM替换为exportPeaks，返回浮点数组
toggleMute现在称为setMuted(true | false)
setHeight、setWaveColor、setCursorColor等 – 使用setOptions和相应的参数代替。例如，wavesurfer.setOptions({ height: 300, waveColor: '#abc' })