# @degreesign/voice 中文文档

规范地址：https://npmcn.com/package/%40degreesign/voice/

版本：2\.4\.2
npm 元数据更新时间：2026-11-09T12:19:43.778Z
中文译文更新时间：2026-11-11T21:28:19.024Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：2 MB，84 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：2 个
- 首次发布：2026-10-19T18:35:09.930Z
- 最新版本发布：2026-11-09T12:19:43.570Z
- 近 30 天下载量：3294（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：22（近 12 个月 22 个）

## 中文简介

网络和节点的线下拼写、文字到文字和文字到语音(TTS)

## 安装

```sh
npm install @degreesign/voice
```

也可以使用：`pnpm add @degreesign/voice`、`yarn add @degreesign/voice`、`bun add @degreesign/voice`

## README

# @ 学位标志/ 语音

将语音转换成文字, 私下, 由用户自己使用 设备。 用它来形容、语音笔记、抄本、语音到文字、文字 转到语音和TTS,之后没有云服务、账户或网络连接 设置.

[![npm version](https://img.shields.io/npm/v/@degreesign/voice.svg)](https://www.npmjs.com/package/@degreesign/voice) [![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://npmcn.com/package/%40degreesign/voice/#readme-licensing) [![node](https://img.shields.io/badge/node-%3E%3D24-brightgreen.svg)](https://npmcn.com/package/%40degreesign/voice/#readme-install) [![types](https://img.shields.io/badge/types-included-blue.svg)](https://npmcn.com/package/%40degreesign/voice/#readme-quick-start)

**[试试现场演示](https://degreesign.github.io/ds_voice/)** 要运行语音到 文本和文本到浏览器中的语音,没有安装.

## 目录

-   [为什么](https://npmcn.com/package/%40degreesign/voice/#readme-why)
-   [安装](https://npmcn.com/package/%40degreesign/voice/#readme-install)
-   [快开始](https://npmcn.com/package/%40degreesign/voice/#readme-quick-start)
-   [对文本的发言](https://npmcn.com/package/%40degreesign/voice/#readme-speech-to-text)
-   [语音文本](https://npmcn.com/package/%40degreesign/voice/#readme-text-to-speech)
-   [语音克隆](https://npmcn.com/package/%40degreesign/voice/#readme-voice-cloning)
-   [拼写](https://npmcn.com/package/%40degreesign/voice/#readme-dictation)
-   [演示](https://npmcn.com/package/%40degreesign/voice/#readme-demo)
-   [模型](https://npmcn.com/package/%40degreesign/voice/#readme-models)
-   [储存和性能](https://npmcn.com/package/%40degreesign/voice/#readme-storage-and-performance)
-   [建筑](https://npmcn.com/package/%40degreesign/voice/#readme-architecture)
-   [许可证发放](https://npmcn.com/package/%40degreesign/voice/#readme-licensing)

## 为什么

-   下行:重量下载一次,然后每个解码都运行在机器上.
-   流线 : `transcribe` 返回活控并不断更新音频 来了.
-   1 API:同名条目自动检测出Node.js和浏览器.
-   任何音频: 16千赫单PCM, a `Blob` 或者说 `File`、 URL、 文件系统路径或 浏览器麦克风.
-   已打入: TypeScript 声明覆盖了每次导出.
-   两个方向:语音到文字,文字到语音.
-   自控: 缓存、 存储和音频解码器在构建时捆绑 时间.

[多莉丝蒂](https://dolisty.com/) 将软件包用于任务描述和语音 注释.

## 安装

```bash
npm install @degreesign/voice
```

```bash
yarn add @degreesign/voice
```

```bash
pnpm add @degreesign/voice
```

需要24号节点或更新。 主要出口的确认和 语音库. 口述控制器有自己的条目.

公布的文件有:

-   `dist/node/degreesign.node.min.js`,用于节点的 CommonJS 条目.
-   `dist/browser/degreesign.min.js`,完整的UMD条目为 `window.dsVoice`。 。 。 .
-   `dist/browser/whisper.min.js`,仅Whisper的UMD条目为 `window.dsVoiceWhisper`。 。 。 .
-   `dist/browser/dictation.min.js`(原始内容存档于2017-03-26). Dictation UMD 条目.
-   `dist/browser/dictation.worker.js`那个预建的拼写工.

从源创建到 `yarn build` 输入 `yarn typecheck`。 。 。 .

### 光盘N

```html
<script src="https://cdn.jsdelivr.net/npm/@degreesign/voice@latest/dist/browser/degreesign.min.js"></script>
```

试试看 [现场演讲演示](https://degreesign.github.io/ds_voice/) 在安装前。 它在浏览器中运行语音到文本和语音.

## 快开始

### 浏览器麦克风

```html
<script src="https://cdn.jsdelivr.net/npm/@degreesign/voice@latest/dist/browser/degreesign.min.js"></script>
<script>
  const { Language, transcribe } = window.dsVoice;
  const session = transcribe({ language: Language.auto });
  const timer = setInterval(() => {
    output.textContent = session.fullText().text;
  }, 500);
  stopButton.onclick = async () => {
    clearInterval(timer);
    const result = await session.stop();
    output.textContent = result.text;
  };
</script>
```

浏览器会话没有 `pcm`,没有 `audioFilePath` 没有要求手动种子 麦克风访问和记录,直到 `stop`。 。 。 .

### PCM 输入

输入为 16 kHz 单 `Float32Array` PCM (英语).

```ts
import { Language, transcribe } from "@degreesign/voice";

const session = transcribe({ pcm, language: Language.auto });
console.log(session.fullText().text);

const result = await session.done;
console.log(result.text, result.duration, result.meta.rtf);
```

先给模特取暖,打个电话 `preloadVoice`在音频到达的时候, 通过 `microphone: false` 并附带样本 `push`。 。 。 .

## 对文本的发言

`transcribe(options?)` 返回 a `TranscribeSession` 马上.

| 成员 | 说明 |
| --- | --- |
| `fullText()` | 最新文本和解码时间。 便宜而同步. |
| `push(pcm)` | 附加 16 kHz 单采样 `microphone: false`。 。 。 . |
| `stop()` | 停止抓取或输入,冲出尾部并下定决心. |
| `cancel()` | 丢弃待发音频并解析, 没有最终解码 . |
| `done` | 在输入结束后决定, `stop` 或者说 `cancel`。 。 。 . |
| `error` | 首先同步失败,或者 `null`。 。 。 . |

### 选项

| 外地 | 说明 |
| --- | --- |
| `model` | `ModelId.WhisperBase`唯一一个模特儿. |
| `pcm` | 16千赫单相 `Float32Array`,最高优先来源. |
| `audioFilePath` | URL 字符串, `Blob` 或者说 `File`,或节点文件系统路径. |
| `microphone` | 抓住麦克风 默认为 `true`· ; `false` 接受 `push`。 。 。 . |
| `language` | 音频语言或 `Language.auto`。默认自动检测. |
| `quality` | `Quality.High` (F16) 默认, `Medium` (问题8 0)或 `Low` (问题4 K M). |
| `timestamps` | `TimestampMode.none`, (中文(简体) ), `.segment` 或者说 `.word`。 。 。 . |
| `lowLatency` | 跳过30秒垫。 默认为 `true`。 。 。 . |
| `allowedDiskSpaceMB` | MB 缓存盖 。 默认为 `512`。 。 。 . |
| `updateIntervalMs` | 现场更新 Cadence in ms. 默认为 `1000`。 。 。 . |
| `weightsBaseUrl` | 重量主机,默认为 `https://huggingface.co`。 。 。 . |
| `weightCacheMB` | MB中的F32起式缓存盖. |
| `threads` | `ThreadCount.Two`, (中文(简体) ), `.Four` 或者说 `.Eight`默认为 `Four`。 。 。 . |
| `onProgress` | 在每个文件中下载并加载进度 . |

### 型号加载

```ts
import {
    Language,
    ModelId,
    Quality,
    isModelCached,
    loadModel,
    preloadVoice,
} from "@degreesign/voice";

await preloadVoice({
    model: ModelId.WhisperBase,
    language: Language.en,
    quality: Quality.Low,
});

const cached = await isModelCached({
    model: ModelId.WhisperBase,
    language: Language.en,
    quality: Quality.Low,
});
const model = await loadModel({
    model: ModelId.WhisperBase,
    language: Language.en,
    quality: Quality.Low,
});
```

`preloadVoice` 提前下载并加载一个模型. `loadModel` 返回时 装入的模型. `isModelCached` 在不使用网络的情况下检查商店. 明确 `Language.en` 选择仅有的英文检查点; 所有其他 语言,包括 `Language.auto`,使用多语种检查站.

### 音频和时间安排

第一个来源获胜: `pcm`,则 `audioFilePath`,然后是一个 手动种子 `microphone: false`,然后是浏览器麦克风.

在节点中,路径从文件系统读取并解码为WAV,FLAC或MP3. 在浏览器中获取 URL, a `Blob` 或者说 `File` 直接读取,以及 解码使用Web Audio API. 支持的浏览器格式取决于 浏览器.

下面的音频 `-50 dBFS` 作为沉默处理,返回空文本,不包含 触摸模型。 短于一秒钟的可读输入集中在 沉默,所以被剪辑的单词保持了两侧上下文.

一段会话在12秒后暂停等待音频,没有音频,或 当停止。 已执行的文本不再更改, 其音频已发布, 因此 内存在长相录音时会被限制. `msElapsed` 财务报告和审定财务报表 `meta.rtf` 覆盖 解码只工作,不下载,加载,音频解码或等待音频.

### 重量镜像

设定 `weightsBaseUrl` 服务于您所在的检查站:

```ts
await preloadVoice({
    weightsBaseUrl: "https://models.example.com",
});
```

镜像保持了"拥抱相貌"的布局: `<base>/<repo>/resolve/main/<file>`读取GGUF的重量 `handy-computer` 仓库和文本文件 `openai` 存储器. 支助 `Range` 请求允许可重复的平行下载.

## 语音文本

语音库有两个48千赫的声音. 两者都使用MOSS-TTS-Nano 100M和克隆 被捆绑的参考代码,因此不下载参考记录. 每个声音 第一次使用大约需要133 MB 。 已经捆绑了 16 kHz 预览片段 .

| 语音 | 编号 | 型号 | 产出 |
| --- | --- | --- | --- |
| 妇女 | `VoiceId.Female` | 最低业务安全标准-TTS-Nano 100M | 48千赫兹 |
| 男性 | `VoiceId.Male` | 最低业务安全标准-TTS-Nano 100M | 48千赫兹 |

文本本身选择了20种最低业务安全标准语言之一:阿拉伯文、中文、捷克文、, 丹麦语、英语、法语、德语、希腊语、希伯来语、匈牙利语、意大利语、日语, 朝鲜语、波斯语、波兰语、葡萄牙语、俄语、西班牙语、瑞典语和土耳其语.

```ts
import {
    VoiceId,
    getVoiceSample,
    isVoiceCached,
    listVoices,
    loadVoice,
    removeVoice,
    synthesize,
} from "@degreesign/voice";

const voices = listVoices();
const sample = getVoiceSample(VoiceId.Female);
console.log(voices.map((voice) => voice.label), sample.sampleRate);

if (!(await isVoiceCached(VoiceId.Female))) {
    await loadVoice({
        voice: VoiceId.Female,
        onProgress: ({ phase, ratio }) => console.log(phase, ratio),
    });
}

const audio = await synthesize({
    voice: VoiceId.Female,
    text: "Hello from @degreesign/voice.",
});
// audio.pcm is mono Float32 at audio.sampleRate.

await removeVoice(VoiceId.Female);
```

| 函数 | 说明 |
| --- | --- |
| `listVoices()` | 每一个语音谱,按照库序. |
| `getVoiceSpec(voice)` | 一个带有文件、许可证和预览行的光谱 . |
| `getVoiceSample(voice)` | 被捆绑的WAV字节和剪辑率. |
| `isVoiceCached(voice)` | 每个语音文件被存储时为真 . |
| `loadVoice(options)` | 下载语音文件 。 接受 `weightsBaseUrl`。 。 。 . |
| `prepareVoice(options)` | 下载并解析不说话的声音 . |
| `synthesize(options)` | 文本和返回 `VoiceAudio`。 。 。 . |
| `removeVoice(voice)` | 删除已缓存的声音文件 . |

`synthesize` 接受可选 `pitch` 以半音为单位, `rate` 线性 `gain`。 。 。 . 皮奇和速率在合成后适用于每个语音. 最低业务安全标准的声音 接受 `seed` 财务报告和审定财务报表 `temperature`。增益默认值为 2, 投出值为 0 和 比率 对一个。 解析后重量保持不变,直到另一个声音取代它们.

## 语音克隆

`cloneVoice` 记录浏览器麦克风3秒钟并编码 使用最低业务安全标准音频显示器录制。 第一次通话下载45MB 编码器,然后保持它居住.

```ts
import { cloneVoice, synthesize, VoiceId } from "@degreesign/voice";

const clone = await cloneVoice({ durationMs: 3000 });
const audio = await synthesize({
    voice: VoiceId.Female,
    text: "This is the recorded voice.",
    reference: clone.codes,
});
```

A 类 `VoiceClone` 持有 `codes`,帧数和原生48千赫速率. 存储 在页面上重新使用同一声音而不再次录制的代码 :

```ts
const audio = await synthesize({
    voice: VoiceId.Male,
    text: "The stored reference still speaks.",
    reference: clone.codes,
});
```

过 `pcm` 与 `sampleRate` 以编码您已经拥有的录音。 这个 编码器再被复制到48千赫并保持了最多4秒. 简称 超过一秒钟被否决. `onProgress` 遵循编码器下载.

## 拼写

`@degreesign/voice/dictation` 是用于直播麦克风的无头控制器 相会. 它拥有工人,捕捉,暂停状态,模型进步和部分 语句。 该页保留了自己的标记和副本.

复制页面旁边的预建工人,或者从同一个来源路径为它服务:

```bash
cp node_modules/@degreesign/voice/dist/browser/dictation.worker.js \
  public/dictation.worker.js
```

```ts
import {
    createDictation,
    DictationState,
    Language,
} from "@degreesign/voice/dictation";

const dictation = createDictation({
    workerUrl: "/dictation.worker.js",
    language: Language.en,
    onState: (state, { modelReady, ratio }) => {
        status.textContent = state === DictationState.recording && modelReady
            ? "Listening"
            : `${state} ${Math.round(ratio * 100)}%`;
    },
    onText: (text) => {
        input.value = text;
    },
    onError: ({ source, message }) => console.error(source, message),
});

micButton.onclick = () => void dictation.start();
pauseButton.onclick = () => dictation.togglePause();
doneButton.onclick = () => void dictation.finish();
cancelButton.onclick = () => dictation.cancel();
```

主要选项是: `workerUrl` 或者说 `workerFactory`, (中文(简体) ), `model`, (中文(简体) ), `language`, (中文(简体) ), `quality`, (中文(简体) ), `threads`, (中文(简体) ), `timestamps`, (中文(简体) ), `updateIntervalMs`, (中文(简体) ), `partialIntervalMs`, (中文(简体) ), `onState`, (中文(简体) ), `onText`, (中文(简体) ), `onFrequency`, (中文(简体) ), `onError` 和高级 `capture` 超过。 一个控制器属于一个输入或组件. 主计长: 页面共享一个工人,从一个开始取消活动的工人。 取消发送 `onText("", true)` 这样页面就可以恢复其基础文本.

各州是 `idle`, (中文(简体) ), `requesting`, (中文(简体) ), `recording`, (中文(简体) ), `paused`, (中文(简体) ), `loading` 财务报告和审定财务报表 `working`。控制器的方法是 `start`, (中文(简体) ), `pause`, (中文(简体) ), `resume`, (中文(简体) ), `togglePause`, (中文(简体) ), `finish`, (中文(简体) ), `cancel`, (中文(简体) ), `reset`, (中文(简体) ), `active`, (中文(简体) ), `state` 财务报告和审定财务报表 `destroy`。 。 。 .

## 演示

打开 [现场演示](https://degreesign.github.io/ds_voice/) 尝试 在安装前在浏览器中双向移动。 装入 `@degreesign/voice` 从jsDelivr 并让你:

-   从麦克风录音或选取音频文件并阅读记录稿.
-   选一出出声,调音投出,收分,收分,温度和种子,再听.
-   记录一个引用,用被克隆的声音来表达文字.

语音演示为文本使用 `Quality.Low`,59MB下载. 演示 来源是 [文件/索引.html](https://npmcn.com/package/%40degreesign/voice/docs/index.html)运行 `node test/example/serve.cjs`,然后打开 `http://127.0.0.1:17544/docs/index.html` 以服务当地.

## 模型

| 编号 | 检查站 | 语文 |
| --- | --- | --- |
| `ModelId.WhisperBase` | 华声基地 | 多语种 |
| `ModelId.WhisperBase` + 键 `Language.en` | 耳语基础.en | 联合国 |

低语基数使用 `handy-computer/whisper-base-gguf` 与 `openai/whisper-base` 文本文件。 英国检查站使用 `handy-computer/whisper-base.en-gguf` 与 `openai/whisper-base.en`两种份额 一个 `ModelId`,一个使用记录和一个 `meta.model`。 。 。 .

重量公布为F16,Q8 0和Q4 K M. `Quality.High` 默认值.

| `Quality` | 重量 | 华声基地 | 耳语基础.en |
| --- | --- | --- | --- |
| `High` | F16 导弹 | 151 甲基溴 | 151 甲基溴 |
| `Medium` | 问题8 0 | 85 MB 设备 | 85 MB 设备 |
| `Low` | 问题4 K M | 59 MB (英语) | 59 MB (英语) |

被量化的文件在第一次访问时被分解为F32. 内核是 所以质量会改变下载的大小 和第一次访问的成本, 而不是稳定状态解码路径.

## 储存和性能

节点.js 存储模型文件通过 `@degreesign/cache` 下级 `~/.cache/decoder`。浏览器将其存储于索引数据库 `@degreesign/storage`。 。 。 .

重量作为4个米B块存储,其中包含一个清单,文本文件为JSON,以及 `usage.json` 跟踪磁盘预算的大小和最后使用。 下载使用四个 平行 `Range` 从存储块中请求并恢复 。 失败块是 在整个文件回归到一流之前,通过备份重新进行了测试.

`allowedDiskSpaceMB` 封盖存储模型字节并默认为512. 一个模型 已经缓存 .

该图以WebAssembly SIMD内核运行在CPU上. `threads` 默认为 `ThreadCount.Four`。浏览器需要交叉原产地隔离 `Cross-Origin-Opener-Policy: same-origin` 财务报告和审定财务报表 `Cross-Origin-Embedder-Policy: require-corp` 使用工人池;无 引擎使用单一线程路径。 F32收发机缓存 默认检查站一次; `weightCacheMB` 下盖.

## 建筑

承诺地图 [文件/档案.html](https://npmcn.com/package/%40degreesign/voice/docs/architecture.html) 显示 档案和发挥乐队的作用,从公众进入到模范家庭, 百度运行时间,平台商店和音频输入. 离线了 HTML文件. 直接打开并用面板追踪一个电话.

## 许可证发放

这个寄存器的运行时间代码是MIT许可的. 轻声的重量和象征 数据为Apache-2.0. 最低业务安全标准TTS权重、指示器和参考码是 阿帕奇2.0 (英语). 捆绑的 MP3 解码器是 CC0 和 `minimp3-wasm` 约束是 阿帕奇2.0 (英语). 见 [第三个](https://npmcn.com/package/%40degreesign/voice/THIRD_PARTIES.md) 财务报告和审定财务报表 [自由主义](https://npmcn.com/package/%40degreesign/voice/LICENSE)。 。 。 .

## 常见问题

### @degreesign/voice 是什么？

网络和节点的线下拼写、文字到文字和文字到语音\(TTS\)

### 如何安装 @degreesign/voice？

在项目目录运行 npm install @degreesign/voice，或使用 pnpm add / yarn add / bun add。

### @degreesign/voice 支持 TypeScript 吗？

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

### @degreesign/voice 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @degreesign/voice 需要什么版本的 Node\.js？

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

### @degreesign/voice 可以商用吗？

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

### @degreesign/voice 的下载量有多少？

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

### @degreesign/voice 还在维护吗？

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