@hanzo/voice

中文文档
0.1.19发布于 2026/10/21Apache-2.0TypeScriptES Module零依赖近 30 天下载 1万

Bidirectional voice for a composer — open mic, live transcript, spoken replies, barge-in, and a talk socket. One machine and one button, shared by every Hanzo surface.

原始使用文档
文档目录7 节
  1. Use
  2. What it uses
  3. When it refuses
  4. When it can't
  5. Talk mode
  6. Live transcript
  7. API

@hanzo/voice

Bidirectional voice for a composer. One machine, one button, shared by hanzo.chat and hanzo.app.

Click the mic and the microphone stays open: the transcript streams into the composer as it is heard, each pause sends a turn through the composer's own submit path, and the reply is read back aloud. Speak over the reply and it stops so you can take the next turn. Click again to end the conversation.

npm i @hanzo/voice

Use

The caller keeps the machine — it needs say to read the reply — and the button only draws it.

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 is deliberately the composer's existing submit. Voice is a way of typing, never a second way of sending.

A composer that should only DICTATE — the person reads it back and sends — spreads useDictation instead. Each utterance lands after what the field held, so a pause never replaces the sentence before it:

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

A conversation belongs to the page, not to the component drawing it. Sending the first turn is exactly what makes a chat surface swap /c/new for /c/<id>, remounting the composer — so the machine picks the microphone back up on the other side. Only a click ends a conversation. A fresh page load always starts closed.

What it uses

The platform's own speech services — POST /v1/audio/transcriptions and POST /v1/audio/speech on the Hanzo gateway, both OpenAI-compatible and metered. speech() builds that transport; a surface that fronts those paths with its own proxy passes its own baseUrl and nothing else changes.

Hanzo's own transcriber listens wherever it is configured and the browser can record for it — every browser, not only the ones missing a recogniser. The browser's own recogniser is the standby:

Listens withLive partials
speech supplied (the default)Hanzo's /v1/audio/transcriptionsthe phrase arrives whole
no speech, or prefer: "browser"the built-in recogniseryes, word by word
Hanzo's transcriber refusedthe built-in recogniser, from that momentyes, word by word

Replies are read by the Hanzo voice when speech.speak is supplied, and by the browser's own voice when it is not — and "is not" includes "refused".

Both legs hold an echo-cancelled capture stream for as long as they are open. Without it the microphone hears the reply coming out of the speakers and interrupts itself on every turn.

When it refuses

A refused service is never swallowed. A 401, an empty balance or a timeout puts the browser behind the microphone or behind the reply, and puts a refusal on the machine at the same moment:

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

A page with nobody signed in passes speech({ public: true }): transcription on POST /v1/audio/transcriptions/public, Hanzo's own transcriber with no credential, a minute of audio at a time within a day per visitor. Past the day it refuses with public_allowance_spent, the browser's recogniser takes over, and the label says the free day is used. No reading voice or live transcript is offered there; replies are read by the browser.

covered is whether the browser could stand in. <Voice/> wears the sentence in its label and marks itself data-refusal; a surface drawing its own button reads voice.refusal or takes onRefusal. Standing in quietly would make a dead key sound exactly like a live one, and nobody goes looking for a bill that reads zero.

When it can't

voice.blocked is one of insecure, unsupported, denied, absent, and voice.reason is a sentence a person can act on. The button stays put, disabled, wearing that reason — the composer still types. A control that quietly disappears teaches the user nothing.

Talk mode

A hands-free conversation on Hanzo's realtime socket, /v1/voice: the microphone streams up, the reply streams back as audio with its words beside it, and talking over the reply stops it. The server decides when a turn ends.

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

Live transcript

Text that grows as people speak, on /v1/audio/transcript. onSettled gets each piece once it will not change; onPartial gets everything, tail included.

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? }) → the machine: state (idle | listening | speaking), open, blocked, reason, refusal, toggle(), say(text, voice?) (resolves true when the sentence played out, false when it was spoken over or hushed), hush(). open is the user's intent, true from the click; state is what is actually happening, and it does not say listening until the microphone really is. The button reads aria-pressed off the first and data-state off the second.
  • useDictation(value, setValue) → { onPartial, onUtterance } that append each utterance to a controlled field; dictation(read, write) is the same for a field React does not hold.
  • <Voice voice={...} className? disabled? children? says? /> — the button, for any of the three machines. Unstyled by design; supply the chrome.
  • useTalk({ token?, baseUrl?, org?, onReply?, onDone?, onError? }) → talk mode: the machine plus reply.
  • useTranscript({ speech, language?, onPartial?, onSettled? }) → a live transcript machine.
  • speech({ baseUrl?, token?, ear?, voice?, public?, fetch? }) — the platform transport. A refusal throws SpeechError (status, code); refused(refusal) is the sentence <Voice/> wears for it. ear defaults to zen-scribe; voice to { model: "zen-voice-mini", name: "af_heart", format: "mp3" }. Voice names are the speech service's own ids (af_heart, am_michael, bf_emma, bm_george, …); say(text, voice) names one for a single sentence.
  • listen, mouth, capability, blocker — the pieces, if you want them.

Apache-2.0 · hanzo.ai

版本与发布记录

@hanzo/voice 共发布 20 个版本,首次发布于 2026/07/27;过去 12 个月发布了 20 个版本。

版本发布日期距今
0.1.19latest2026/10/2127 天前
0.1.182026/10/041 个月前
0.1.172026/10/041 个月前
0.1.162026/10/041 个月前
0.1.152026/10/041 个月前
0.1.142026/10/031 个月前

关于 @hanzo/voice 的常见问题

@hanzo/voice 是什么?

Bidirectional voice for a composer — open mic, live transcript, spoken replies, barge-in, and a talk socket. One machine and one button, shared by every Hanzo surface.

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