Home Original page

GitHub - rbright/sotto: Local-first speech-to-text CLI

CI

Local-first speech-to-text CLI.

sotto captures microphone audio, streams to a local ASR backend (Riva by default), assembles transcript text, and commits output to the clipboard with optional paste dispatch.

Why this exists

  • single-process CLI (no daemon)
  • local-first by default (localhost Riva endpoints)
  • explicit state machine (toggle, stop, cancel)
  • deterministic config + observable runtime logs

Feature summary

  • single-instance command coordination via unix socket
  • audio capture via PipeWire/Pulse
  • streaming ASR via NVIDIA Riva gRPC
  • transcript normalization + sentence capitalization + optional trailing space
  • output adapters:
    • clipboard command (clipboard_cmd)
    • optional paste command override (paste_cmd)
    • default Hyprland paste path (hyprctl sendshortcut) when paste_cmd is unset
  • indicator backends:
    • hypr notifications
    • desktop (freedesktop notifications, e.g. mako)
  • embedded cue WAV assets for start/stop/complete/cancel (not user-configurable)
  • built-in indicator localization scaffolding (English catalog currently shipped)
  • built-in environment diagnostics via sotto doctor

Platform scope (current)

sotto is currently optimized for Wayland + Hyprland workflows.

  • default paste behavior uses hyprctl
  • doctor currently checks for a Hyprland session

You can still reduce Hyprland coupling by using:

  • indicator.backend = desktop
  • paste_cmd = "..." (explicit command override)

Install

Nix (recommended)

nix build 'path:.#sotto'
nix run 'path:.#sotto' -- --help

From source

just tools
go test ./apps/sotto/...
go build ./apps/sotto/cmd/sotto

Quickstart

sotto doctor
sotto toggle   # start
sotto toggle   # stop + commit

Core commands:

sotto toggle
sotto stop
sotto cancel
sotto status
sotto devices
sotto doctor
sotto version

Configuration

Config resolution order:

  1. --config <path>
  2. $XDG_CONFIG_HOME/sotto/config.jsonc
  3. ~/.config/sotto/config.jsonc

Compatibility note:

  • if the default .jsonc file is missing, sotto will fall back to legacy config.conf automatically.

See full key reference and examples in:

Verification

Required local gate before hand-off:

just ci-check
nix build 'path:.#sotto'

Manual/local runtime checklist:

Architecture and design docs