# @corpusant/wavesurfer\.js 中文文档

规范地址：https://npmcn.com/package/%40corpusant/wavesurfer.js/

版本：7\.9\.0
npm 元数据更新时间：2025-02-07T03:03:19.884Z
中文译文更新时间：2026-11-10T22:23:28.717Z
软件包许可：BSD-3-Clause

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40corpusant/wavesurfer.js
原文对照：https://npmcn.com/package/%40corpusant/wavesurfer.js/?lang=original
项目主页：https://wavesurfer.xyz/
源码仓库：https://github.com/katspaugh/wavesurfer.js

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：593 kB，69 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2025-02-07T03:03:19.246Z
- 最新版本发布：2025-02-07T03:03:19.603Z
- 近 30 天下载量：2584（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：1（近 12 个月 0 个）

## 中文简介

音频波形播放器

## 安装

```sh
npm install @corpusant/wavesurfer.js
```

也可以使用：`pnpm add @corpusant/wavesurfer.js`、`yarn add @corpusant/wavesurfer.js`、`bun add @corpusant/wavesurfer.js`

## README

# ![logo](https://user-images.githubusercontent.com/381895/226091100-f5567a28-7736-4d37-8f84-e08f297b7e1a.png) (原始内容存档于2018-03-21). wasurfer.js

