---
title: "Voice"
description: "使用本机或 Provider 转写引擎向 Composer 输入语音。"
image: "https://kxen.ai/og/integrations/voice.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://kxen.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Voice

Voice 把语音转成 Composer 文本。它只负责输入，不改变 Agent 权限或模型路由。

## 产品入口

Composer 中的麦克风按钮可以开始和停止语音输入。长按空格超过 400ms 也可以进入 PTT，松开后结束。

Settings 的语音区域用于配置引擎、fallback、locale 和转写模型。Composer 的麦克风菜单可以快速切换当前可用引擎。

## 引擎

- Apple Speech framework。
- OpenAI 兼容音频转写。
- xAI 音频转写。
- 声明 audio 能力的自定义 Provider。

Apple 引擎只在 macOS 桌面应用提供，只使用支持 on-device recognition 的本机识别器。Provider 引擎需要对应凭证和网络，并会把录音发送给实际选中的音频转写服务。

## Fallback

可以为首选引擎配置有序 fallback。首选引擎不可用时，kxen 依次尝试后续引擎，并在 Composer 显示实际使用的引擎。

当 Apple 是首选引擎时，把已配置凭证的 cloud Provider 加入 `voice.fallback` 还表示允许把本次录音发送给该 Provider，用云端终稿升级本机结果。仅仅保存 Provider 凭证不构成上传授权。`fallback` 为空时，Apple 录音不为云上传缓冲 PCM，也不会外发。

## 输入行为

转写 partial 会更新当前 Session 草稿。切换 Session 会停止旧会话录音，迟到终稿不会写入新 Session。

录音中直接发送时，Composer 先等待终稿合并，再发送完整文本。重复按 Enter 不会产生两次发送。

需要云转写的录音最多缓冲 5 分钟，同时受 PCM 样本数和 WAV 大小硬上限约束，以先达到者为准。超过上限时停止并拒绝上传；Apple 本机路径仍可保留已经得到的本地结果。

云端音频服务通常按时长而不是 token 计费。kxen 会在上传前持久化请求声明，完成或失败后把 token 计量标为 `UNKNOWN`，不会伪装成 `0/0`，也不会自动重发可能已经计费的录音。

## 系统权限

Apple 引擎需要麦克风和语音识别权限。权限未授予时，界面会给出 macOS 系统设置入口提示。

Source: https://kxen.ai/integrations/voice/index.mdx
