omni

A command line interface for real-time transcription.

Install

# npm. macOS, Linux, WSL.
npm i -g @ahkohd/omni

# Homebrew. macOS or WSL.
brew install ahkohd/omni/omni

# Verify the install.
omni --version

Quick start

omni start
omni doctor
omni transcribe start
# speak, then stop:
omni transcribe stop
omni stop

Backend setup

omni streams audio to any server that speaks the OpenAI Realtime protocol.

• vLLM. Recommended backend.

  vllm serve repo/model --served-model-name model --port 1237
  omni config set server.baseUrl http://127.0.0.1:1237/v1
  omni config set server.model model

• LocalAI.
• Speaches. OpenAI-compatible realtime server with a transcription-only mode.
• OpenAI API.

  omni config set server.baseUrl https://api.openai.com/v1
  omni config set server.apiKey sk-...
  omni config set server.model gpt-4o-transcribe

Activation options

Use CLI commands directly, scripts, or your existing launcher and keybind setup.

skhd

cmd + alt - r : omni transcribe start --background
cmd + alt - c : omni transcribe stop copy
cmd + alt - i : omni transcribe stop insert

If you prefer your own launcher, bind one action for start and one for the stop mode you want:

omni transcribe start --background
omni transcribe stop insert

Commands

• omni start / stop / status / reload / doctor. Daemon lifecycle and health checks. stop also terminates the spawned omni-transcribe-ui client.
• omni transcribe start. Begin recording. Add --background for keybind flows.
• omni transcribe stream --jsonl. JSONL live transcript stream.
• omni transcribe file <path>. Transcribe an audio file. Supports flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm. Add --json or --output <path>.
• omni transcribe stop [mode]. Stop and run hooks. Examples: stop copy, stop insert.
• omni transcribe status. Recording state, duration, transcript preview.
• omni input show / input list / input set <id> / input set --name "<device>". Mic selection. input set auto-reloads the daemon when running.
• omni config .... Read or write config.

Useful flags:

• --json for machine-readable output.
• --output <path> on transcribe file to write text or JSON to a file.
• --debug and --debug-json for live diagnostics.

Configuration

Config path: ~/.config/omni/config.toml

[server]
llmApi = "openai-realtime"
baseUrl = "http://127.0.0.1:4077/v1"
apiKey = ""
model = "model"

[dictation]
replacements = ["Licensestead", "Turso"]
expansions = [
  { trigger = "my email", text = "[email protected]" },
]

[event.hooks.transcribe]
start = ["show_ui"]
stop = ["hide_ui", "copy"]
stop_insert = ["hide_ui", "stash", "copy", "paste", "sleep 120", "unstash"]

omni config path
omni config show
omni config get <dot.key>
omni config set <dot.key> <value>
omni config set <dot.key> '<json>' --json-value
omni config unset <dot.key>

Replacements & Expansions

Apply deterministic text transforms before streaming output.

[dictation]
# heard text to intended spelling.
replacements = ["JavaScript", "Turso", "AI"]

# trigger phrase to inserted text.
expansions = [
  { trigger = "my email", text = "my email ([email protected])" },
  { trigger = "AI", text = "Artificial Intelligence" },
  { trigger = "LGTM", text = "looks good to me" },
]

Replacements also accept explicit aliases:

[dictation]
replacements = [
  { term = "macOS", aliases = ["mac os", "mac oh ess"] },
  { term = "TypeScript", aliases = ["type script"] },
]

Hooks

Hooks let you decide what happens during and after transcription. Run built-in actions, your own scripts, or both.

Built-in actions:

• show_ui. Show transcription UI.
• hide_ui. Hide transcription UI.
• copy. Copy transcript to clipboard.
• paste. Paste into focused app.
• stash. Save current clipboard before overwriting.
• unstash. Restore previously stashed clipboard.
• sound. Play a sound.
• sleep <ms>. Pause hook execution for N milliseconds.

Hook recipes

[event.hooks.transcribe]
# default start
start = ["show_ui"]

# custom start mode
start_meeting = ["./hooks/start-meeting.sh"]

# default stop
stop = ["hide_ui", "copy"]

# copy-only mode
stop_copy = ["copy"]

# default insert mode, clipboard-safe
stop_insert = ["hide_ui", "stash", "copy", "paste", "sleep 120", "unstash"]

# custom stop mode via script
stop_slack = ["./hooks/slack-send.sh"]

Troubleshooting

• Run omni doctor first.
• If transcription fails, ensure the daemon is running: omni status.
• If mic input is wrong, inspect and set the device:
  • omni input list
  • omni input set <id>
• On macOS, grant microphone and accessibility permissions when prompted.
• On Linux and WSL, install clipboard helpers for hook builtins:
  • wl-copy and wl-paste from wl-clipboard, or xclip, for copy, stash, unstash.
  • wtype on Wayland, or xdotool on X11, for paste.
• For live diagnostics, use omni transcribe start --debug.