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

GTK Settings 会展示常用字段，并在保存时重写完整配置。对于界面固定为默认值或未展示的字段，需要手动编辑。

顶层字段与快捷键

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

安装的静态 Hyprland snippet 使用 toggle 模式，而 TOML 示例的值是 hold。可以运行 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	90	单会话独立 capture reader 的最长时长。当前共享 pre-roll capture 路径不会应用该 timer。
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。
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，最少 1,000 ms；同时作为 final-pass HTTP connect timeout。
finalize_timeout_ms	8000	请求 realtime session 结束后的 deadline，最少 1,000 ms。
fallback_to_local	true	Qwen 失败或返回空结果时允许调用本地 backend。如果 realtime 已生成有效 transcript，即使另一个 realtime worker 随后报错，也可能继续使用该文本。

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。

[output]

字段	默认值	含义
mode	"type"	type：直接调用 wtype；clipboard：只复制；paste：复制、发送粘贴按键，再恢复剪贴板。文本超过 120 个字符时，有效模式会从 type 改为 paste。
fallback_to_clipboard	true	直接调用 wtype 失败后尝试 paste 路径。明确配置为 clipboard/paste 时，该字段不生效。
type_delay_ms	0	作为逐字符延迟传给 wtype -d。
pre_type_delay_ms	140	输出前等待时长。直接输入时传给 wtype -s；剪贴板操作前执行相同时长的 sleep。使用 toggle 和 modifier 时至少为 500 ms。
paste_keys	"shift+Insert"	Wayland 粘贴按键。客户端按 + 拆分各部分，并通过 wtype 按下和释放 modifier。
prefer_paste_for_xwayland	true	XWayland 目标会把有效模式从 type 改为 paste。
xwayland_paste_keys	"shift+Insert"	交给 xdotool 的 XWayland 按键；留空时使用 paste_keys。

如果无法读取现有剪贴板内容，paste 的备份和恢复只能尽力执行。clipboard 模式会有意把识别文本留在剪贴板中，并且不会发送粘贴按键。

[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	5000	共享的 refinement 预算，运行时限制为 1,000–5,000 ms。带上下文和纯 transcript 请求不会分别获得预算。
provider_sort	""	仅当该值非空，并且 URL host 是 openrouter.ai 或其 subdomain 时，客户端才发送 provider.sort。其他 host 会忽略该字段。
agent_context_enabled	false	启用当前 Pi/Codex 会话的术语上下文。关闭 LLM refinement 后，该字段不会产生效果。
agent_context_max_chars	6000	上下文字符上限；运行时限制为 500–12,000。截断时会同时保留开头和结尾。

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

[hud]

字段	默认值	含义
enabled	true	控制由 daemon 启动的 Python fallback HUD。单独启用的 voice-input-hud.service 由 systemd 控制，不受该字段控制。
margin_bottom	72	Python fallback HUD 的下边距。当前 Quickshell surface 直接使用 72 px。
height	56	Python fallback HUD 的基础高度。当前 Quickshell surface 直接使用 56 px 最小高度。
position	"bottom-center"	可选 bottom-center、bottom-left 或 bottom-right；该值会写入状态，并由 Quickshell/Python HUD 使用。
offset_x	0	水平偏移，单位为 logical pixel；正值向右移动。
offset_y	0	加到下边距上的垂直偏移；正值向上移动。
nudge_step	24	voice-input hud move … 的默认移动量；运行时最小为 1。

移动命令会立即更新 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 可能看到环境变量。

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