@vocalstack/player

中文文档
0.1.0-alpha.14发布于 2026/11/03MITTypeScriptES Module构建来源已验证

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

中文使用文档
文档目录3 节
  1. 道具
  2. 设置
  3. 许可证

@vocalstack /播放器

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

npm install @vocalstack/player
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 隐藏一个。
autoplaytrue在浏览器需要的地方静音启动。
startAt开始时间,以秒为单位。
endCard在在一个视频的最后,提供转录另一个链接在访问者自己的VocalStack帐户。通过 false 关掉它。
baseUrlhttps://api.vocalstack.com
onSource, onProgress, onError调用加载转录,转录进度(0-100) null 完成时)和错误。
onPlayback一秒钟打十次电话,只要情况有变 { t, dur, playing, idx, seekN, lang }:以秒为单位的时间,长度,是否播放,当前行的索引,每次查找时增长的计数器,以及显示的语言。
ref一、 PlayerHandle: seek(t), play(), pause(), toggle().
compactfalse任意宽度的小控件,暂停时没有标题、摘要或共享卡片。对于侧栏或卡牌内的玩家。
poster在选择视频之前或在访问者连接之前,在播放器后面显示的图像。

设置

{
  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
}
<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" />

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

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 共发布 16 个版本,首次发布于 2026/11/02;过去 12 个月发布了 16 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.1.0-alpha.14latest2026/11/03今天
0.1.0-alpha.132026/11/03今天
0.1.0-alpha.122026/11/03今天
0.1.0-alpha.112026/11/03今天
0.1.0-alpha.102026/11/03今天
0.1.0-alpha.92026/11/03今天

关于 @vocalstack/player 的常见问题

@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 和提交记录判断。