# @fonoster/voice 中文文档 规范地址：https://npmcn.com/package/%40fonoster/voice/ 版本：0\.61\.0 npm 元数据更新时间：2026-11-15T14:01:13.623Z 中文译文更新时间：2026-11-15T04:24:00.944Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40fonoster/voice 原文对照：https://npmcn.com/package/%40fonoster/voice/?lang=original 项目主页：https://github.com/fonoster/fonoster#readme 源码仓库：https://github.com/fonoster/fonoster ## 关键信息（来自 npm 元数据） - 包体积（解压后）：72 kB，17 个文件 - 模块格式：CommonJS - TypeScript 类型：包内自带 - 运行依赖：3 个 - 首次发布：2021-11-01T01:13:04.715Z - 最新版本发布：2026-11-15T14:01:13.247Z - 近 30 天下载量：8971（2026-10-15 至 2026-11-13，npm 官方下载统计） - 已发布版本数：334（近 12 个月 70 个） ## 中文简介 长老会语音应用程序的会话 SDK ## 安装 ```sh npm install @fonoster/voice ``` 也可以使用：`pnpm add @fonoster/voice`、`yarn add @fonoster/voice`、`bun add @fonoster/voice` ## README # 语音 [![Voice](https://img.shields.io/badge/voice-api-brightgreen.svg)](https://fonoster.com/) [![Version](https://img.shields.io/npm/v/@fonoster/voice.svg)](https://npmjs.org/package/@fonoster/voice) [![Downloads/week](https://img.shields.io/npm/dw/@fonoster/voice.svg)](https://npmjs.org/package/@fonoster/voice) [![License](https://img.shields.io/npm/l/@fonoster/voice.svg)](https://github.com/fonoster/fonoster/blob/main/package.json) 长老会语音应用的SDK会话. 每一次电话,长老会的Appbridge 打开一个签名的 WebSocket **第二届会议** 给您的应用程序; `VoiceServer` 接受并运行您的处理器 与届会。 协议在 `docs/session-protocol.md`,完整的 SDK 向导在 `docs/voice-sdk.md`示例 `examples/`。 。 。 . - [安装](https://npmcn.com/package/%40fonoster/voice/#readme-installation) - [示例](https://npmcn.com/package/%40fonoster/voice/#readme-example) - [会议](https://npmcn.com/package/%40fonoster/voice/#readme-the-session) ## 安装 ```sh-session $ npm install --save @fonoster/voice ``` ## 示例 ```typescript import { VoiceServer } from "@fonoster/voice"; // AppBridge signs every connection with the app's signing secret. new VoiceServer({ port: 3000, signingSecret: process.env.APP_SIGNING_SECRET }).listen( async (session) => { await session.say("Hi there! What's your name?"); const { speech: name } = await session.gather(); await session.say(`Nice to meet you ${name}!`); await session.say("Please enter your 4 digit pin."); const { digits } = await session.gather({ maxDigits: 4, finishOnKey: "#" }); await session.say(`Your pin is ${digits}`); await session.hangup(); } ); ``` `attach(server, handler)` 在已有的 HTTP 或 Express 服务器上挂载同一服务器 . ## 会议 | 方法 | 对 | | --- | --- | | `say(text | asyncIterable, options?)` | 发声; 决定 `{ interrupted, heardText, heardMs }` | | `gather(options?)` | 等待演讲或按键`maxDigits`, (中文(简体) ), `finishOnKey`, (中文(简体) ), `timeout`(中文(简体) ) | | `play(url)`, (中文(简体) ), `playDtmf(digits)` | 播放媒体或 DTMF 声调 | | `transfer(to, { mode })`, (中文(简体) ), `completeTransfer()` | 冷,温暖或 `refer` 转让 | | `hold()`, (中文(简体) ), `resume()`, (中文(简体) ), `handoff(app, payload)`, (中文(简体) ), `hangup()` | 调用控制 | | `audio.onFrame`, (中文(简体) ), `audio.send`, (中文(简体) ), `audio.mark`, (中文(简体) ), `audio.clear` | 原始调用音频 | | `on(event, cb)`, (中文(简体) ), `subscribe(events)` | 转弯、部分记录、按键 | 字段 : `callRef`, (中文(简体) ), `appRef`, (中文(简体) ), `from`, (中文(简体) ), `to`, (中文(简体) ), `direction`, (中文(简体) ), `metadata`。 。 。 . 来自gRPC SDK(英语:`(req, res)` 处理者, `VoiceResponse`, (中文(简体) ), `stream`, (中文(简体) ), `sgather`, (中文(简体) ), `dial`{\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你觉得呢? 这些不见了,看 `docs/migrating-to-sessions.md`。 。 。 . `@fonoster/voice/session` 决心 软件包,再放一次. ## 会议 一通电话的会话以fonost.session.v1消息(voice-sdk S8)为基础. 动词是 方便:每个都发出一个命令,并解答事件. **仁爱**: 全球类 - [会议](https://npmcn.com/package/%40fonoster/voice/#readme-Session) - [中转](https://npmcn.com/package/%40fonoster/voice/#readme-Session+midTurn) - [转换已过期](https://npmcn.com/package/%40fonoster/voice/#readme-Session+turnExpired) - [.say () (中文(简体) )](https://npmcn.com/package/%40fonoster/voice/#readme-Session+say) - [stopSay () (中文(简体) )](https://npmcn.com/package/%40fonoster/voice/#readme-Session+stopSay) - [.gather () (中文(简体) )](https://npmcn.com/package/%40fonoster/voice/#readme-Session+gather) - [. listen () (中文(简体) )](https://npmcn.com/package/%40fonoster/voice/#readme-Session+listen) - [。订阅()](https://npmcn.com/package/%40fonoster/voice/#readme-Session+subscribe) - [. 转让()](https://npmcn.com/package/%40fonoster/voice/#readme-Session+transfer) - [. 完成传输()](https://npmcn.com/package/%40fonoster/voice/#readme-Session+completeTransfer) - [手势( )](https://npmcn.com/package/%40fonoster/voice/#readme-Session+handoff) - [挂起( )](https://npmcn.com/package/%40fonoster/voice/#readme-Session+hangup) - [. 注释()](https://npmcn.com/package/%40fonoster/voice/#readme-Session+note) - [.报告Usage()](https://npmcn.com/package/%40fonoster/voice/#readme-Session+reportUsage) - [. 答案( )](https://npmcn.com/package/%40fonoster/voice/#readme-Session+answer) - [收到( )](https://npmcn.com/package/%40fonoster/voice/#readme-Session+receive) - [已关闭( )](https://npmcn.com/package/%40fonoster/voice/#readme-Session+closed) - [命令( )](https://npmcn.com/package/%40fonoster/voice/#readme-Session+command) - [.bargeIn () (中文(简体) )](https://npmcn.com/package/%40fonoster/voice/#readme-Session+bargeIn) ### 中间 呼叫者是中转:一个转弯. user 开始没有转弯. 已定. **仁爱**: 实例财产 [`Session`](https://npmcn.com/package/%40fonoster/voice/#readme-Session) ### 会话 一次集会放弃了目前的转折;其后转折. 已取消,而不是缓冲. **仁爱**: 实例财产 [`Session`](https://npmcn.com/package/%40fonoster/voice/#readme-Session) ### say( ) 讲出文字,或一流的文字片段作为单词,并报告所听到的. **仁爱**: 实例方法 [`Session`](https://npmcn.com/package/%40fonoster/voice/#readme-Session) ### 语句。 stopSay () 切断代理: 每个待决的语句和播放解析作为中断 . **仁爱**: 实例方法 [`Session`](https://npmcn.com/package/%40fonoster/voice/#readme-Session) ### 会话.gather () 等待发言(turn.dested)或数字(dtmf),以先到者为准. **仁爱**: 实例方法 [`Session`](https://npmcn.com/package/%40fonoster/voice/#readme-Session) ### 届会。 listen () 开始聆听或改变 AppBridge 如何聆听(`listen.update`: 识别语言, 暗示和坚忍`low`, (中文(简体) ), `normal` 或者说 `high`) (中文(简体) ). **仁爱**: 实例方法 [`Session`](https://npmcn.com/package/%40fonoster/voice/#readme-Session) ### 会话. 订阅() 请求选入事件:"turn.present","transcript.". **仁爱**: 实例方法 [`Session`](https://npmcn.com/package/%40fonoster/voice/#readme-Session) ### 转移() 调用; 当 AppBridge 结束会话时, 以 理由 调用 . **仁爱**: 实例方法 [`Session`](https://npmcn.com/package/%40fonoster/voice/#readme-Session) ### 交接器( ) 完成待定的取暖转移:代理机离开,呼叫机和新方停留. 决定: 当会话以理由转移结束时; 用会话错误拒绝 (单位:千美元)`transfer_not_answered`),当新党尚未答复,这就留下了转移 待决:等待 `transfer.answered` {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}再打个电话 {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}我记得. **仁爱**: 实例方法 [`Session`](https://npmcn.com/package/%40fonoster/voice/#readme-Session) ### 页 次 用有效载荷将电话交给另一个应用程序;当本届会议结束时,就决定了. **仁爱**: 实例方法 [`Session`](https://npmcn.com/package/%40fonoster/voice/#readme-Session) ### 挂起( ) 挂起; 会话结束后决定 . `failure` 结束调用为调用记录失败 (@ 内部: 留给长老会自己的应用( Autopilot); AppBridge 忽略了他人的应用). **仁爱**: 实例方法 [`Session`](https://npmcn.com/package/%40fonoster/voice/#readme-Session) ### 页:1 在呼叫记录中添加一个注释(record.note). **仁爱**: 实例方法 [`Session`](https://npmcn.com/package/%40fonoster/voice/#readme-Session) **内部**: 为长老会自己的应用软件(Autopilot)预留;不是公共SDK的一部分,可能改变. ### 页:1 将模型符号用法添加到调用中(usage.report, add-usage-metering). **仁爱**: 实例方法 [`Session`](https://npmcn.com/package/%40fonoster/voice/#readme-Session) **内部**:预留给长老会自己的"自动驾驶";AppBridge拒绝其他应用. ### 答题( ) 即刻决定:AppBridge响应连接(voice-sdk S2)的呼叫. **仁爱**: 实例方法 [`Session`](https://npmcn.com/package/%40fonoster/voice/#readme-Session) ### 收到( ) 从套接字中提供一个框架. **仁爱**: 实例方法 [`Session`](https://npmcn.com/package/%40fonoster/voice/#readme-Session) ### 会议闭幕() 插座关了. **仁爱**: 实例方法 [`Session`](https://npmcn.com/package/%40fonoster/voice/#readme-Session) ### 会话. command () 发送唯一答案为可能错误的命令( 以会话错误记录) . **仁爱**: 实例方法 [`Session`](https://npmcn.com/package/%40fonoster/voice/#readme-Session) ### 语法 应用程序拥有中断( appbridge B22) : 当呼叫者开始谈论中断时 说或玩,SDK以清晰的方式切断它;一个无间断的不断播放. **仁爱**: 实例方法 [`Session`](https://npmcn.com/package/%40fonoster/voice/#readme-Session) ## 语音服务员 接受通过 WebSocket 的 Appbridge 会话并运行每次会话的处理器 (voice-sdk,"VoiceServer通过WebSocket接受AppBridge会话"). **仁爱**: 全球类 - [语音服务员](https://npmcn.com/package/%40fonoster/voice/#readme-VoiceServer) - [. listen () (中文(简体) )](https://npmcn.com/package/%40fonoster/voice/#readme-VoiceServer+listen) - [.attach () (中文(简体) )](https://npmcn.com/package/%40fonoster/voice/#readme-VoiceServer+attach) - [手提式升级( )](https://npmcn.com/package/%40fonoster/voice/#readme-VoiceServer+handleUpgrade) ### 语音服务器. listen () 启动独立的服务器。 决心一旦它听. **仁爱**: 实例方法 [`VoiceServer`](https://npmcn.com/package/%40fonoster/voice/#readme-VoiceServer) ### 语音服务器. attach () 挂载在 HTTP 服务器上的挂载( 包括 Express): 会话到达 `path`。 。 。 . **仁爱**: 实例方法 [`VoiceServer`](https://npmcn.com/package/%40fonoster/voice/#readme-VoiceServer) ### 语音服务器. handle Update () 处理一个升级请求:验证签名,然后运行会话. **仁爱**: 实例方法 [`VoiceServer`](https://npmcn.com/package/%40fonoster/voice/#readme-VoiceServer) ## 会话错误 命令失败: AppBridge 已发送 `error` 与 `relatesTo` 设置到命令的id. **仁爱**: 全球类 ## 会话结束错误 会话在命令待决时结束(或致命错误已到来). **仁爱**: 全球类 ## 常见问题 ### @fonoster/voice 是什么？ 长老会语音应用程序的会话 SDK ### 如何安装 @fonoster/voice？ 在项目目录运行 npm install @fonoster/voice，或使用 pnpm add / yarn add / bun add。 ### @fonoster/voice 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @fonoster/voice 支持 ESM 还是 CommonJS？ 以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。 ### @fonoster/voice 可以商用吗？ @fonoster/voice 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @fonoster/voice 的下载量有多少？ 根据 npm 官方下载统计，@fonoster/voice 在 2026/10/15 – 2026/11/13 这 30 天内被下载 8,971 次，日均约 299 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @fonoster/voice 还在维护吗？ 最新版本 0\.61\.0 发布于 2026/11/15（今天）；至今共发布 334 个版本，其中过去 12 个月发布了 70 个；首次发布于 2021/11/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。