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,
**pastes the transcript straight into the focused app** (`ostt --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) |

For paste output on Wayland you also need `wtype` or `ydotool` (`xdotool` on
X11) — see the [OSTT docs](https://ostt.ai). Pick a transcription model once
with `ostt model` / `ostt auth`.

## 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` | `paste` | Where the transcript goes: paste into the focused app, or copy to the clipboard. |
| `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.