Configuration.zh CN

配置参考

English · 首页

用户配置是 ${XDG_CONFIG_HOME:-$HOME/.config}/voice-input/config.toml。安装后的公开示例位于 ~/.local/share/voice-input/config.toml。

查看解析后的有效配置；输出中不含 credential：

voice-input config
voice-input config --format json

编辑 TOML 后重新启动 daemon：

systemctl --user restart voice-input.service

按需启动的 Quickshell Settings 窗口会显示受支持的配置，并通过 Rust 保存经过完整验证的配置。Overview 汇总本地 service 和当前配置。Speech、Refinement、Output、Appearance 与 Hotkey & state 对日常选项进行分类；包含技术参数的页面会提供各自的可展开高级设置区域。选择对应 provider 后，Alibaba Realtime 或实验性 Audio3 设置会在 Speech 内显示。QML 本身不解析或写入 TOML。

Settings 保存模型

voice-input settings

Settings 通过带版本号的 NDJSON 与专用的 voice-input settings-backend --stdio child 通信，并由该 child 加载配置。同一个 child 会为 Overview 返回经过严格筛选的运行状态摘要；响应中不会包含 transcript、输出目标、任意 runtime error 或 credential。Rust 会返回一个与实际配置源绑定的不透明 revision。Save 会发送该 revision 和全部受支持字段；如果另一个编辑器已经修改原始内容，Rust 会拒绝过期的保存请求并要求用户重新加载，从而避免静默覆盖。

Rust 会把配置目录权限设为 0700，把 config.toml 权限设为 0600，再以原子方式替换文件。Save 还可以重启 voice-input.service；如果持久化已经成功，重启失败会单独报告。Credential field 只提供保留或替换操作，并在提交后清空。QML/JavaScript 只能尽力清理托管内存中的 string。

顶层字段与快捷键

字段	默认值	含义
state_file	"auto"	auto 使用 runtime state file。自定义路径会接收额外副本。disabled 只会关闭该可选副本；daemon 仍会维护 HUD 和 status 所需的 $XDG_RUNTIME_DIR/voice-input/state.json。
hotkey.accelerator	", F9"	生成主要开始/停止 binding 时使用的 Hyprland accelerator 文本，同时参与计算输出前等待时长。Daemon 本身不会注册全局快捷键。
hotkey.mode	"toggle"	可选 hold 或 toggle，用于决定生成的 F9 类开始/停止 binding。在 toggle 模式下，如果 accelerator 包含 modifier，输出前至少等待 500 ms。

安装的静态 Hyprland snippet 还会使用 F8 取消、使用 F10 丢弃并重新开始，同时保持 Omarchy 原有的 Super+Ctrl+X Voxtype 快捷键不变。可以运行 voice-input setup hyprland，根据当前配置生成 binding。

[audio]

字段	默认值	含义
device	"default"	PipeWire target。default 表示不向 pw-record 传递 --target；其他值会作为 target 传入。
sample_rate	16000	采集、WAV 和 ASR 的采样率，单位 Hz。Qwen session metadata 也使用该值。
max_duration_secs	300	独立采集和共享 pre-roll 采集路径都遵守的最长录音时长。达到上限后，程序会自动停止采集并开始最终处理，不会让 session 继续停留在录音状态。
partial_interval_ms	1500	本地 CLI 重复执行 partial transcription 前的 sleep 间隔。Qwen realtime partial 由事件驱动。
pre_roll_enabled	false	在 daemon 运行期间保持 pw-record 打开，并用环形缓冲区为新会话补入开头音频。该功能会影响麦克风隐私。
pre_roll_ms	500	期望保留的 pre-roll 时长。环形缓冲区还会至少保留 320 ms 的 capture warm-up。

[asr]

