# @hanzo/voice 中文文档

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

版本：0\.1\.19
npm 元数据更新时间：2026-10-20T19:55:08.418Z
中文译文更新时间：2026-11-17T08:35:04.330Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：198 kB，51 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react \>=18
- 首次发布：2026-07-27T02:18:59.511Z
- 最新版本发布：2026-10-20T19:55:08.121Z
- 近 30 天下载量：10263（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 20 个）

## 中文简介

作曲家的双向声音——开口麦克风,现场录音稿,口头回答,出门出道,还有口语插座. 一个机器和一个按钮,每个汉藏地表共享.

## 安装

```sh
npm install @hanzo/voice
```

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

## README

# @hanzo/语音

作曲家的双向语音. 一台机器,一个按钮,共享 hanzo.chat和hanzo.app. (英语).

点击麦克风和麦克风继续打开:记录片流入 作曲家听到的,每次暂停 都会通过作曲家自己的转弯 提交路径,并大声读回回复。 说回话就停了 这样你就可以转一圈了 再次点击结束对话 .

```bash
npm i @hanzo/voice
```

## 使用

打电话者保留机器——它需要 `say` 来读取回复——和按钮 只画它.

```tsx
import { Voice, useVoice, speech } from "@hanzo/voice";

const platform = speech({ token: () => iam.getValidAccessToken() });

function Composer() {
  const [text, setText] = useState("");
  const voice = useVoice({
    speech: platform,
    onPartial: setText,                 // heard so far — show it
    onUtterance: (said) => submit(said), // the EXISTING submit path
  });

  // Read the reply back, but only inside a conversation.
  useEffect(() => { if (done) void voice.say(reply); }, [done]);

  return (
    <form onSubmit={...}>
      <textarea value={text} onChange={...} />
      <Voice voice={voice} className="my-composer-icon" />
    </form>
  );
}
```

`onUtterance` 是故意的 作曲家现有的提交。 声音是一种方式 打字,从不以第二次方式发送.

作曲家只应该DICTATE——人物读回并发送—— 差数 `useDictation` 换句话说 每句话,在田稼之后, 因此,暂停永远不会取代它面前的句子:

```tsx
const voice = useVoice({ speech: platform, ...useDictation(text, setText) });
```

一个对话属于页面,而不是属于绘制它的组件. 发送 初回转弯就是聊天的空想 `/c/new` 页:1 `/c/<id>`, (中文(简体) ), 重新装上作曲家——所以机器把麦克风取回 另一边 只点击结束对话 。 新的页面负载总是开始 关闭.

## 用什么来着

平台本身的语音服务—— `POST /v1/audio/transcriptions` 财务报告和审定财务报表 `POST /v1/audio/speech` 在半藏网关上, 既与OpenAI兼容, 也与Metro兼容. `speech()` 建造这种运输;以自己的路向前的地表 代理通过自己的 `baseUrl` 其它一切都不会改变.

韩佐自己的收音机无论配置在哪里,浏览器都可以监听 每个浏览器 不只是缺少识别器 这个 浏览器自己的识别器是备用:

|  | 听着 | 实时部分 |
| --- | --- | --- |
| `speech` 已提供( 默认) | 汉佐的 `/v1/audio/transcriptions` | 整个短语到达 |
| 没有 `speech`,或 `prefer: "browser"` | 内置识别器 | 是,逐个字 |
| 半藏的转写拒绝了 | 内在识别器,从那一刻起 | 是,逐个字 |

答复由半藏语音读取 `speech.speak` 由 浏览器自己的声音当它不是——而"不是"包括"被重播".

两条腿都握有回声失效的捕捉流,只要是开口. 没有它,麦克风听到 回答从发言者 每次都会打断自己.

## 当它拒绝时

被拒绝的服务永远不会被吞噬。 401,空余额或超时 在麦克风后或回复后设置一个 `refusal` 打开 机器在同一时刻:

```ts
voice.refusal // { service: "ear" | "mouth", error, covered } | null
```

一张没有签名的纸 `speech({ public: true })`: 复制打开 `POST /v1/audio/transcriptions/public`半藏的手抄本没有 证明书,每个访客一天之内一次录音一分钟. 过了一天 拒绝使用 `public_allowance_spent`,浏览器的识别器接管 标签上写着自由日被使用. 不提供阅读声音或现场记录 那里;答复由浏览器读取.