[![npm](https://img.shields.io/npm/v/wavesurfer.js)](https://www.npmjs.com/package/wavesurfer.js) [![sponsor](https://img.shields.io/badge/sponsor_us-%F0%9F%A4%8D-%23B14586)](https://github.com/sponsors/katspaugh)

**Vavesurfer.js (英语)** 是一个交互式波形渲染和音频回放库,适合网络应用程序。 它利用现代的网络技术,提供强有力的视觉参与音频体验.

![waveform screenshot](https://github.com/katspaugh/wavesurfer.js/assets/381895/05f03bed-800e-4fa1-b09a-82a39a1c62ce)

**黄金赞助商** [关闭字幕创建者](https://www.closedcaptioncreator.com/)

# 目录

1.  [开始](https://npmcn.com/package/%40corpusant/wavesurfer.js/#readme-getting-started)
2.  [API 参考](https://npmcn.com/package/%40corpusant/wavesurfer.js/#readme-api-reference)
3.  [插件](https://npmcn.com/package/%40corpusant/wavesurfer.js/#readme-plugins)
4.  [CSS 样式](https://npmcn.com/package/%40corpusant/wavesurfer.js/#readme-css-styling)
5.  [常见问题](https://npmcn.com/package/%40corpusant/wavesurfer.js/#readme-questions)
6.  [从v6升级到v7](https://npmcn.com/package/%40corpusant/wavesurfer.js/#readme-upgrading-from-v6-to-v7)
7.  [发展](https://npmcn.com/package/%40corpusant/wavesurfer.js/#readme-development)
8.  [测试](https://npmcn.com/package/%40corpusant/wavesurfer.js/#readme-tests)
9.  [反馈](https://npmcn.com/package/%40corpusant/wavesurfer.js/#readme-feedback)

## 开始

安装和导入软件包 :

```bash
npm install --save wavesurfer.js
```

```js
import WaveSurfer from 'wavesurfer.js'
```

或者插入一个 UMD 脚本标签,将库导出为全局 `WaveSurfer` 变量 :

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

创建波浪实例并传递各种 [选项](http://wavesurfer.xyz/docs/options)数字 :

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

要导入一个插件, 例如 [区域插件](https://wavesurfer.xyz/examples/?regions.js)数字 :

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

或作为导出脚本标签 `WaveSurfer.Regions`数字 :

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

TypeScript 类型包含在软件包中,所以不需要安装 `@types/wavesurfer.js`。 。 。 .

看见更多 [实例](https://wavesurfer.xyz/examples)。 。 。 .

## API 参考

请参看我们网站上的wasurfer.js文档:

-   [方法](https://wavesurfer.xyz/docs/methods)
-   [选项](http://wavesurfer.xyz/docs/options)
-   [事件](http://wavesurfer.xyz/docs/events)

## 插件

我们维护一些添加各种额外功能的官方插件:

-   [区域](https://wavesurfer.xyz/examples/?regions.js) - 音频区域的视觉覆盖和标记
-   [时间线](https://wavesurfer.xyz/examples/?timeline.js) - 在波形下方显示节点和时间标签
-   [最小映射](https://wavesurfer.xyz/examples/?minimap.js) - 一个小波形,作为主波形的滚动条
-   [信封](https://wavesurfer.xyz/examples/?envelope.js) – 一个图形界面来添加淡出和出出效果和控制音量
-   [记录](https://wavesurfer.xyz/examples/?record.js) - 记录麦克风的声音并制作出波形
-   [光谱](https://wavesurfer.xyz/examples/?spectrogram.js) - 音频频谱的可视化(由@akreal所写)
-   [缓冲](https://wavesurfer.xyz/examples/?hover.js) - 在波形上显示垂直线和时间图

## CSS 样式

wowsurfer.js v7被制成一棵影子DOM树. 这将其CSS与网页的其余部分隔离. 然而,仍然有可能将各种有CSS的Waverurfer.js元素通过 `::part()` 伪选者. 例如:

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

您可以在 DOM 检查员中看到您可以风格的元素 `part` 属性. 见 [此示例](https://wavesurfer.xyz/examples/?styling.js) 来玩弄造型.

## 问 题

关于将wasurfer.js整合到您的网站上的问题吗? 随便问吧 [讨论论坛](https://github.com/wavesurfer-js/wavesurfer.js/discussions/categories/q-a)。 。 。 .

然而,请铭记,本论坛专门讨论瓦斯沃费尔具体问题。 如果你是JavaScript的新手, 需要帮助 普通基础, 如导入国家防范机制模块.

### 财务问题

我有点问题 Wavesurfer从您指定的 URL 获取音频以解码 。 确保此 URL 允许从您的域获取数据 。 在浏览器 JavaScript 中,您只能从中获取数据编辑器 **相同领域** 或另一个域,如果且仅在该域允许时 [(简体中文)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)因此,如果音频文件位于外部域上,请确保域发送正确的访问控制-Allow-Origin信头。 请求方(即你的JS代码)对此无能为力. Wasurfer 支持大文件吗 ? 由于wasurfer在浏览器中完全使用Web Audio来解码音频,大片片段可能由于内存限制而无法解码. 我们建议对大文件使用预先解码的峰值(见 [此示例](https://wavesurfer.xyz/examples/?predecoded.js)) (中文(简体) ). 你可以使用一个工具,比如 [bbc/ 自动波形](https://github.com/bbc/audiowaveform) 生成峰值. 流传的音频呢? 仅以 [预解码峰和持续时间](https://wavesurfer.xyz/examples/?predecoded.js)。 。 。 . 我的音频和波形有不匹配之处 我该怎么修? 如果使用VBR(可变比特率)音频文件,音频和波形之间可能存在不匹配. 这可以通过将您的文件转换为 CBR( 恒定比特速率)来固定.

或者,你可以使用 [网络音频 shim](https://wavesurfer.xyz/examples/?webaudio-shim.js) 这更准确.

我如何将Waverurfer.js与Web音频效果联系起来? 一般来说,wasurfer.js并不打算成为所有事物的包装器Web Audio. 它只是一个具有波形可视化的玩家. 它的确允许通过导出其音频元素来连接自己到一个Web音频图(参见 [此示例](https://wavesurfer.xyz/examples/?4436ec40a2ab943243755e659ae32196))但无更相. 请不要期望浪客能够以任何方式切割,添加效果,或处理你的音频.

## 从v6升级到v7

Wavesurfer.js v7是一款由Waveurfer.js重写而成的TypeScript重写,带来若干改进:

-   为更好的发展经验而输入的API
-   加强解码和渲染性能
-   新建和改进的插件

大多数选项,事件,方法都与前几个版本类似.

### 显著差异

-   默认情况下 HTML 音频回放( 用于选择通过) `backend: "MediaElement"`(中文(简体) )
-   标记插件被删除 – 您应该使用区域插件, 只需要一个 `startTime`。 。 。 .
-   没有麦克风插件 – 被更多功能的新唱片插件所取代.
-   光标插件被Hover插件所取代.

### 删除选项

-   `audioContext`, (中文(简体) ), `closeAudioContext`, (中文(简体) ), `audioScriptProcessor`
-   `autoCenterImmediately` – 说吧 – `autoCenter` 现在总是立即,除非音频在播放
-   `backgroundColor`, (中文(简体) ), `hideCursor` - 这很容易通过CSS设定
-   `mediaType` -你应该通过整个媒体元素 `media` 选项. [示例](https://wavesurfer.xyz/examples/?video.js)。 。 。 .
-   `partialRender` - 默认完成
-   `pixelRatio` – 说吧 – `window.devicePixelRatio` 默认使用
-   `renderer` - 目前只有一个渲染器 所以不需要这个选择
-   `responsive` - 默认启用响应
-   `scrollParent` - 如果 `minPxPerSec` 设置为更高值
-   `skipLength` - 没有 `skipForward` 财务报告和审定财务报表 `skipBackward` 方法已经
-   `splitChannelsOptions` - 你现在应该用 `splitChannels` 以通过频道选项。 过 `height: 0` 隐藏频道。 见 [此示例](https://wavesurfer.xyz/examples/?split-channels.js)。 。 。 .
-   `drawingContextAttributes`, (中文(简体) ), `maxCanvasWidth`, (中文(简体) ), `forceDecode` - 删除以减少代码复杂度
-   `xhr` - 请用 `fetchParams` 换成
-   `barMinHeight` - 默认最小栏高为 1 像素

### 删除的方法

-   `getFilters`, (中文(简体) ), `setFilter` - 看到了吗 [Web 音频示例](https://wavesurfer.xyz/examples/?webaudio.js)
-   `drawBuffer` - 重新绘制波形,使用 `setOptions` 转而通过新的渲染选项
-   `cancelAjax` - 你可以通过一个 [中止符号](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) 内 `fetchParams`
-   `skipForward`, (中文(简体) ), `skipBackward`, (中文(简体) ), `setPlayEnd` - 可使用 `setTime(time)`
-   `exportPCM` 替换为 `exportPeaks` 返回浮点数组
-   `toggleMute` 现在叫做 `setMuted(true | false)`
-   `setHeight`, (中文(简体) ), `setWaveColor`, (中文(简体) ), `setCursorColor`等 – 使用 `setOptions` 改为相应的参数。 例如, `wavesurfer.setOptions({ height: 300, waveColor: '#abc' })`

见完整 [新API的文档](http://wavesurfer.xyz/docs)。 。 。 .

## 发展

为了从发展入手,遵循这些步骤:

1.  安装非依赖性 :

```
yarn
```

2.  在监视模式下启动 TypeScript 编译器并启动 HTTP 服务器 :

```
yarn start
```

此命令将在您的浏览器中打开 http://localhost: 9090, 并进行活的重载, 允许您看到您正在开发的更改 .

## 测试

测试用Cypress框架书写. 它们是e2e和视觉回归测试的组合.

要在当地运行测试套件,首先要构建项目:

```
yarn build
```

然后启动测试:

```
yarn cypress
```

## 反馈

我们感谢你的反馈和贡献!

如果你遇到任何问题或有改进建议,请不要犹豫,在我们这里张贴 [论坛](https://github.com/wavesurfer-js/wavesurfer.js/discussions/categories/q-a)。 。 。 .

我们希望你们喜欢使用wasurfer.js,并期待着听到你们在图书馆的经历!

## 常见问题

### @corpusant/wavesurfer\.js 是什么？

音频波形播放器

### 如何安装 @corpusant/wavesurfer\.js？

在项目目录运行 npm install @corpusant/wavesurfer\.js，或使用 pnpm add / yarn add / bun add。

### @corpusant/wavesurfer\.js 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @corpusant/wavesurfer\.js 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @corpusant/wavesurfer\.js 可以商用吗？

@corpusant/wavesurfer\.js 使用 BSD-3-Clause 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。另外不得用原作者名义为衍生产品背书。以上为概括，不构成法律意见，请以许可原文为准。

### @corpusant/wavesurfer\.js 的下载量有多少？

根据 npm 官方下载统计，@corpusant/wavesurfer\.js 在 2026/10/11 – 2026/11/09 这 30 天内被下载 2,584 次，日均约 86 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @corpusant/wavesurfer\.js 还在维护吗？

最新版本 7\.9\.0 发布于 2025/02/07（1\.8 年前）；至今共发布 1 个版本，其中过去 12 个月发布了 0 个；首次发布于 2025/02/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。