字段	默认值	可选值与行为
provider	"local-cli"	local-cli、alibaba-qwen-realtime，或需要明确开启 gate 的实验性 alibaba-qwen-audio3。
backend_command	"/usr/bin/voxtype"	用于本地 final/partial ASR 和远程 fallback 的可执行文件。参数依次包含可选的 --engine、可选的 --model，以及 --language CODE transcribe WAV。
engine	"sensevoice"	本地 backend engine。空字符串表示不传递 --engine。
model	""	本地 backend model。空字符串表示采用 backend 默认值，并且不传递 --model。
language	"simplified-chinese"	english、simplified-chinese、traditional-chinese、japanese 或 korean。发送给 ASR 的代码为 en、zh、ja、ko；中文随后通过 OpenCC 转换。
connect_timeout_ms	5000	Realtime TCP/WebSocket 连接 timeout，同时作为完整音频处理的 HTTP connect timeout。有效范围为 100–120,000 ms；Audio3 replacement connection 最多使用 5,000 ms。
finalize_timeout_ms	8000	请求 realtime provider 结束后的 deadline。有效范围为 100–120,000 ms。
fallback_to_local	true	Qwen 失败、返回空结果或实时音频流不完整时，允许使用完整录音调用本地 backend。部分 worker error 发生后仍可使用有效的 realtime transcript；如果实时传输反压导致远程音频流不完整，则绝不会使用该远程文本。

backend_command 有意明确设为 /usr/bin/voxtype。请保留绝对路径，避免递归调用 Voice Input。

[asr.alibaba]

字段	默认值	含义
endpoint	"wss://dashscope.aliyuncs.com/api-ws/v1/realtime"	Realtime WebSocket endpoint。如果 URL 中没有 model query parameter，客户端会自动附加。
model	"qwen3-asr-flash-realtime-2026-02-10"	Realtime Qwen model ID。
turn_mode	"server-vad"	server-vad 会发送 VAD 参数；manual 会关闭服务端 turn detection，并在停止时提交音频。
vad_threshold	0.2	不作修改地发送给 Qwen 的 Server VAD threshold。
silence_duration_ms	400	发送给 Qwen 的 Server VAD silence duration。
final_pass_enabled	false	通过 compatible HTTP chat-completions endpoint 重新识别完整 WAV。
final_pass_base_url	""	不含 /chat/completions 的 base URL。留空时，客户端可以从已知的中国、国际或美国 DashScope realtime host 推导 compatible-mode URL。自定义 realtime host 必须明确填写该字段。
final_pass_model	"qwen3-asr-flash-2026-02-10"	全音频 final model ID。
final_pass_timeout_ms	20000	Final pass 的 HTTP 整体请求 timeout。
final_pass_enable_itn	false	设置 Alibaba asr_options.enable_itn。ITN 指 inverse text normalization。

Alibaba key 不是 assets/config.toml 中的公开 TOML 字段。请按照 安全与隐私 的说明保存 alibaba-api-key credential。

[asr.alibaba_audio3]——实验性功能

Qwen-Audio-3 是需要用户明确选择的实验性功能。公开 sample 默认关闭它，voice-input setup model 也不会提供该选项，请勿把它视为稳定默认值。请在 Settings 中选择 alibaba-qwen-audio3，并在保存前确认独立的实验功能 gate。该 provider 与 Alibaba Realtime 共用 credential ID alibaba-api-key。

