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 对日常选项进行分类；包含技术参数的页面会提供各自的可展开高级设置区域。选择 Alibaba provider 后，相关设置会在 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	"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	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。
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。部分 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。

[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	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	启用当前 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	控制是否显示常驻 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 中已有的值。

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