Kilo 语音转文字Voice Transcription完整指南从 FFmpeg 配置到模型选择与快捷录音【免费下载链接】kilocodeKilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kilocodeKilo 是面向工程场景的一体化 AI 编码代理平台其语音转文字Voice Transcription功能允许你在提示词输入框中直接用语音代替打字并通过 Kilo Gateway 与已登录的 Kilo 账号完成音频转录。本文将以官方文档为主线结合packages/kilo-vscode中的语音转文字源码实现完整讲解环境准备、账号登录、转录模型选择、录音操作与快捷方式、底层调用链路以及常见问题的排查方法帮助你快速上手并理解该功能的工作机制。环境准备语音输入需要满足两个前置条件本机安装 FFmpeg用于音频捕获与处理以及能够访问 Kilo provider用于转录。安装 FFmpegFFmpeg 是音频捕获和处理所必需的工具请根据你的平台安装macOSbrew install ffmpegLinuxUbuntu/Debiansudo apt update sudo apt install ffmpegWindows从 ffmpeg.org/download.html 下载对应的构建版本并将解压后的bin目录添加到系统 PATH 环境变量中。登录 Kilo 账号启用并登录 Kilo provider 后提示词输入框中才会出现麦克风按钮。所有转录请求都会通过 Kilo Gateway 使用你的 Kilo 账号额度因此无需单独配置 OpenAI provider 配置文件或 API Key。从源码看麦克风按钮的出现与否由 availability.ts 中的hasSpeechToTextAccess决定其判定条件包括Kilo provider 未被禁用enabled_providers/disabled_providers、且当前鉴权状态为api或oauth即已登录export function hasSpeechToTextAccess(cfg: Cfg, auth: ReadonlyRecordstring, AuthState): boolean { const enabled !cfg.enabled_providers || cfg.enabled_providers.includes(KILO_PROVIDER_ID) const type auth[KILO_PROVIDER_ID] return enabled !cfg.disabled_providers?.includes(KILO_PROVIDER_ID) (type api || type oauth) }文件路径packages/kilo-vscode/webview-ui/src/components/speech-to-text/availability.ts选择转录模型你可以在SettingsModelsSpeech to Text Model中按需选择转录模型。Kilo 会将该选择以experimental.speech_to_text_model字段的形式存入全局 Kilo CLI 配置文件~/.config/kilo/kilo.jsonc。该配置字段在 config.ts 中被定义为可选的字符串类型Schema.optional(Schema.String)属于experimental配置分组。模型列表由 Kilo Gateway 动态发现并下发反映你的账号或组织可用的转录模型因此新增的模型会自动出现在列表中无需手动升级或配置。内置转录模型目录虽然运行时模型列表以 Gateway 下发的目录为准但 models.ts 中内置了一份默认模型目录作为网关目录不可用时的兜底与默认选项模型 ID名称Provider特点nvidia/parakeet-tdt-0.6b-v3Parakeet TDT 0.6B v3NVIDIA默认模型DEFAULT_SPEECH_TO_TEXT_MODELopenai/whisper-large-v3-turboWhisper Large V3 TurboOpenAI-compatible—openai/gpt-4o-mini-transcribeGPT-4o Mini TranscribeOpenAIverbatim: true逐字转录openai/gpt-4o-transcribeGPT-4o TranscribeOpenAIverbatim: true逐字转录openai/whisper-1Whisper 1OpenAI—openai/whisper-large-v3Whisper Large V3OpenAI-compatible—google/chirp-3Chirp 3Google—其中带verbatim标志的模型会启用逐字转录提示词见下文底层原理其余模型默认会做常规转写。模型选择的判定逻辑availability.ts 中的selectedSpeechToTextModel负责解析用户选择优先读取配置cfg.experimental?.speech_to_text_model若该值不在已知模型目录中则回退到目录中的第一个模型最终兜底为内置默认模型export function selectedSpeechToTextModel( cfg: Cfg, models: readonly SpeechToTextModelDef[] SPEECH_TO_TEXT_MODELS, ): string { const id cfg.experimental?.speech_to_text_model return models.find((model) model.id id)?.id ?? models[0]?.id ?? DEFAULT_SPEECH_TO_TEXT_MODEL.id }模型目录的动态发现catalog.ts 展示了模型目录的获取方式扩展向本地后端发起GET /kilo/models/transcriptions请求携带 Basic 鉴权与directory查询参数随后解析返回的模型数组。每个模型只需包含id与name两个字段解析时会从name中拆分出 provider 与显示标签function toModel(model: CatalogModel): SpeechToTextModelDef { const index model.name.indexOf(:) const provider index -1 ? model.id.split(/, 1)[0] || Kilo Gateway : model.name.slice(0, index).trim() return { id: model.id, label: index -1 ? model.name : model.name.slice(index 1).trim(), provider, } }这就是新模型自动出现的底层机制——目录是动态拉取的而不是写死在客户端里。录制提示词登录并启用 Kilo provider 后提示词输入框中会出现麦克风按钮操作流程如下点击麦克风按钮开始录音清晰地朗读你的内容再次点击按钮停止录音语音会被转录为文本并插入输入框。键盘快捷方式Cmd/CtrlK当焦点位于 Kilo 提示词输入框或审查评论review comment输入框时可以使用Cmd/CtrlKmacOS 为⌘KWindows/Linux 为CtrlK控制录音轻点一下开始录音再轻点一次停止并转录按住说话按住的同时说话松开后自动转录并提交当前聚焦的输入框按住时长需超过 400ms 才会触发提交语义见下方源码转录过程中按键取消本次转录。快捷方式的判定逻辑在 shortcut.ts 中SPEECH_HOLD_MS 400定义了按住并提交的阈值——若按下到松开的时间差大于等于 400ms松开时除了转录还会提交输入框submit event.timeStamp - current.time SPEECH_HOLD_MS。同时窗口失焦blur或页面隐藏visibilitychange时会自动放弃当前按键状态。录音状态机与实时反馈前端通过 useSpeechToText.ts 维护一个五态状态机idle→starting→recording→transcribing→error并据此驱动界面反馈录音过程中实时展示音频电平可视化audio level visualization直观反映音量大小内置语音活动检测voice activity detection, VAD自动识别你何时开始说话录制停止后进入transcribing状态转录结果通过speechToTextResult消息回调并插入输入框。前端还会将浏览器语言环境navigator.language的主语言标签如en、zh随录音请求一并传给后端用于指导转录。文件路径packages/kilo-vscode/webview-ui/src/components/speech-to-text/useSpeechToText.ts、packages/kilo-vscode/webview-ui/src/components/speech-to-text/shortcut.ts底层实现原理语音转文字功能分为两个阶段音频处理与转录请求。音频处理FFmpeg 捕获录音与音频捕获由扩展端extension host负责通过 FFmpeg 完成系统音频捕获与格式处理捕获到的音频以 base64 数据的形式交给转录环节见transcribe.ts中请求体的input_audio.data字段。若 FFmpeg 缺失或不在 PATH 中录音将无法正常启动这也是官方文档把 FFmpeg 列为硬性前置依赖的原因。转录请求经 Kilo Gateway 的调用链转录的核心实现在 transcribe.ts。整个调用链为扩展端向本地 Kilo 后端发起POST /kilo/audio/transcriptions请求使用kilo:${password}的 Basic 鉴权密码来自本地连接配置并携带directory查询参数请求体包含model模型 ID默认取getSpeechToTextModel的解析结果、input_audio.database64 音频与input_audio.format音频格式以及可选的language本地后端再通过 Kilo Gateway 将请求转发至所选转录模型完成实际转录响应中的text字段被取出并 trim 后作为转录结果返回前端插入输入框。值得注意的细节若所选模型带verbatim标志请求会附带如下逐字转录提示词PROMPT常量要求模型不润色、不概括、不改写Transcribe exactly what is spoken. Do not paraphrase, summarize, infer intent, or rewrite for clarity. Preserve the speakers original wording as closely as possible, including incomplete phrases and unusual wording when audible.错误处理与取消语义handler.ts 中通过AbortController、Mapstring, ...等结构按requestId管理每次录音/转录任务并定义了完整的错误码语义not_connected未连接到 Kilo 后端not_authenticatedHTTP 401登录状态失效前端会弹出登录提示useSpeechToText.ts中的login()会触发 Sign In 引导empty_transcript未检测到语音响应文本为空cancelled用户主动取消中止信号触发not_available网络不可达Failed to fetch。状态消息speechToTextStarted/speechToTextCancelled/speechToTextResult/speechToTextError通过 webview 与扩展端之间的消息通道传递由前端useSpeechToText统一消费。常见问题排查麦克风按钮不出现启用并登录 Kilo provider检查enabled_providers/disabled_providers配置以及登录状态参考 availability.ts 的判定条件核对配置。转录报错确认 Kilo provider 仍处于启用且已登录状态确认 FFmpeg 已安装且位于 PATH 中检查网络连接是否正常尝试更清晰地发音或调整麦克风设置转录准确性受音频质量与语音清晰度影响若提示未登录not_authenticated重新登录 Kilo 账号。已知限制语音转录存在以下约束使用前请留意需要稳定的网络连接需要通过 Kilo 账号访问 Kilo Gateway转录准确度取决于音频质量与发音清晰度录音/转录需要本机 FFmpeg 支持Linux 下还需系统具备音频捕获能力。参考与延伸官方功能文档packages/kilo-docs/pages/code-with-ai/features/speech-to-text.md配置字段定义packages/core/src/v1/config/config.tsexperimental.speech_to_text_model转录实现packages/kilo-vscode/src/speech-to-text/transcribe.ts任务状态管理packages/kilo-vscode/src/speech-to-text/handler.ts模型目录packages/kilo-vscode/src/speech-to-text/models.ts、packages/kilo-vscode/src/speech-to-text/catalog.ts前端交互packages/kilo-vscode/webview-ui/src/components/speech-to-text/useSpeechToText.ts、packages/kilo-vscode/webview-ui/src/components/speech-to-text/shortcut.ts可用性判定packages/kilo-vscode/webview-ui/src/components/speech-to-text/availability.ts相关测试用例packages/kilo-vscode/tests/unit/speech-to-text-availability.test.ts、packages/kilo-vscode/tests/unit/speech-to-text-capture.test.ts、packages/kilo-vscode/tests/unit/speech-to-text-catalog.test.ts、packages/kilo-vscode/tests/unit/speech-to-text-models-sync.test.ts、packages/kilo-vscode/tests/unit/use-speech-to-text.test.ts【免费下载链接】kilocodeKilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kilocode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考