字段	默认值	含义
experimental_enabled	false	当 asr.provider = "alibaba-qwen-audio3" 时必须为 true；仅选择 provider 不会自动确认实验功能。
endpoint_mode	"regional"	regional 根据 region 使用经过审核的 canonical endpoint pair；custom 完全按原值使用 endpoint 和 native_endpoint。
region	"beijing"	可选 beijing 或 singapore。Regional 模式会用它同时选择两个 endpoint。
endpoint	"wss://dashscope.aliyuncs.com/api-ws/v1/inference"	Streaming WebSocket URL。只在 Custom 模式生效；Regional 模式会把它作为非活动数据保留。
model	"qwen-audio-3.0-asr-flash-streaming"	Streaming model ID。
language_hints_enabled	false	发送从 [asr].language 得到的提示：en、zh,en、ja,en 或 ko,en。关闭时保留 provider 自动检测。
heartbeat_enabled	false	在有效音频帧持续发送时，使长时间静音的 streaming push-to-talk session 保持连接。Native 请求不会发送该字段。
recognition_preset	"standard"	可选 standard、low-latency-dictation、long-form 或 custom；生效映射见下文。
max_sentence_silence_ms	800	Custom 最大句末静音时长。生效值必须在 200–6,000 ms 之间。Named preset 使用固定值，并将该 raw field 作为非活动数据保留。
semantic_punctuation_enabled	false	Custom 语义标点开关。Named preset 使用各自的固定映射。
multi_threshold_mode_enabled	false	Custom 多阈值模式开关。Named preset 使用各自的固定映射。
speech_noise_threshold	省略	可选的 Custom 有限阈值，范围为 -1 到 1。省略时不改变 provider 行为；named preset 不发送该值。
vocabulary	[]	由 { term, weight } entry 组成的全局动态词汇表。非空 list 会同时发送给 Streaming 和 Native。
native_endpoint	"https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation"	Native HTTP URL。只在 Custom 模式生效；Regional 模式会把它作为非活动数据保留。
native_model	"qwen-audio-3.0-asr-flash"	Native 完整音频 model ID。
native_final_pass_mode	"streaming-only"	可选 streaming-only、adaptive 或 always；具体 policy 见下文。
native_timeout_ms	20000	Native 整体 request timeout。运行范围为 100–120,000 ms；当配置的 policy 可以自动运行 Native 时，程序会验证该范围。

Regional 模式只会解析为以下固定组合，不会把一个区域的 Streaming endpoint 与另一个区域的 Native endpoint 混用：

区域	Streaming	Native
beijing	wss://dashscope.aliyuncs.com/api-ws/v1/inference	https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
singapore	wss://dashscope-intl.aliyuncs.com/api-ws/v1/inference	https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation

Custom Streaming 与 Native endpoint 必须分别是有效的 ws/wss 和 http/https URL。非 loopback host 必须使用加密的 wss/https，URL 不得包含内嵌 credential。程序会使用配置的原始字符串，包括 path、port 和 query。Regional 模式会忽略并保留非活动的 Custom URL。

识别预设

值	生效控制项
standard	max_sentence_silence_ms = 800；关闭语义标点；关闭多阈值模式；不发送语音/噪声阈值。该值继续作为默认值。
low-latency-dictation	400 ms；关闭语义标点；开启多阈值模式；不发送阈值。该值仍是实验性评估候选项，不构成通用建议。
long-form	1300 ms；开启语义标点；关闭多阈值模式；不发送阈值。该值仍是实验性评估候选项。
custom	使用全部四个 raw control。静音时长必须为 200–6,000 ms；可选阈值必须是 -1..=1 范围内的有限数值；语义标点与多阈值模式互斥。

动态词汇表

vocabulary 是可选配置。Streaming 会把同一份经过 trim 的 term/weight map 放入 run-task，Native 会把它放入完整音频请求。本地验证会执行以下全部限制：

• 最多 2,000 个 entry；
• 所有已配置 term 的 byte 总数最多为 256 KiB；
• 不得包含 control character，trim 后不得为空；
• trim 后完全由 ASCII 组成的 term 最多包含 7 个 whitespace-separated segment；包含非 ASCII 文本的 term 最多包含 15 个 Unicode character；
• weight 只能是 1–5 或精确值 50；
• weight = 50 的 entry 最多为 50 个；
• trim 后的 term 不得重复，比较时使用精确 string comparison。

常规 diagnostics 只会报告 entry 数量，绝不会报告 term 内容。

Native final-pass policy

