# @desert-ant-labs/voz 中文文档

规范地址：https://npmcn.com/package/%40desert-ant-labs/voz/

版本：4\.3\.0
npm 元数据更新时间：2026-11-05T21:27:03.976Z
中文译文更新时间：2026-11-12T01:11:35.835Z
软件包许可：SEE LICENSE IN LICENSE\.md

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

原始 npm 页面：https://www.npmjs.com/package/%40desert-ant-labs/voz
原文对照：https://npmcn.com/package/%40desert-ant-labs/voz/?lang=original
项目主页：https://desertant.com/models/voz/
源码仓库：https://github.com/Desert-Ant-Labs/desert-ant-core

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

- 包体积（解压后）：46.6 MB，24 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：3 个
- peer 依赖：onnxruntime-web \>=1\.23\.0
- 首次发布：2026-09-23T17:12:12.393Z
- 最新版本发布：2026-11-05T21:27:03.823Z
- 近 30 天下载量：8644（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

JavaScript的On-device语音识别:有词级时间戳的文字记录,有25种语言. 在WebAssembly + ONNX Runtime Web的浏览器中运行(WebGPU,在浏览器所在的WebNN上设置解码步骤),在节点的服务器侧从一个 im中运行

## 安装

```sh
npm install @desert-ant-labs/voz
```

也可以使用：`pnpm add @desert-ant-labs/voz`、`yarn add @desert-ant-labs/voz`、`bun add @desert-ant-labs/voz`

## README

# @ 沙漠- ant- labs/ voz

对在浏览器和节点运行的JavaScript进行在线语音识别. 给Voz音频,它返回一个记录片,每个字都有起始和结尾,跨越25种语言. 音频留在本地:没有上传,也没有 API 密钥 .

一个入口, `@desert-ant-labs/voz`一个 `Voz` API (英语). 不像这个项目的其他型号 `/native` 子路径: Voz 没有原生的节点核心, 因此浏览器和服务器运行着同样的WebAssembly 管道—— 与 Swift SDK 相同的窗口, 车道相撞的解码和相接点—— 运行在 ONNX 运行时 .

```bash
# Browser
npm i @desert-ant-labs/voz onnxruntime-web

# Node
npm i @desert-ant-labs/voz onnxruntime-node
```

在浏览器中您会安装运行时间, 而不是其他的 。 输入于 需求,方式 `@litertjs/core` 用于这个项目的其他模式 捆绑者把它分成自己的块, 所以一个从不转录的页面从不 下载它.

```js
import { Voz } from "@desert-ant-labs/voz";

const voz = await Voz.load();
const result = await voz.transcribe(file);   // a File, Blob, ArrayBuffer, or samples

result.text;            // "the transcript, as one string"
result.words[0];        // { text: "the", start: 0.08, end: 0.24 }
result.realtimeFactor;  // seconds of audio per second of wall clock
```

文件是片面的,当模型通过它, 所以五分钟 录音和5小时的1 花费同样的记忆。 见 [内存](https://npmcn.com/package/%40desert-ant-labs/voz/#readme-memory) 对于这意味着什么 数字.

在节点下,你通过运行时间, 因为那里是 `onnxruntime-node`页:1 土生土长. 无法捆绑一个 服务器,所以这个不是.

```js
import { Voz } from "@desert-ant-labs/voz";
import * as ort from "onnxruntime-node";

const voz = await Voz.load({ ort });
```

通过 `ort` 在浏览器中工作, 对于已经捆绑 a 的应用程序 运行时间或想要一个非 `onnxruntime-web/webgpu`。 。 。 .

捆绑在第一次使用时从 Hugging Face 下载并缓存( 在浏览器中缓存 API, 在节点中磁盘), 因此重装不会再次取取. 在Npm的柏油球里没有模型大小的船.

## 文字时间戳

每个字都带着 `start` 财务报告和审定财务报表 `end` 从音频开始的几秒钟, 字幕、文字记录和剪辑调查需要:

```js
const { words } = await voz.transcribe(file);

for (const { text, start, end } of words) {
  console.log(`${start.toFixed(2)} -> ${end.toFixed(2)}  ${text}`);
}
```

时间来源于每个字的发音框架 而不是从第二 校正合格证,所以没有额外费用 他们的解析度是一个编码器 帧,80毫秒.

## 你可以转写的东西

| 投入 | 发生什么事 |
| --- | --- |
| `File`, (中文(简体) ), `Blob` | 流出: 成块读取, 任何容器WebCodecs都可以解码 |
| 路径( 第20号+) | 流出,同样的方式 |
| `ArrayBuffer`, (中文(简体) ), `Uint8Array` | 解码整段, 因为字节已经在内存中 |
| `Float32Array` | 作为单一的16千赫样本 |
| `{ samples, sampleRate }` | 恢复到 16 kHz |

浏览器可以交出一个 `<input type="file">` 直接文件 :

```js
input.addEventListener("change", async () => {
  const result = await voz.transcribe(input.files[0], {
    onProgress: (fraction) => console.log(`${Math.round(fraction * 100)}%`),
  });
  console.log(result.text);
});
```

在节点下,路径流 相同的方式a `File` ,它需要节点20或 较新(`fs.openAsBlob`。 WebCodecs 是解码压缩音频, 所以在一个 节点构建没有它, 先转换为 WAV - `ffmpeg -i in.mp4 -ac 1 -ar 16000 out.wav` - 到处都是溪流.

如果一个解码器返回的音频 低于容器说它持有,即 报告而不是转录: `decodeAudioData` 可以返回一个短缓冲 没有错误, 和记录 静静停留一分钟 比一个 失败。 在视频文件中,允许音频音轨短于 照片,它是一个警告.

## 内存

记录长度的常数,即流线点 上面的路径。 在M5上用铬测量,整个浏览器的峰值居民:

| 音频 | 峰值 |
| --- | --- |
| 1分钟 | 2.4 英国 |
| 29分钟 | 2.7 英国 |
| 29分钟,在流出前 | 7.7 GB 数字 |

该层约1.2GB为型号:349 MB重量,约900 MB重量 oNNX 运行时间为编译的会话( 测量, 而非某事) 此软件包可以配置掉 ). 其余的是浏览器本身. 重要的东西 是形状:音频不再贡献,所以长度是免费的.

## 它运行的地方

在浏览器中,编码器运行 **网络GPU** 在浏览器显示的地方 **网络NN** (Cromium today),解码步骤运行在神经引擎上. 两者都是 检测; `Voz.load({ webnn: false })` 强制WebGPU单独.

速度, 十分钟的音频: M5, 38x 上的Chromium实时125x 一辆M1,255x 在一辆M3 Ultra, 和大约35x在Safari。 单词出错率为等值 与 Core ML 构建 Apple SDK 用户(2.83%对2.66%超过300) LibriSpeech 语句,一个对接的靴子无法区分的区别).

