noctalia-ostt/README.md

# OSTT

Voice-to-text for the Noctalia bar, powered by
[OSTT](https://github.com/kristoferlund/ostt).

Click the microphone (or bind a hotkey) to start recording — the capsule turns
into a red record indicator with an elapsed timer while the microphone is
live. Click again to stop: OSTT transcribes the audio and, by default,
**copies the transcript to your clipboard** (`ostt -c`) — ready to paste.
No popup terminal is spawned; the recorder runs headlessly and the bar capsule
is the only UI.

The indicator also lights up for recordings started outside Noctalia (e.g. an
`ostt launch` hotkey), since the plugin watches OSTT's own runtime state.

## Plugin

| Field | Value |
| --- | --- |
| ID | `prdlk/ostt` |
| Entries | Bar widget: `recorder`; service: `monitor` |
| Requires | [`ostt`](https://ostt.ai/guide/installation), `script` (util-linux), `wl-clipboard` on Wayland (`xclip` on X11) |

Pick a transcription model once with `ostt model` / `ostt auth`.

### Output modes

**Clipboard (default)** — `ostt -c` copies the transcript with `wl-copy`
(Wayland) or `xclip` (X11). Paste it anywhere with your normal paste; the
transcript is also readable from scripts via `wl-paste`.

**Paste (opt-in)** — `ostt --paste` copies the transcript, then injects a
single paste shortcut (`wtype`/`ydotool`/`xdotool`) into the focused app. Per
the [OSTT docs](https://ostt.ai/guide/configuration#paste-output) it sends
exactly one configurable key — default `ctrl+v` — and cannot detect success,
so it silently does nothing in apps with a different paste binding (terminals
usually want `ctrl+shift+v`). Tune `[output.paste] paste_key` in
`~/.config/ostt/ostt.toml` before enabling it.

## Usage

Add the **OSTT** widget from the Add-widget picker.

| Interaction | Action |
| --- | --- |
| Left click | Start recording / stop & transcribe |
| Right click | Cancel the in-flight session (no transcription) |

Widget states: mic glyph (idle) → red filled mic + `m:ss` timer (recording) →
spinner (transcribing).

## Settings

| Setting | Type | Default | Description |
| --- | --- | --- | --- |
| `output_mode` | `select` | `clipboard` | Where the transcript goes: copy to the clipboard, or paste into the focused app. |
| `model` | `string` | *(empty)* | Optional `provider/model` override (e.g. `deepgram/nova-3`, `whisper/turbo`). Empty uses the model selected with `ostt model`. |
| `process_action` | `string` | *(empty)* | Optional post-processing action id from `ostt.toml` (`ostt -p <action>`). |
| `show_elapsed` | `bool` | `true` | Show the elapsed timer while recording. |
| `notify_on_done` | `bool` | `true` | Notify when the transcript has been delivered. |
| `extra_args` | `string` | *(empty)* | Advanced: appended verbatim to `ostt record` (e.g. `--param language=sv`). |

## Hotkeys (IPC)

The widget exposes IPC events for compositor keybinds:

```sh
noctalia msg plugin prdlk/ostt:recorder focused toggle   # start / stop & transcribe
noctalia msg plugin prdlk/ostt:recorder focused start
noctalia msg plugin prdlk/ostt:recorder focused stop
noctalia msg plugin prdlk/ostt:recorder focused cancel
```

Example (niri):

```kdl
Mod+Space { spawn "noctalia" "msg" "plugin" "prdlk/ostt:recorder" "focused" "toggle"; }
```

## How it works

- OSTT's recorder is a TUI, so the widget runs it inside a throwaway pty via
  `script(1)` — headless, no window.
- Stopping uses OSTT's external-trigger contract: `SIGUSR1` finishes the
  recording and runs transcription (the same mechanism `ostt launch` uses).
- The `monitor` service polls `$XDG_RUNTIME_DIR/ostt/recording.pid`
  (liveness-checked) and publishes `idle / starting / recording / transcribing`
  to the widget, plus an exit-code file written by the pty wrapper so failed
  transcriptions surface as error notifications.