• streaming-only 不会自动发送完整录音。
• adaptive 会在 Streaming 为空、失败、降级、中断、过载、provider 未明确发送完成事件，或录音达到 30 秒时运行 Native。只有可用、未过载、明确完成且短于 30 秒的 stream 才会跳过 Native。如果正常完成且可用的 stream 确实发送了 Audio3 Session Context，程序不会只因为时长达到 30 秒就用 Native 替换它；其他恢复条件仍然生效。
• always 会针对每段未取消且非空的录音运行 Native。

成功的 Native transcript 具有更高优先级。Native 失败或超时后，程序仍可使用有效的 Streaming 文本；仍无有效文本时，才会按需使用本地 fallback。取消操作绝不会启动 Native。Native 最多接受 10 MiB 的原始 WAV byte。

配置迁移与区域 credential

迁移过程会区分字段缺失与明确配置：

• 缺少 endpoint_mode 时，只有与北京或新加坡 canonical pair 完全一致的 URL 组合才会进入 Regional 模式。匹配的 pair 会提供推断区域，但明确配置的 region 具有更高优先级。其他所有组合都会变为 Custom，并逐 byte 保留两个原始 URL string；缺少 region 时默认为 Beijing。
• 已移除的 workspace_id 会在加载时忽略，并且在保存时省略。它不会影响请求或路由。
• 旧版 native_final_pass_enabled = true 会变为 native_final_pass_mode = "always"，false 会变为 "streaming-only"。如果新旧字段同时存在，只有相互一致的组合可以加载；冲突组合会因含义不明确而被拒绝。
• 缺少 recognition_preset 时，只有精确的默认 raw control 组合（800、两个开关均为 false、无 threshold）会变为 standard。其他所有组合都会变为 custom，并保留 raw value。

Alibaba API key 受区域范围约束。Voice Input 不会在区域改变时迁移 key，也绝不会探测其他区域。如果所选区域需要另一份 key，请自行替换 alibaba-api-key credential。支持选择 Singapore 不表示每个 model/control 场景都已经完成在线验证。

以下独立命令要求当前配置已经选择并明确启用 Audio3。命令会把 WAV 上传到解析后的 Regional 路由或完全按原值使用的 Custom endpoint，并且可能产生 API 费用：

voice-input asr stream-test --file sample.wav
voice-input asr test --file sample.wav

Streaming test 要求使用 16 kHz、单声道、PCM16 WAV。Native 命令遵守 10 MiB 原始 WAV 限制。

[output]

字段	默认值	含义
mode	"paste"	文本始终通过剪贴板粘贴。程序仍可解析旧配置中的 type 和 clipboard，但是这些值不再改变运行时行为。
fallback_to_clipboard	true	用于兼容旧配置；加载和保存时会保留该字段，但它不再改变运行时行为。
type_delay_ms	0	用于兼容旧配置；程序不再执行逐字符合成输入。
pre_type_delay_ms	140	剪贴板输出前的等待时长。Toggle 快捷键包含 modifier 时至少等待 500 ms。
paste_keys	"shift+Insert"	Wayland 粘贴快捷键，由 Hyprland dispatch sendshortcut 发送给活动窗口。支持 Ctrl、Shift、Alt 和 Super modifier。
prefer_paste_for_xwayland	true	用于兼容旧配置；XWayland 始终使用粘贴路径。
xwayland_paste_keys	"shift+Insert"	通过 xdotool 发送的 XWayland 快捷键；留空时使用 paste_keys。

每次输出都会把识别文本暂时写入目标剪贴板，发送粘贴快捷键，等待 220 ms，再恢复原内容。在原生 Wayland 路径中，transcript 与恢复的 payload 都使用 wl-copy --sensitive hint；只有兼容的剪贴板管理器才保证不把这些内容写入历史记录，并且不改变其顺序。XWayland 没有等效 hint。无法读取剪贴板内容时，备份和恢复只能尽力执行。

[ime]

字段	默认值	含义
manage_fcitx5	true	启用 Fcitx5 guard。
force_ascii_before_output	true	两个字段都为 true，且 fcitx5-remote 返回状态 2 时，输出前运行 fcitx5-remote -c，输出后运行 -o。

