## Transcribe live audio

**Before you start:** prepare a speech model that runs on this computer. Prepare the speaker model as well if you need separate voice labels. Test the input and permissions before an important conversation.

Discover the available inputs:

```sh
olenji live sources --json
```

| Source | Command value | What must stay open |
| --- | --- | --- |
| Default computer microphone | `microphone` | The Olenji service. A separate viewer can close. |
| Another native input device | `device:NUMBER` | The service. Use a device number returned by source discovery. |
| Supported system output | `system` | The service and the supported operating-system capture route. |
| This browser's microphone | `browser` | The tab that supplies the microphone, plus the service. |

System audio is audio played by your computer. It is not the same as your microphone. The reviewed start command selects **one source**; it does not promise simultaneous microphone-and-system tracks, per-app capture, or arbitrary browser-tab audio capture.

### Dictate into your focused textbox

**Available in version 1.4.0:** configurable Hold/Toggle mappings, physical-key setup, guarded microphone selection, native feedback, explicit macOS live textbox delivery and bounded recovery. Check the connected version and capabilities. Publication and device acceptance are separate from a successful source/build review.

Ask your local agent: “Use Right Option to write what I say into the field where I’m composing. Don’t send it.” First prepare the selected speech model. In **Settings → Dictation keys and delivery → Set up shortcut**, choose the physical key and **Primary gesture**, model, language, microphone and delivery. Use **Add another key mapping** for independent Hold/Toggle keys, up to eight additional mappings (nine total). The shortcut's model is shown separately from the workspace default. A focused key recorder captures your chosen key until release; Escape, Tab or leaving the recorder cancels it. Check the service computer's capability matrix rather than assuming every browser key works globally.

On a live-capable Mac, **Use Right Option + live typing + popup** explicitly chooses Right Option, insertion, live timing and native feedback. It keeps the existing gesture and additional mappings; choose those separately. Otherwise select each choice below it. **Prepare setup command** generates a command for your local agent or terminal and moves keyboard focus to the command so you can review and copy it. Removing a key mapping keeps focus in the remaining mappings or returns it to **Add another key mapping**. The page cannot enable global monitoring directly through its paired connection. With a prepared model, you can also use:

```sh
olenji hotkey set right_alt --activation toggle --binding hold:ctrl+alt+space --model faster-whisper.tiny --delivery insert --delivery-timing live --feedback --json
olenji hotkey status --json
```

This example uses Right Option for tap-to-toggle and Control–Option–Space for hold-to-speak, with macOS live textbox updates. Use different supported keys or remove the additional binding. Each key has its own gesture; duplicate or overlapping physical shortcuts are refused, including `alt+a` with `right_alt+a` or `ctrl+alt` with `alt+ctrl`. Omit `--activation` for hold, omit `--delivery-timing live` for final-only insertion, and omit `--delivery insert` to keep the established transcript-only default. Setting a shortcut downloads nothing and starts no recording. Omit input selection to follow the named OS default; explicitly choose a numbered native input with `--input-device` to save an ID and observed-name check. Pair it with `--input-device-name` to check the name seen during setup before applying that ID; the browser-generated command includes both. If that input disappears or its ID changes, Olenji refuses the activation instead of silently selecting another microphone. Device discovery opens no microphone and proves neither permission nor incoming audio.

Each recording keeps a transcript in Olenji, including when text is inserted elsewhere. **Retain dictation audio** is off by default; opt in for playback and later refinement. **Keep Olenji-managed processing local** is on by default. This controls Olenji's processing; an external agent that receives your transcript has its own processing boundary. All key mappings share these choices.

| Physical choice | Meaning and limits |
| --- | --- |
| `right_alt`, `left_alt`, `alt` | Right Option/Alt, Left Option/Alt, or either side. A sided trigger rejects the opposite side; either-side allows both. |
| `ctrl+right_alt` | Hold Right Option/Alt after Control. The final stated modifier is the trigger. |
| `alt+right` | Option/Alt plus Right Arrow, distinct from Right Option alone. |
| Modified ordinary/navigation/numpad keys | Supported keys depend on the desktop. Plain typing keys stay refused. Letter/digit chords follow the current layout; non-ASCII characters are refused rather than guessed from US key-code names. Record again after a layout change. |
| Function keys and Fn | Parser F1–F24; Mac F1–F20 and hardware Fn; Windows refuses F12. Fn/top-row settings need a device test. Media and mouse triggers are unsupported. |

macOS and Windows physical modifier bindings listen without consuming normal shortcuts, so beginning another Option shortcut can also start a modifier-only recording. Choose a chord if that would be disruptive. Legacy Windows registered chords consume their shortcut. X11 consumes its trigger key and can affect the key's usual shortcuts. Wayland uses the desktop-approved Global Shortcuts portal, cannot request physical sides/modifier-only identity and never falls back to XWayland. Inspect `binding.trigger_description` for its approved chord. A pending approval is not listening.

Use a local interactive desktop. macOS requires Input Monitoring and Microphone; insertion adds Accessibility. Grant access to the actual executable/app identified in System Settings → Privacy & Security, then re-enable. Olenji cannot grant access or guarantee a prompt. Linux insertion requires AT-SPI; Windows currently saves transcripts only.

