> ## 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.

# Installing Sotto

> Install Sotto from the AppImage or build it with the GPU backend that matches your hardware, then complete first-run setup.

## The AppImage

The download on mauvely.com is a single-file AppImage:

```bash theme={null}
chmod +x Sotto-x86_64.AppImage
./Sotto-x86_64.AppImage
```

Nothing to install, nothing to uninstall — delete the file to remove it.

<Note>
  There is no Flathub package and no `.deb`, `.rpm` or AUR package. The AppImage is the one Linux
  artifact.
</Note>

<Warning>
  **The GPU backend is fixed when Sotto is compiled, not chosen at runtime.** Check the bottom of
  the Settings window, which names the backend actually in use. If it says `cpu`, transcription will
  be much slower than it needs to be — build from source with the backend that matches your
  hardware.
</Warning>

## Recommended companion packages

Sotto needs a way to put text into other applications. On Arch:

```bash theme={null}
sudo pacman -S --needed wl-clipboard ydotool
```

| Package        | Why                                                       |
| -------------- | --------------------------------------------------------- |
| `wl-clipboard` | Setting and restoring the clipboard on Wayland            |
| `ydotool`      | Synthesising the paste keystroke, or typing text directly |

Without either, Sotto can still transcribe — the text just ends up somewhere you have to fetch it
from. See [Dictating](/sotto/dictation#getting-text-into-an-application).

### Setting up ydotool

Once:

```bash theme={null}
sudo systemctl enable --now ydotool
```

Your user needs write access to `/dev/uinput`; the `ydotool` package ships udev rules for that.

If you would rather not run ydotool, Sotto can use the desktop's RemoteDesktop portal instead — it
asks for permission once and remembers it.

## Building from source

Building lets you pick the GPU backend, which is the single biggest factor in transcription speed.

### Dependencies (Arch)

```bash theme={null}
sudo pacman -S --needed base-devel cmake ninja git \
    qt6-base qt6-declarative qt6-multimedia qt6-svg layer-shell-qt
```

### Pick a backend

| Backend              | Packages                                           | Flag                 |
| -------------------- | -------------------------------------------------- | -------------------- |
| **ROCm** (AMD)       | `rocm-hip-sdk`                                     | `-DSOTTO_GPU=hip`    |
| **Vulkan** (any GPU) | `vulkan-headers vulkan-icd-loader glslang shaderc` | `-DSOTTO_GPU=vulkan` |
| **CUDA** (NVIDIA)    | `cuda`                                             | `-DSOTTO_GPU=cuda`   |
| CPU only             | —                                                  | `-DSOTTO_GPU=cpu`    |

<Tip>
  On AMD, Vulkan is often within a few percent of ROCm for this workload and is far less fussy to
  set up. Try Vulkan first; only reach for ROCm if you have a specific reason.
</Tip>

### Build

```bash theme={null}
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DSOTTO_GPU=vulkan
cmake --build build -j$(nproc)

./build/sotto              # first run opens Settings
sudo cmake --install build # optional
```

whisper.cpp is fetched during configuration and linked statically, so the result is one binary.

<Note>
  **ROCm and unsupported GPUs.** If your card is not officially supported by ROCm, set
  `HSA_OVERRIDE_GFX_VERSION` before running — `10.3.0` works for many RDNA2 cards. If the ROCm
  build gives you trouble, Vulkan is a strong fallback.
</Note>

## First run

<Steps>
  <Step title="Download a model">
    Settings opens automatically. Nothing works until a speech model is installed.

    **Large v3 Turbo** (\~1.6 GB) is the recommended default on a discrete GPU. **Small** (\~488 MB)
    if you want something lighter. See [Speech models](/sotto/models).
  </Step>

  <Step title="Confirm the shortcut">
    KDE asks you to confirm the global shortcut binding — **Meta+Alt+D** by default. You can change
    or disable it at any time; it also appears in *System Settings → Shortcuts*.
  </Step>

  <Step title="Try it">
    Focus any text field, press the shortcut, talk, and press it again. Watch the pill at the bottom
    of your active screen.
  </Step>
</Steps>

## Desktop support

| Desktop                                | State                                                                                                    |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| **KDE Plasma / KWin (Wayland)**        | The primary target. Fully supported.                                                                     |
| Hyprland and other wlroots compositors | The overlay works; text injection needs ydotool. On the roadmap.                                         |
| GNOME                                  | Layer-shell is unsupported, so the overlay falls back to an ordinary always-on-top window. Portals work. |
| X11                                    | Works, with the fallback overlay positioned on the screen under the pointer.                             |

## Verifying your GPU is being used

The bottom of the Settings window names the active backend. If it says `cpu`, transcription will be
noticeably slow — rebuild with `-DSOTTO_GPU=vulkan` or `hip`.