Dictare / Docs / Tray App

Tray App

The tray app provides a persistent status icon in your menu bar (macOS) or system tray (Linux). It shows the current engine state and gives quick access to common actions.

Starting the Tray

The tray starts automatically when you install dictare as a service. You can also manage it manually:

dictare tray start    # Start the tray app
dictare tray stop     # Stop it
dictare tray status   # Check if running

Icon States

Icon State Meaning
Purple Active Engine is running, listening for voice
Gray Off Engine is running but not listening
Pulsing Loading Engine is starting up or loading models
Dimmed Disconnected Engine is not reachable

Right-click (or click on Linux) the tray icon to access:

  • Status — shows the current engine state (off, listening, recording)
  • Start/Stop Listening — toggle voice recognition on or off
  • Output: Agents/Keyboard — switch between agent mode and keyboard mode
  • Current: \<agent> — submenu to switch the active agent
  • Advanced — additional engine controls
  • Settings... — opens the web-based settings UI in your browser
  • About Dictare... — version info and credits
  • Quit — stops the tray app (engine keeps running)

Settings UI

Clicking Settings... opens a browser-based configuration panel served by the engine at http://localhost:8770. From here you can configure:

  • STT model and language
  • TTS engine and voice
  • Hotkey binding
  • Audio devices (input/output)
  • Agent profiles
  • Pipeline filters

Changes are saved to ~/.config/dictare/config.toml and take effect immediately.

Platform Notes

macOS

  • The tray icon appears in the menu bar (top-right)
  • The tray is managed by the launchd service — it starts automatically with the engine
  • Uses NSStatusItem for native macOS appearance

Linux

  • Requires a desktop environment with system tray support (GNOME, KDE, XFCE, etc.)
  • Tray dependencies (libappindicator, PyGObject) are installed automatically by the install script
  • On GNOME, you may need the AppIndicator extension for tray icons to appear
  • The tray must run in a graphical session — it won't work over SSH without display forwarding

Troubleshooting

Tray icon not visible (macOS) Restart the tray: dictare tray stop && dictare tray start

Tray icon not visible (Linux/GNOME) Install AppIndicator support: sudo apt install gnome-shell-extension-appindicator and enable it in GNOME Extensions.

"Tray failed to start" error Check that you're in a graphical session (echo $DISPLAY). The tray cannot run in a headless/SSH-only environment.

Settings page doesn't open Ensure the engine is running: dictare service status. The settings UI is served by the engine on port 8770.