`covered` 是指浏览器是否能够站入. `<Voice/>` 带句子 标签和标记本身 `data-refusal`; 表面绘制自己的按钮 读取 `voice.refusal` 或获取 `onRefusal`静静地站着会让 死钥匙听起来就像活生生的, 没有人去寻找一个法案 改为零.

## 当它不能

`voice.blocked` 这是其中之一 `insecure`, (中文(简体) ), `unsupported`, (中文(简体) ), `denied`, (中文(简体) ), `absent`,以及 `voice.reason` 是一个可以执行的判决。 扣子停放, 禁用, 带着这个理由——作曲家仍然会打字. 一个安静的控制 消失后不教用户什么.

## 谈话模式

关于半藏实时插座的无手对话, `/v1/voice`页:1 麦克风流出,回声流回声 与它的词旁 说到答复就停止了 服务器决定何时转弯结束 .

```tsx
import { Voice, useTalk } from "@hanzo/voice";

const talk = useTalk({ token: () => iam.getValidAccessToken(), onDone: (reply) => log(reply) });
<Voice voice={talk} says={{ idle: "Start a conversation" }} />;
// talk.reply — the words being spoken
```

## 现场记录

随人们说话而增长的文字 `/v1/audio/transcript`。 。 。 . `onSettled` 获得 每一块不会改变; `onPartial` 得到一切,包括尾巴.

```tsx
import { Voice, speech, useTranscript } from "@hanzo/voice";

const live = useTranscript({ speech: speech({ token }), onSettled: (text) => note(text), onPartial: setCaption });
<Voice voice={live} says={{ idle: "Transcribe", listening: "Transcribing — click to stop" }} />;
```

## API 密码

-   `useVoice({ onUtterance, onPartial?, onLevel?, speech?, prefer?, onRefusal?, voice?, language?, pause? })` 机器: `state` (单位:千美元)`idle` | `listening` | `speaking`, (中文(简体) ), `open`, (中文(简体) ), `blocked`, (中文(简体) ), `reason`, (中文(简体) ), `refusal`, (中文(简体) ), `toggle()`, (中文(简体) ), `say(text, voice?)` (解决办法) `true` 当 句子响了, `false` 当时,有人对他说:, `hush()`。 。 。 . `open` 是用户的 意图,单击时为真; `state` 正在发生的事情,它确实 不说 `listening` 直到麦克风真的存在 按钮读取 `aria-pressed` 关闭第一个和 `data-state` 关闭第二个.
-   `useDictation(value, setValue)` → `{ onPartial, onUtterance }` 该附件 (一) 对有控制的字段说话; `dictation(read, write)` 同样的 a 字段反射不能坚持.
-   `<Voice voice={...} className? disabled? children? says? />` - 按钮,用于 这三台机器中的任何一台 未被设计所取代;提供铬.
-   `useTalk({ token?, baseUrl?, org?, onReply?, onDone?, onError? })` — 谈话模式 : 机器加起来 `reply`。 。 。 .
-   `useTranscript({ speech, language?, onPartial?, onSettled? })` - 现场直播 录音机.
-   `speech({ baseUrl?, token?, ear?, voice?, public?, fetch? })` ——站台运输. 拒绝掷出 `SpeechError` (单位:千美元)`status`, (中文(简体) ), `code`(三); `refused(refusal)` 这是 句子 `<Voice/>` 为所穿. `ear` 默认为 `zen-scribe`· ; `voice` 改为 `{ model: "zen-voice-mini", name: "af_heart", format: "mp3" }`。语音名称是语音服务本身的ID (单位:千美元)`af_heart`, (中文(简体) ), `am_michael`, (中文(简体) ), `bf_emma`, (中文(简体) ), `bm_george`(......) ; (......); `say(text, voice)` 单句名一.
-   `listen`, (中文(简体) ), `mouth`, (中文(简体) ), `capability`, (中文(简体) ), `blocker` - 碎片,如果你想要的话.

Apache-2.0 · [韩佐·艾](https://hanzo.ai/)

## 常见问题

### @hanzo/voice 是什么？

作曲家的双向声音——开口麦克风,现场录音稿,口头回答,出门出道,还有口语插座\. 一个机器和一个按钮,每个汉藏地表共享\.

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

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

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

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

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

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

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

@hanzo/voice 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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

