# @vocalstack/player 中文文档

规范地址：https://npmcn.com/package/%40vocalstack/player/

版本：0\.1\.0-alpha\.14
npm 元数据更新时间：2026-11-02T20:30:56.522Z
中文译文更新时间：2026-11-02T20:35:32.372Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.4 MB，44 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react \>=18，react-dom \>=18
- 首次发布：2026-11-02T15:31:49.748Z
- 最新版本发布：2026-11-02T20:30:55.771Z
- 已发布版本数：16（近 12 个月 16 个）

## 中文简介

用于React的VocalStack视频和脚本播放器：同步脚本，字幕，口语翻译和背景声音，通过公共VocalStack API。

## 安装

```sh
npm install @vocalstack/player
```

也可以使用：`pnpm add @vocalstack/player`、`yarn add @vocalstack/player`、`bun add @vocalstack/player`

## README

# @vocalstack /播放器

一个React视频和脚本播放器 [VocalStack](https://vocalstack.com/) 音标。它会显示字幕、同步的文字记录，以及用说话者自己（克隆的）或固定的声音朗读的口语翻译。它还可以删除背景声音。它只与公共VocalStack API对话。

```bash
npm install @vocalstack/player
```

```tsx
import { VocalStackPlayer } from '@vocalstack/player';
import '@vocalstack/player/style.css';

export function Video() {
  return <VocalStackPlayer id="r4m4srrrhi24" mode="video" />;
}
```

`id` 是来自VocalStack共享链接的共享代码(`vocalstack.com/v/<code>`）. 共享的转录不需要钥匙。

## 道具

| 道具 | 默认的 |  |
| --- | --- | --- |
| `id` |  | 共享代码。或者,与 `token`，一个转录id。既无 `id` 也不 `src`，玩家打开一个盒子，访问者在其中粘贴任何视频链接并将其转录到自己的VocalStack帐户中。 |
| `src` |  | 一个视频或音频链接（YouTube, Vimeo， mp3或任何媒体URL），而不是 `id`。如果访问者已经用VocalStack转录了它，它就会播放。如果没有，他们会被问及是否开始转录。与 `token`，该链接将在该帐户中查找。 |
| `token` |  | 用于私有转录的浏览器令牌（或返回令牌的函数）。永远不要将API密钥传递给浏览器。 |
| `mode` | `'video'` | `'video'` 对于完整玩家来说， `'transcript'` 对于一个球员的阅读视图。 |
| `layout` | `'embed'` | `'embed'` 大小到它的容器（16:9视频）。 `'page'` 填充页面。 |
| `settings` |  | 你控制的设置。改变一个值会更新玩家。见下文。 |
| `initial` |  | 相同的设置，在开始时应用一次。观众可以在之后更改它们。 |
| `onSettingsChange` |  | 当查看器改变一个设置时，调用所有设置。 |
| `controls` | 都在 | `{ language, subtitles, audio, export, share, fullscreen, settings }`。通过 `false` 隐藏一个。 |
| `autoplay` | `true` | 在浏览器需要的地方静音启动。 |
| `startAt` |  | 开始时间，以秒为单位。 |
| `endCard` | 在 | 在一个视频的最后，提供转录另一个链接在访问者自己的VocalStack帐户。通过 `false` 关掉它。 |
| `baseUrl` | `https://api.vocalstack.com` |  |
| `onSource`， `onProgress`， `onError` |  | 调用加载转录，转录进度（0-100） `null` 完成时)和错误。 |
| `onPlayback` |  | 一秒钟打十次电话，只要情况有变 `{ t, dur, playing, idx, seekN, lang }`：以秒为单位的时间，长度，是否播放，当前行的索引，每次查找时增长的计数器，以及显示的语言。 |
| `ref` |  | 一、 `PlayerHandle`： `seek(t)`， `play()`， `pause()`， `toggle()`. |
| `compact` | `false` | 任意宽度的小控件，暂停时没有标题、摘要或共享卡片。对于侧栏或卡牌内的玩家。 |
| `poster` |  | 在选择视频之前或在访问者连接之前，在播放器后面显示的图像。 |

### 设置

```ts
{
  lang?: string | null;          // translate into this language code; null = as spoken
  subtitles?: boolean;           // captions over the video
  speakerLabels?: boolean;       // who is speaking, before each line
  wordHighlight?: boolean;       // follow each word as it is spoken
  translateAudio?: boolean;      // hear the translation read aloud
  voices?: 'cloned' | 'synthetic';
  removeBackground?: boolean;    // play only the speech
}
```

```tsx
<VocalStackPlayer
  id="r4m4srrrhi24"
  settings={{ lang: 'es', speakerLabels: true, voices: 'cloned' }}
  controls={{ export: false, share: false }}
  onSettingsChange={(s) => console.log(s)}
/>

<VocalStackPlayer src="https://www.youtube.com/watch?v=QWCLiPOgeuw" />
```

跟随并驱动它从您的页面：

```tsx
const player = useRef<PlayerHandle>(null);
<VocalStackPlayer ref={player} id="r4m4srrrhi24" onPlayback={(s) => setAt(s.t)} />
<button onClick={() => player.current?.seek(42)}>Jump to 0:42</button>
```

通过覆盖上的CSS变量来主题化它 `.vsp`例如： `--vsp-radius`， `--brand` 和 `--vs-font-sans`.

## 许可证

麻省理工学院

## 常见问题

### @vocalstack/player 是什么？

用于React的VocalStack视频和脚本播放器：同步脚本，字幕，口语翻译和背景声音，通过公共VocalStack API。

### 如何安装 @vocalstack/player？

在项目目录运行 npm install @vocalstack/player，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18）、react-dom（\>=18）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @vocalstack/player 支持 TypeScript 吗？

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

### @vocalstack/player 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @vocalstack/player 可以商用吗？

@vocalstack/player 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @vocalstack/player 还在维护吗？

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