Troubleshooting¶
Every failure mode below has been hit by a real alpha tester. Each entry lists the symptom (what you see), the cause (what's actually happening), and a fix per OS. If you run into something that isn't here, use Discord Support or open a ticket — we'd rather expand this page than make you guess.
For first-install steps and the dictation loop itself, see Install and First dictation. For what Quill does and doesn't send off your machine, see the Privacy promise.
Quick index¶
- Setup — permissions, model download, polish endpoint, hotkey, Wayland
- Runtime — crashes, latency, stuck modifier keys, lost settings, orphan processes
- Linux-specific — engine-not-found,
.debvs.rpm, AppImage FUSE, build-from-source dev libs - Intel Mac — unsupported in the current closed alpha
- Audio — wrong input device, intermittent cut-out
Setup¶
Microphone permission denied¶
Symptom: the level meter on the setup screen is flat. The Activity log
shows no captures. The setup screen reads "Microphone permission: Denied,"
or the daemon logs audio: failed to open input stream: permission denied.
Cause: the OS hasn't granted your user (or the Quill process specifically) access to the microphone device.
| OS | Fix |
|---|---|
| macOS | Open System Settings → Privacy & Security → Microphone (direct link). Find Quill in the list and toggle it on. Quit Quill (Cmd+Q from the menu-bar icon) and reopen it. If Quill isn't in the list at all, macOS hasn't been asked yet — hold F8 once to trigger the prompt. If you previously denied it via TCC and the prompt is suppressed, run tccutil reset Microphone com.corvidlabs.quill and try again. |
| Linux (PulseAudio) | Microphone access on stock PulseAudio is allowed by default. If it isn't, check pactl list sources short — a missing device is usually a kernel-level capture problem, not a permission problem. The pavucontrol GUI has a Recording tab that lets you confirm Quill is reading from the right source while a capture is in flight. |
| Linux (PipeWire) | Same check: wpctl status should list a default Audio/Source. If wpctl reports your mic as muted, wpctl set-mute @DEFAULT_AUDIO_SOURCE@ 0 un-mutes it. On flatpak-style sandboxes (irrelevant for the .deb / AppImage but possible if you've rebuilt) grant the pipewire portal or --device=all. |
| Windows | Not yet shipping; planned for a future alpha. When it lands, the path will be Settings → Privacy & security → Microphone with Quill toggled on under "Let desktop apps access your microphone." |
Accessibility permission denied (macOS)¶
Symptom: Quill transcribes correctly — you can see the polished text in the Activity log — but nothing gets typed into the focused field. Or text appears via a momentary clipboard paste that briefly clobbers whatever you'd previously copied.
Cause: the Accessibility inject mode writes directly to the focused
UI element's kAXSelectedText and needs the macOS Accessibility permission.
Starting in alpha.4, Quill no longer hard-bails when the permission is
missing — it degrades gracefully to clipboard paste — but the
Accessibility path is the high-quality one and worth granting.
| OS | Fix |
|---|---|
| macOS | Open System Settings → Privacy & Security → Accessibility (direct link). Click the lock icon and authenticate. Find Quill in the list and toggle it on. Restart Quill. If Quill isn't in the list, click + and add /Applications/Quill.app. The first dictation attempt populates the list automatically, but a stale TCC database occasionally needs the manual nudge. |
| Linux | Not applicable. Linux has no equivalent permission gate; injection goes through enigo (X11) or the compositor (Wayland — see Wayland injection below). |
Whisper model not found / download failed¶
Symptom: the setup screen sits at "Downloading speech model… 0%"
indefinitely, or jumps to "Download failed: connection reset." The daemon
logs stt: model file missing at <path>.
Cause: the first-run downloader (a single HTTPS GET to the whisper.cpp ggml mirror) was blocked, interrupted, or failed. The download is not partial-resume — a 99% failure restarts from scratch.
| OS | Fix |
|---|---|
| macOS | Click Retry on the failed download card. If you're behind a corporate proxy, set HTTPS_PROXY before launching: HTTPS_PROXY=http://proxy.corp:8080 open -a Quill. Manual fallback: download ggml-base.en.bin (or tiny.en / small.en) and drop it into ~/Library/Caches/quill/models/. Quill picks it up on the next setup-check pass. |
| Linux | Click Retry, or set HTTPS_PROXY in the shell you launch quill-app from. Manual fallback: download the same model file and drop it in ~/.cache/quill/models/. Create the directory if it doesn't exist. |
| Windows | Not yet shipping. |
The download URLs come from the whisper.cpp project's public release manifest. Quill verifies size after download but does not yet verify SHA — a manual download from a trusted mirror is fine.
Polish model download or enhance failed¶
Symptom: captures work, the raw Whisper transcript shows up in the
Activity log, then a polish failed: connection refused warning, and the
raw transcript is injected instead of the polished version. Subsequent
captures show the same error.
Cause: the embedded GGUF model is missing, still downloading, failed
SHA verification, or the optional system / remote Ollama-compatible
endpoint is unreachable. Release packages no longer ship a bundled Ollama
binary.
Triage (any OS):
# Is the embedded GGUF present in Quill's model cache?
ls -lh ~/Library/Caches/quill/models 2>/dev/null || ls -lh ~/.cache/quill/models
# If you opted into system/remote polish, is that endpoint reachable?
curl -s http://127.0.0.1:11434/api/tags
| OS | Fix |
|---|---|
| macOS | Open Settings → Polish backend. Confirm it's Embedded, then retry the model download from setup. To bypass polish entirely while you debug, set backend to None in Settings; the daemon will inject raw Whisper output, which is still readable. |
| Linux | Same path: Settings → Polish backend. Confirm it's Embedded, then retry the GGUF download. To use your own Ollama-compatible server: backend = System + endpoint = http://127.0.0.1:11434, or Remote for a non-loopback endpoint. |
| Windows | Not yet shipping. |
The daemon logs the concrete model-download, SHA, or endpoint error when polish fails. See Where are the logs? below.
Hotkey doesn't trigger¶
Symptom: F8 (or whatever key you set) does nothing — no capture starts. Or F8 toggles Music play/pause / iTunes media controls instead of starting a capture.
Cause: another app, the OS itself, or your desktop environment grabbed the key first. The OS-level grab wins; Quill never sees the event.
| OS | Fix |
|---|---|
| macOS | Open System Settings → Keyboard → Keyboard Shortcuts. Walk through Mission Control, Spotlight, Screenshots, App Shortcuts, and Function Keys sections and disable or remap anything bound to your chosen key. Spotlight in particular grabs Cmd+Space and won't release it. Keyboard → Keyboard Shortcuts → Function Keys also has a "Use F1, F2, etc. keys as standard function keys" toggle — without this, F-keys send media events (play/pause, volume) instead of raw keycodes and Quill never sees them. If a third-party tool like Karabiner-Elements, Hammerspoon, or a Logitech driver has a profile binding the key, disable that profile. As a last resort, open Quill → Settings → Quick capture hotkey and pick a different F-key. |
| Linux (X11 / Xorg) | Quill registers globals via rdev/x11 and they work on Xorg sessions out of the box. Conflicts usually come from a window manager or compositor binding. Search your WM config — i3: bindsym, sway (X11 mode): bindsym, KDE: System Settings → Shortcuts, GNOME: Settings → Keyboard → Keyboard Shortcuts → View and Customize Shortcuts — and remove or remap whatever is bound to F8. |
| Linux (Wayland) | Wayland compositors do not deliver global hotkeys to a normal user process at all — see Wayland injection / global keys for the compositor-binding workaround. |
| Windows | Not yet shipping. |
Wayland injection doesn't work¶
Symptom: on a Wayland session (Hyprland, Sway, GNOME-Wayland, KDE
Plasma 6 Wayland), the global hotkey is never delivered to the daemon, or
nothing gets injected even when capture works. Capture itself may also be
silent if you're using a compositor that grabs /dev/input/* exclusively.
Cause: Wayland's security model intentionally blocks normal user processes from grabbing global keys or synthesizing input events outside their own surfaces. This is by design, not a bug; we work around it via compositor binds and XWayland fallback.
| Environment | Fix |
|---|---|
| Hyprland | Bind the key in your compositor config and have it call the daemon's IPC: bind = , F8, exec, quill press quick bindr = , F8, exec, quill release quick Reload: hyprctl reload. |
| Sway | bindsym --no-repeat F8 exec quill press quick bindsym --release F8 exec quill release quick Reload: swaymsg reload. |
| GNOME (Wayland) | GNOME doesn't expose press / release as separate events from gsettings. Either log out and use the GNOME-Xorg session for now, or wait for the global-shortcut portal support we're tracking. Injection still works under XWayland for any X11 app you focus. |
| KDE Plasma 6 (Wayland) | Similar limitation. The XWayland fallback path works for injection into X11 apps. For Wayland-native apps, the compositor must broker the keystroke; we don't have a working path yet. |
Known limitation: even with the compositor binding, native Wayland
applications using wl_keyboard directly may reject synthesized events.
Quill's injection currently falls back to XWayland, which works for any
app running under XWayland (basically every non-GTK4-native app today)
but not for true Wayland-only surfaces.
Runtime¶
Daemon crashed during dictation¶
Symptom: mid-dictation the menu-bar icon goes from red back to grey, the GUI shows "Quill stopped unexpectedly," and no transcript appears. Subsequent F8 presses do nothing until you click Restart Quill in the GUI.
Cause: an unhandled error in the daemon process. Could be Whisper inference (model file corrupted on disk), the audio capture thread (device disconnected mid-capture — common with USB mics), or the polish subprocess.
First step on every OS: capture the daemon log before anything else. See Where are the logs?. Then:
| OS | Fix |
|---|---|
| macOS | Quit Quill (Cmd+Q from menu bar, or kill quill-app from Activity Monitor) and relaunch. If the crash reproduces, launch the daemon manually with stderr attached: /Applications/Quill.app/Contents/Resources/quill-daemon listen --key f8, then trigger the crash with stderr capturing the panic. Copy the panic line and backtrace into a Discord Support ticket. |
| Linux (.deb) | pkill quill-daemon quill-app to clean up, then relaunch. To capture the panic: quill-daemon listen --key f8 2>&1 \| tee /tmp/quill-crash.log and reproduce. Attach /tmp/quill-crash.log to the issue. |
| Linux (AppImage) | Same as .deb, but the daemon binary lives inside the AppImage. Easiest: launch the AppImage from a terminal so its stderr is visible (./Quill-*.AppImage 2>&1 \| tee /tmp/quill-crash.log). |
When filing the bug, include: OS version (sw_vers on macOS,
lsb_release -a on Linux), Quill version (quill-daemon --version), and
whether the crash reproduces with Polish backend = None (helps isolate
whether it's the polish pass or the pipeline itself).
Polish takes forever / times out¶
Symptom: capture finishes (release F8, see the red icon go away), the
raw transcript appears in the Activity log, then a long pause — 10 s,
20 s, 60 s — before the polished version appears or the daemon logs
polish stage exceeded 5s soft timeout (added in alpha.4).
Cause: either the local model is slow on your hardware, the model is
loaded fresh (first-call latency is always higher than steady-state), or
you've pointed polish_backend = "remote" at a network endpoint that's
slow or unreachable.
| Path | Fix |
|---|---|
| Embedded polish, slow on first call | Normal. The first polish call after a cold start loads the GGUF into memory; subsequent calls are much faster. Trigger one warmup dictation after launch and the steady-state latency drops. |
| Embedded polish, slow always | The selected model is too big for your hardware or the utterance is long. Use F8/raw for speed, set Polish = None, or choose a smaller embedded model once the picker exposes one. |
| Remote endpoint slow / timing out | Confirm the endpoint is reachable: curl -s http://your-endpoint:11434/api/tags. If curl is also slow, it's a network issue, not Quill. The per-stage timeout falls back to raw text so one hung polish call doesn't stall the pipeline. |
Cmd+V got stuck after Quill ran¶
Symptom: after a Quill capture that used the Paste inject mode,
your keyboard is stuck — typing a produces select-all, typing s saves,
etc. The Cmd (macOS) or Ctrl (Linux) modifier appears to be held down
even though nothing is physically pressed.
Cause: a bug in alpha.3 and earlier — the Paste inject path's Cmd+V
Click step could error and never reach the modifier Release, leaving
the modifier "stuck" until the user pressed it manually.
Status: Fixed in alpha.4 by
#78. The modifier-key
release is now guaranteed: an explicit Release runs after Click even
when Click itself errors.
| OS | Fix |
|---|---|
| macOS | Upgrade to alpha.4 or newer. As an immediate unstuck-it workaround, tap Cmd once on the physical keyboard — that re-syncs the modifier state. |
| Linux | Upgrade to alpha.4 or newer. Tap Ctrl once to re-sync. |
If you're already on alpha.4 or newer and you still see a stuck modifier,
that's a regression — file a bug and include the inject mode you were on
(accessibility / keystroke / paste).
My settings reset themselves¶
Symptom: every time you launch Quill, your hotkey choice, polish backend, inject mode, and other Settings reset to defaults. Or the settings persist for a while, then one launch they're all gone.
Cause: a bug in alpha.3 and earlier — quill-app wrote settings
non-atomically (write-in-place), so a crash mid-write left a half-written
TOML file that the next launch parsed as defaults, silently wiping every
preference.
Status: Fixed in alpha.4 by
#81. Settings are now
written atomically (temp file → fsync → rename), so a crash mid-write can't
corrupt the file. A schema_version field was added for future migrations,
and a warn-log fires on TOML parse failure so silent resets are visible in
the daemon log.
| OS | Fix |
|---|---|
| macOS | Upgrade to alpha.4 or newer. Confirm ~/Library/Application Support/quill/settings.toml is writable by your user (ls -l ~/Library/Application\ Support/quill/). If a stale half-written file exists, delete it and Quill will recreate with defaults on next launch — set your preferences once and they'll stick. |
| Linux | Upgrade to alpha.4 or newer. Settings live at ~/.config/quill/settings.toml. Same fix: delete a corrupted file and let Quill recreate it. |
Clipboard contents disappeared¶
Symptom: you had something on your clipboard (a copied URL, a chunk of code), you triggered a Quill dictation, the inject completed — and your clipboard now contains the dictated text instead of your original copy.
Cause: a bug in alpha.3 and earlier — the Paste inject path's
stash-set-paste-restore sequence used ? after set_text, so any failure
in the Paste step dropped your prior clipboard before the restore block
ran. Even the success path occasionally raced.
Status: Fixed in alpha.4 by #78. Stash → set → paste → restore is now a four-phase guarded sequence with the restore unconditional once the stash succeeded. Clipboard contents are guaranteed to round-trip.
| OS | Fix |
|---|---|
| macOS / Linux | Upgrade to alpha.4 or newer. If you'd rather avoid clipboard injection entirely, set Settings → Inject mode → Keystroke (Linux) or Accessibility (macOS — requires the Accessibility permission). Both modes bypass the clipboard. |
Daemon or legacy polish subprocess orphaned after Quill closed¶
Symptom (pre-alpha.4): you close the Quill window, but
ps aux | grep -E 'quill|ollama' shows quill-daemon and, on legacy
development builds, ollama serve still running. They hold the microphone,
keep the polish model in RAM, and don't exit until you reboot or pkill -9
them.
Cause: two distinct shutdown paths could leak. The GUI's Drop impl
called try_lock() on a mutex permanently held by the daemon-waiter task,
so start_kill never ran (the daemon outlived the GUI). Separately, the
daemon's IPC Shutdown watchdog called process::exit(0) without first
signaling the legacy bundled-Ollama PID (so Ollama outlived the daemon).
Status: Fixed in alpha.4 by
#74 (GUI → daemon) and
#79 (daemon → legacy polish child).
The GUI now captures the daemon's PID at spawn time and signals SIGTERM
(SIGKILL after 100 ms) directly via libc::kill, bypassing the mutex. The
daemon's IPC watchdog now signals any legacy bundled-Ollama PID before exiting.
| OS | Fix |
|---|---|
| macOS | Upgrade to alpha.4 or newer. To clean up an existing orphan: pkill quill-daemon; pkill -f 'quill.*ollama'. If the daemon refuses SIGTERM (rare), kill -9 it. |
| Linux | Same: upgrade to alpha.4. Clean up an orphan: pkill quill-daemon; pkill -f 'quill.*ollama'. Check with ps aux | grep -E 'quill|ollama' afterward to confirm. |
If you're already on alpha.4 or newer and you still see an orphan, include
the ps output in your bug report along with the OS version.
Where are the logs?¶
The Quill GUI has an Activity log panel — toggle it from the menu bar. That covers transcripts, pipeline events, and recoverable warnings.
For lower-level daemon logs (panics, Ollama subprocess output, IPC events), launch the daemon manually with stderr attached:
| OS | Command |
|---|---|
| macOS | /Applications/Quill.app/Contents/Resources/quill-daemon listen --key f8 |
| Linux (.deb) | quill-daemon listen --key f8 |
| Linux (AppImage) | Launch the AppImage from a terminal so its stderr is visible. |
By default, raw transcripts are not printed to stdout — that's a
deliberate privacy choice as of alpha.4 (see the
Privacy promise). To see them for debugging, pass
--emit-transcripts or set QUILL_EMIT_TRANSCRIPTS=1. The GUI sets this
env var when it spawns the daemon child, so the Activity log panel keeps
working; CLI users get the privacy default.
Linux-specific¶
"Couldn't find the Quill engine"¶
Symptom: Quill opens but the setup screen reads "Couldn't start the Quill engine." The Activity log is empty. The GUI process is alive but no daemon spawns.
Cause: a bug in alpha.3 and earlier — the .deb / AppImage installer
puts quill-daemon at /usr/libexec/quill/quill-daemon, but the GUI's
binary resolver only checked the sibling of quill-app. Launch failed with
couldn't find the Quill engine.
Status: Fixed in alpha.4 by
#68. The resolver now also
walks ../libexec/quill/ in addition to the sibling-of-quill-app path.
| Distro | Fix |
|---|---|
| Ubuntu / Debian | sudo apt install --reinstall ./quill_*_amd64.deb (or *_arm64.deb on aarch64). Confirm the daemon is at /usr/libexec/quill/quill-daemon and is executable: ls -l /usr/libexec/quill/quill-daemon. |
| Fedora / Arch / Other (AppImage) | Re-download the latest AppImage from the release page. The daemon is bundled inside; the resolver fix is the same. |
| From-source build | cargo build --release --workspace produces ./target/release/quill-app and ./target/release/quill-daemon. They must remain siblings (the resolver's primary check), or be discoverable under ../Resources/ (macOS bundle) or ../libexec/quill/ (Linux package). As a last resort, set QUILL_DAEMON_PATH=/absolute/path/to/quill-daemon in the environment before launching quill-app. |
.deb won't install on Fedora / RHEL / other RPM distros¶
Symptom: running rpm -i quill_*.deb or dnf install ./quill_*.deb
errors out. Or dpkg isn't installed in the first place.
Cause: .deb packages don't install on RPM distros — different package
format. There's no .rpm yet.
Fix: use the AppImage:
The AppImage uses embedded llama.cpp for polish and downloads the verified
GGUF into Quill's model cache on first setup. It works on bare Fedora /
RHEL / openSUSE / Arch without an Ollama install — except for fuse2,
which is an AppImage runtime requirement (see the next entry).
AppImage won't start: "FUSE error"¶
Symptom: running the AppImage fails with
fuse: failed to exec fusermount: No such file or directory, or
dlopen(): error loading libfuse.so.2, or just a silent exit.
Cause: AppImage runtime needs fuse2 (libfuse.so.2) to mount the
bundle. Modern distros default to fuse3, which is not backward-
compatible. Until the AppImage build switches to a static runtime
(planned), fuse2 is required.
| Distro | Fix |
|---|---|
| Fedora / RHEL / Rocky / Alma | sudo dnf install fuse fuse-libs |
| openSUSE | sudo zypper install fuse libfuse2 |
| Arch / Manjaro | sudo pacman -S fuse2 |
| Ubuntu 22.04+ / Debian 12+ | sudo apt install libfuse2 (the runtime, not just the userspace fuse package — naming on Debian-family is libfuse2) |
| Workaround (no FUSE) | Extract and run: ./Quill-*.AppImage --appimage-extract produces a squashfs-root/ directory; launch ./squashfs-root/AppRun. Useful in containers / chroots where FUSE isn't available. |
Missing X11 dev libs at build time¶
Symptom: cargo build fails with errors like
X11/extensions/XInput2.h: No such file or directory,
Package xtst was not found in the pkg-config search path, or
ld: cannot find -lXi.
Cause: Quill links against XInput2 and XTest at build time for the
keystroke-injection path. The runtime shared libraries are usually already
installed; the development headers (the *-devel or *-dev packages)
are not.
| Distro | Fix |
|---|---|
| Ubuntu / Debian | sudo apt install clang libclang-dev libxi-dev libxtst-dev libxdo-dev libasound2-dev libudev-dev pkg-config |
| Fedora / RHEL / Rocky | sudo dnf install clang libclang-devel libXi-devel libXtst-devel libxdo-devel alsa-lib-devel systemd-devel pkgconf-pkg-config |
| openSUSE | sudo zypper install clang libclang-devel libXi-devel libXtst-devel libxdo-devel alsa-devel libudev-devel pkg-config |
| Arch / Manjaro | sudo pacman -S clang libxi libxtst xdotool alsa-lib pkgconf (Arch ships dev headers in the same package as the runtime — no separate -devel package.) |
After installing, cargo clean && cargo build --release --workspace should
succeed. If you're cross-compiling, the dev headers must come from your
target sysroot, not your host.
If llama-cpp-sys-2 fails during bindgen with
fatal error: 'stdbool.h' file not found, clang's resource headers are
not visible to bindgen. Install clang / libclang-dev, then rerun the
build; the Linux packaging script also exports BINDGEN_EXTRA_CLANG_ARGS
from clang -print-resource-dir when clang is available and always
adds cc -print-file-name=include when that directory exists. Minimal
self-hosted runners may omit the clang executable, but they still need
the libclang shared library that bindgen loads. The package script
checks common Debian and RPM library paths, including /usr/lib64.
If whisper-rs fails with errors like
no field greedy on type whisper_full_params,
no field beam_search, or no field n_threads, the local bindgen output
for whisper.cpp is wrong for the whisper-rs crate version. Quill's
repo-level Cargo config sets WHISPER_DONT_GENERATE_BINDINGS=1 so
source builds use the pre-generated bindings shipped by
whisper-rs-sys, matching release CI. If you build from a copied source
tree that omits .cargo/config.toml, set the variable manually before
building:
whisper-rs-sys checks whether the variable is present, not whether it
is truthy. Setting WHISPER_DONT_GENERATE_BINDINGS=0 still disables
local binding generation; remove or comment out the variable if you
intentionally need to run bindgen yourself.
Linux package starts with "libllama.so: cannot open shared object file"¶
Symptom: launching quill-app or the AppImage exits immediately with
error while loading shared libraries: libllama.so.
Cause: Linux release packages link embedded llama.cpp dynamically so
it can coexist with whisper.cpp in the same app and daemon binaries. The
package should include those llama.cpp shared libraries under
/usr/lib/quill for .deb, or usr/lib/quill inside the AppImage.
Fix: re-download the release asset. If it still happens, attach the
output of dpkg-deb --contents quill_*_amd64.deb | grep usr/lib/quill
for .deb, or ./Quill-*.AppImage --appimage-extract followed by
find squashfs-root/usr/lib/quill -maxdepth 1 -type f -print for
AppImage installs.
Intel Mac¶
Quill is unsupported on Intel Macs¶
Symptom: double-clicking the app icon does nothing, or macOS says
"You can't open the application Quill because it is not supported on this
type of Mac." Running the app binary from Terminal may show Bad CPU type
in executable.
Cause: current closed-alpha macOS packages are Apple Silicon-only.
The .dmg ships aarch64-apple-darwin binaries for M-series Macs; it is
not a universal Mach-O build and does not include x86_64 macOS binaries.
Fix: use an Apple Silicon Mac for the macOS alpha, or use the Linux
x86_64 .AppImage / .deb artifact on a supported Linux machine. Intel
macOS builds are not part of the closed-alpha release lane.
Audio¶
Wrong microphone selected / picks the wrong input device¶
Symptom: the level meter is flat (or shows your speakers, oddly), the transcript is empty or full of background noise, and you have multiple input devices on your machine (built-in mic + USB headset + HDMI capture card, say).
Cause: Quill defaults to whatever your OS reports as the "default input device." Sometimes that's not the device you actually speak into — a Blue Yeti might rank below a HDMI capture-card mic Quill has no way to know about.
Fix: list devices, then pin Quill to the right one.
The output looks like:
Then either:
| Where | How |
|---|---|
| GUI | Open Settings → Input device and pick the right one from the dropdown. The change is live; no daemon restart. (Linux mic fix landed in #24.) |
| CLI | Pass --input-device "Blue Yeti" to quill-daemon listen. Exact-name match preferred, substring match accepted. (#24) |
On Linux, alpha.4 also auto-prefers PipeWire then PulseAudio over ALSA when multiple backends are present — fixes the common "ALSA picked a phantom HDMI input" case (#25). If you're on alpha.3 or earlier and stuck on the wrong backend, upgrade.
Intermittent silence / cut-out mid-sentence¶
Symptom: the transcript captures the start of what you said, then nothing, then maybe the tail end. Or whole sentences come back as empty. The Activity log shows captures completing in normal duration but with very short transcripts.
Cause: the voice-activity detector (VAD) ended the capture
prematurely. Defaults assume a "natural pause" of 800 ms ends a phrase; if
you speak slowly, take long breaths, or have background noise dipping
under the VAD floor, captures truncate. Conversely, constant background
noise (fan, fridge, traffic) can keep the VAD "on" past your actual speech
and pad the capture with seconds of silence Whisper transcribes as
(silence) / nothing.
Fix: tune the VAD silence threshold.
| Launch path | How |
|---|---|
| GUI (any OS) | Currently CLI-only knob. Edit ~/Library/Application Support/quill/settings.toml (macOS) or ~/.config/quill/settings.toml (Linux) and add vad_silence_secs = 1.5 under [daemon]. Restart Quill. The atomic-write fix from alpha.4 (#81) means hand-edits are safe even if you crash mid-edit. |
| CLI | quill-daemon listen --key f8 --vad-silence-secs 1.5. Default is 0.8 s. Bump up for slow / pause-heavy speakers; bump down for rapid dictation. |
If background noise is the issue, the right fix is hardware: a directional mic, a noise-gate plugin, or moving away from the noise. Software denoising in the capture path is on the roadmap but not in alpha.
Still stuck?¶
Open a Discord Support ticket. Include:
- Your OS + version (
sw_verson macOS,lsb_release -aon Linux). - Your Quill version (
quill-daemon --version). - The daemon log captured with stderr attached, if you can reproduce (see Where are the logs?).
- Whether the bug reproduces with Polish backend = None (helps isolate whether it's a polish-pass issue or a pipeline issue).
This page is updated every release. Cross-reference the CHANGELOG for the canonical record of what's been fixed when.