[llm]

字段	默认值	含义
enabled	false	启用保守的 transcript 整理。失败时始终保留 ASR 文本。
api_base_url	"https://api.openai.com/v1"	OpenAI-compatible base URL；客户端会附加 /chat/completions。
model	""	启用 LLM 后必须填写的 model ID。
timeout_ms	15000	共享的 refinement 预算，运行时限制为 1,000–30,000 ms。带上下文和纯 transcript 请求共用该预算；预算达到 10,000 ms 时，会为纯 transcript 恢复保留最后 5,000 ms。
provider_sort	""	仅当该值非空，并且 URL host 是 openrouter.ai 或其 subdomain 时，客户端才发送 provider.sort。其他 host 会忽略该字段。
agent_context_enabled	false	在 dictation 开始时，从经过验证且当前聚焦的 Pi/Codex session 捕获一次术语。Audio3 或 LLM refinement 任一需要消费 snapshot 时，该字段都会生效；两个 consumer 都不存在时不会执行捕获。
agent_context_max_chars	6000	本地 source-message budget，有效范围为 500–12,000 个 character。本地 redaction/truncation 先于各 consumer 的选择执行；该值不是远程发送的字符数。

启用的 consumer 会共用一份不可变的 start-time 术语 snapshot。Audio3 Session Context 接收使用换行分隔且最多 400 个 character 的视图。Refine 最多接收 96 个 term，并且 term character 总数最多为 1,500。每个 consumer 都会采用小于 agent_context_max_chars 的独立上限；程序不会发送本地 source message、term frequency、window title 或 process metadata。

LLM credential 的 ID 始终是 openrouter-api-key，即使 api_base_url 指向其他 OpenAI-compatible provider。voice-input config 不会输出 key。

[hud]

字段	默认值	含义
enabled	true	控制是否显示常驻 Quickshell HUD 的 surface。禁用 surface 后，voice-input-hud.service process 仍可继续运行。
margin_bottom	72	Quickshell HUD 使用的下边距，单位为 logical pixel。
height	56	Quickshell HUD capsule 使用的基础/最小高度，单位为 logical pixel。
position	"bottom-center"	可选 bottom-center、bottom-left 或 bottom-right；该值会写入状态，并由 Quickshell 应用。
offset_x	0	水平偏移，单位为 logical pixel；正值向右移动。
offset_y	0	加到下边距上的垂直偏移；正值向上移动。
nudge_step	24	voice-input hud move … 的默认移动量；运行时最小为 1。

Daemon 会在每个 HUD snapshot 中提供 hud_enabled、hud_margin_bottom、hud_height、hud_position、hud_offset_x 和 hud_offset_y。Quickshell 会应用全部六个值。

移动命令会立即更新 TOML 和 runtime state：

voice-input hud move left
voice-input hud move up 10
voice-input hud position bottom-right
voice-input hud center   # bottom-center 且 x=0；保留 y
voice-input hud reset    # bottom-center 且 x=y=0

Credential 与环境变量 fallback

Daemon 启动时按以下顺序解析每个 secret：

1. $CREDENTIALS_DIRECTORY 中的 systemd credential：alibaba-api-key 或 openrouter-api-key；
2. VOICE_INPUT_ALIBABA_API_KEY 或 VOICE_INPUT_OPENROUTER_API_KEY；
3. 旧版 config 中可能存在的内存 TOML 值。

随附 service 应使用加密的 systemd credential。环境变量主要适用于手动启动的 daemon；同一用户的 process inspection 可能看到环境变量。

Settings 的 credential replacement 和 Test LLM request 只会通过继承的 stdin 发送用户输入的 secret。Key 不会进入 config、process argument、环境变量、日志或 backend response。Test LLM 可以使用刚输入的 key，也可以使用加密 credential store 中已有的值。

另请参阅：安全与隐私 · 故障排查