Focus the original ordinary writable field with an empty selection. With Hold, keep the key down while speaking and release to finish. With Toggle, press and release once to start, then press again to finish. A second binding cannot start a concurrent recording. The recording deadline applies to both gestures, including while the toggle key is up.

**Live textbox delivery (macOS):** under **Where your words go**, choose **Insert into the original supported field**, then select **Live text while speaking** under **Text delivery timing**. This requires `delivery.capabilities.live_supported:true`. Words appear as buffered recognition produces them and may change or shrink. Olenji replaces only its own draft span. Keep the same field and caret; typing, selecting, moving the caret, switching fields or a capture/delivery fault stops further updates. The helper privately reads up to 200,000 UTF-16 units of the full field value to detect changes; target contents stay out of status, logs, durable delivery metadata and the popup. Cancellation may leave the last draft visible for review. No automatic rollback or uncertain retry occurs. Accessibility does not provide an atomic edit transaction; test your actual application. Linux live textbox delivery is unavailable; choose final-only there.

**Final-only delivery:** select **Final text after stopping**. Insertion waits for clean completed recognition, checks that the same field is still focused, and writes once at its current empty caret. Olenji does not freeze the entire draft or caret during recognition. It never presses Enter/Send, uses the clipboard or replaces selected text. macOS requires writable selected text and range queries; it reads no surrounding draft and confirms only the newly inserted Unicode span. There is no atomic transaction between the saved transcript and the external application. Empty, failed or interrupted recognition is not inserted. Unsupported/failed delivery keeps the transcript. Inspect uncertain delivery before any retry; disable cannot retract text already written. No old utterance is replayed.

On macOS, **Show native desktop feedback** is enabled unless previously disabled. The optional native popup shows starting, connected recording with level/elapsed time, processing, insertion and saved/failure/uncertain outcomes without raising a browser or displaying dictated text. `--no-feedback` disables it. The click-through panel does not take focus. A stale level is shown as unavailable; indicator failure is separate from capture. Other desktops can inspect the status card. The browser updates actual application version and offers an explicit Open transcript action; it does not auto-select or raise sessions.

Check `effective_state`, `listening`, capture connection and error. `enabled` preserves your requested setting; it does not prove readiness. Recording requires an actually connected owned microphone. Processing follows the exact finalization job. Before relying on setup, test every configured gesture with real speech, visible recording/processing and the intended output in your actual application. A permission hint, key recorder or native handshake alone is insufficient.

Secure Input keeps the enabled binding **suspended**. Leave the protected context and release the key; Olenji tries fresh listener handshakes after delays of 1, 2, 4, 8, 16 and 30 seconds, at most six attempts per episode. A successful handshake needs a new deliberate press. Exhaustion needs explicit re-enable. Permission, layout, disconnect and other faults require repair/re-enable. Recovery never resumes audio or insertion and never bypasses secure input.

The maximum recording time for either gesture defaults to 120 seconds and can be set up to 600 with `--max-hold-seconds`. Repeats, preheld keys and extra-modifier changes cannot start an unexpected recording; release all primary sides before pressing again. For Hold, release during startup closes the owned source as startup unwinds; Toggle uses its next deliberate press to stop. Wait for finalization before the next activation; busy work is not queued as a surprise recording. A saved binding restores when the service starts, not an interrupted recording. Login startup is not installed.

```sh
olenji hotkey disable
```

Disable cancels recovery, unbinds and finalizes only owned capture. Retry incomplete cleanup when status asks; other recordings continue. New Mac/Windows physical-key, microphone, field and HUD behavior still needs native acceptance. Earlier TextEdit/F20 results belong to their exact older artifacts; Linux controlled tests and Xvfb input do not certify your Mac permissions or focus.

### Start and monitor a recording

For your computer microphone:

```sh
olenji live start --source microphone --retain-audio --open
```

For a microphone supplied by the browser:

```sh
olenji live start --source browser --retain-audio --open
```

Use the tab's microphone control and approve the browser's permission request. Starting a session does not itself grant permission or send audio. Check the input meter and the arrival of transcript text before relying on the recording.

The saved model preference is used unless you specify `--model`. Add `--diarize` after preparing the speaker model. Keep the returned session ID.

### Pause, resume, and stop

```sh
olenji live pause SESSION_ID
olenji live resume SESSION_ID
olenji live stop SESSION_ID
olenji live status SESSION_ID --json
```

Pause stops new capture temporarily. Stop finishes the session and flushes accepted audio. If stop returns a finalization job, wait for that job before exporting the final transcript.

Closing a viewer or detaching the terminal does **not** stop service-owned recording. Closing the tab supplying browser-microphone audio removes that audio source. Use `live stop` to end work deliberately rather than killing the service.

### What to expect from live text

Draft words can change. Completed turns are saved, but later corrections can still revise them. Text appears after buffered speech is processed; this build does not promise instantaneous captions or the same delay on every model.

A reported audio gap means some audio was missing. Olenji records the gap; it cannot recreate words it never received. A model with “streaming” in its name does not by itself establish a continuous decoder inside this app.

Linux system capture requires a supported PulseAudio/PipeWire setup and tools. Windows uses its WASAPI loopback route. macOS uses a ScreenCaptureKit helper and recording permission. See [Check platform support](/docs/1.4.0/source/#source-0278c0a6b2023dd5963d) for the remaining hardware checks.