> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mauvely.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common Sotto problems and their fixes: no model, the shortcut not firing, nothing being pasted, the overlay on the wrong monitor, slow transcription.

<AccordionGroup>
  <Accordion title="“No speech model installed”" icon="brain">
    Open **Settings → Model** and download one. Nothing works without it.

    **Large v3 Turbo** on a discrete GPU, **Small** on integrated graphics or CPU. See
    [Speech models](/sotto/models).
  </Accordion>

  <Accordion title="The shortcut does not do anything" icon="keyboard">
    Sotto asks your desktop for the shortcut through the GlobalShortcuts portal, which Plasma 5.25
    and later provide. Some desktops do not have it.

    **Fix:** disable the shortcut in **Settings → Shortcut**, then bind `sotto --toggle` in your
    desktop's own shortcut settings — *System Settings → Shortcuts → Custom* on KDE, or your
    compositor's config file elsewhere. It behaves identically.

    Also check the binding has not been claimed by something else, in your desktop's shortcut list.
  </Accordion>

  <Accordion title="Nothing gets pasted into the application" icon="clipboard">
    In order:

    1. **Install `wl-clipboard`.** Nothing clipboard-based works without it.
    2. **Set up ydotool**, or accept the one-time RemoteDesktop permission prompt when it appears.
       One of the two is needed to synthesise the paste keystroke.
    3. **If the target is a terminal**, the default `Ctrl` `V` will not paste — terminals use
       `Ctrl` `Shift` `V`. Switch to **Type it** or **Clipboard only** in **Settings → Output**.

    In the worst case, the text is always left on the clipboard, so it is never lost.
  </Accordion>

  <Accordion title="The overlay appears on the wrong monitor" icon="display">
    With LayerShellQt installed and the screen setting on **auto**, your compositor places the
    overlay on the active output — and it is re-evaluated every time it appears.

    Without LayerShellQt, the fallback window uses the screen under the mouse pointer instead.

    **Fix:** install `layer-shell-qt`, or pin a specific monitor in **Settings → Appearance**.
  </Accordion>

  <Accordion title="Transcription is slow" icon="gauge">
    Look at the backend named at the bottom of the Settings window.

    * **It says `cpu`** — that is the problem. Rebuild with `-DSOTTO_GPU=vulkan` (or `hip` for ROCm,
      `cuda` for NVIDIA). See [Installing](/sotto/installing#pick-a-backend).
    * **It names a GPU backend** — try a smaller model. Large v3 is significantly heavier than
      Large v3 Turbo for a modest accuracy gain.
  </Accordion>

  <Accordion title="ROCm will not start, or produces garbage" icon="microchip">
    If your GPU is not officially supported by ROCm, set `HSA_OVERRIDE_GFX_VERSION` before running —
    `10.3.0` covers many RDNA2 cards.

    If that does not help, build with `-DSOTTO_GPU=vulkan` instead. On AMD, Vulkan is often within a
    few percent of ROCm for this workload and far less sensitive to driver versions.
  </Accordion>

  <Accordion title="Accuracy is poor" icon="ear-listen">
    In rough order of impact:

    1. **The microphone.** A headset beats a laptop microphone across a room by more than any model
       upgrade will.
    2. **A bigger model.** Small → Large v3 Turbo is a real step up.
    3. **Pin the language** in **Settings → Model** instead of leaving it on auto. Detection can
       guess wrong on a short first utterance.
    4. **Speak in complete sentences.** Whisper uses sentence context; fragments give it nothing to
       work with.
  </Accordion>

  <Accordion title="Random line breaks appear in my text" icon="paragraph">
    You are probably saying a phrase that contains "new line" or "new paragraph" — "a new line of
    products" is the classic. Turn voice commands off in **Settings → Formatting** and use pauses
    for paragraphing instead.

    If paragraphs are breaking where you did not pause deliberately, raise the pause threshold in
    the same place.
  </Accordion>

  <Accordion title="My words get cut off at the start" icon="scissors">
    Sotto keeps a short rolling buffer specifically so the first words are not clipped, so this is
    unusual. Check that the right input device is selected in **Settings → Audio**, and that it is
    not being brought up by a noise-suppression layer that gates the first fraction of a second.
  </Accordion>

  <Accordion title="A second sotto command does nothing visible" icon="terminal">
    That is correct behaviour. A running Sotto owns its session-bus name, so a second invocation
    forwards its command to the first and exits — it does not start a second process. See
    [Notepad and CLI](/sotto/notepad-and-cli#d-bus).
  </Accordion>
</AccordionGroup>

## Still stuck?

Note which desktop and compositor you are on, what the Settings window reports as the backend, and
which model you have installed — those three answer most questions before they are asked.