在节点下, `onnxruntime-node` 运行在CPU。 这是正确的选择 在服务器上转录一个文件,每秒音频比 同一机上的浏览器路径,因为浏览器到达了 GPU 并 `onnxruntime-node`默认执行提供者不会 .

页面不需要 `SharedArrayBuffer` 并且没有跨源隔离:运行时间 被配置到一个单一的相位线程,该线程在铬和 避免了WebKit JIT的病理,在萨法里花费了15%.

## 正在装入模型

`Voz.load()` 选择:

| 选项 | 默认 |  |
| --- | --- | --- |
| `ort` | 浏览器中的 onnxruntime-web | 您自己的 ONNX 运行时模块; 在节点下需要 |
| `ep` | `"auto"` | `"webgpu"` 或者说 `"wasm"` 以覆盖图表运行的地方 |
| `modelBaseUrl` | 拥抱相貌 | 自己服务捆绑; 必须结束于 `/` |
| `revision` | sDK的胸针 | 加权数的不同修改 |
| `webnn` | 检测 | 在 WebNN 上运行解码步骤 |
| `wasmDir` | 运行时间是自己的 | 哪里的nxruntime -web's `.wasm` 文件来自 |
| `onProgress` | 无 | 下载进度, 作为分数 |
| `cache` | `true` | 缓存已下载的捆绑 |

为了照顾自己,复制 `web/` 权重重目录 在您的应用程序和点旁边 `modelBaseUrl` 临τ. `meta.json` 说出其他的,所以 这里没有要同步的文件列表 .

一个实例包含三个已编译的图表和大约1.2GB的内存(349 MB of 重磅重,所以装入一次,再用一次。 笔录就是一个例子 运行,并同时调用队列而不是互出.

## 所需资源

-   带有WebGPU的浏览器. Chromium 135+和 Safari 26+上测试. 浏览器 适配器无法编译编码器的 f16 阴影器 - 这就是 没有 GPU 曝光的机器 - 运行在 CPU 上,正确和多 慢慢来.
-   流出路径的节点 20+,与 `onnxruntime-node` 已安装.

## 许可证

[沙漠蚂蚁实验室 源头可破坏许可证](https://license.desertant.com/)。为大多数免费提供 应用软件和商务许可证必须规模化。 完整的术语在链接. 许可证发放: [许可@ desertant.com](mailto:licensing@desertant.com)。 。 。 .

SDK的第三方通知: [`THIRD_PARTY_NOTICES.md`](https://github.com/Desert-Ant-Labs/desert-ant-core/blob/main/THIRD_PARTY_NOTICES.md)。 。 。 .

权重第三方通知: [`THIRD_PARTY_NOTICES.md`](https://huggingface.co/desert-ant-labs/voz/blob/main/THIRD_PARTY_NOTICES.md)。 。 。 .

## 常见问题

### @desert-ant-labs/voz 是什么？

JavaScript的On-device语音识别:有词级时间戳的文字记录,有25种语言\. 在WebAssembly \+ ONNX Runtime Web的浏览器中运行\(WebGPU,在浏览器所在的WebNN上设置解码步骤\),在节点的服务器侧从一个 im中运行

### 如何安装 @desert-ant-labs/voz？

在项目目录运行 npm install @desert-ant-labs/voz，或使用 pnpm add / yarn add / bun add。

### @desert-ant-labs/voz 支持 TypeScript 吗？

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

### @desert-ant-labs/voz 支持 ESM 还是 CommonJS？

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

### @desert-ant-labs/voz 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @desert-ant-labs/voz 可以商用吗？

@desert-ant-labs/voz 使用 SEE LICENSE IN LICENSE\.md 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @desert-ant-labs/voz 的下载量有多少？

根据 npm 官方下载统计，@desert-ant-labs/voz 在 2026/10/12 – 2026/11/10 这 30 天内被下载 8,644 次，日均约 288 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @desert-ant-labs/voz 还在维护吗？

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