The Inference Gateway CLI can turn speech into text in two places:

• Chat mode - the /voice shortcut records your microphone, transcribes it, and drops the text into the input field.
• Channels mode - inbound Telegram voice messages are transcribed to text before the agent sees them, so you can talk to the agent from your phone.

Both use a local whisper.cpp binary and run fully offline once the model is downloaded. The feature is disabled by default because the model download can take time and the runtime depends on external tools.

Note: Speech-to-text shells out to whisper.cpp and ffmpeg - no CGO is added to the infer binary. When a required tool is missing, the CLI reports an actionable error naming what to install; it never fails silently.

Speech-to-text relies on two external programs:

On Linux, arecord (ALSA) or sox can substitute for ffmpeg for microphone capture. See Platform notes for details.

Add a speech_to_text section to .infer/config.yaml (project) or ~/.infer/config.yaml (user):

speech_to_text:
  enabled: true # feature flag (default: false)
  engine: whisper.cpp # transcription engine
  model: tiny # tiny | base | small | medium | large-v3-turbo | *.en (default: tiny)
  language: '' # ISO code (e.g. "en"); empty = auto-detect
  auto_download: true # download the model on first use if missing
  max_recording_seconds: 30 # /voice hard recording cap
  silence_timeout: 2 # stop /voice this many seconds after you go quiet (0 = record full cap)
  # Optional overrides:
  binary_path: '' # explicit whisper-cli/whisper-cpp path; empty = resolve on PATH
  ffmpeg_path: '' # explicit ffmpeg path; empty = resolve on PATH
  models_dir: '' # where models are cached; empty = ~/.infer/models/whisper
  input_device: '' # microphone device; empty = platform default
  timeout: 120 # transcription timeout (seconds)

Every field can also be set via an INFER_SPEECH_TO_TEXT_* environment variable - see Environment variables.

All options live under speech_to_text in .infer/config.yaml:

Every YAML key has an INFER_SPEECH_TO_TEXT_-prefixed environment variable that takes precedence over the config file.

For example:

export INFER_SPEECH_TO_TEXT_ENABLED=true
export INFER_SPEECH_TO_TEXT_MODEL=base

The GGML model is downloaded on first use from huggingface.co/ggerganov/whisper.cpp and cached under ~/.infer/models/whisper/ (e.g. ggml-tiny.bin). Larger models are more accurate but slower and heavier:

Append .en (e.g. base.en) for English-only variants. You can also pass a full filename (ggml-small.bin), or place a model in models_dir manually and set auto_download: false to skip the download.

The /voice shortcut records audio from your microphone, transcribes it locally, and places the text into the input field - ready to review and send. It only appears when speech_to_text.enabled is true.

1. Type /voice and press Enter - recording starts immediately.
2. Speak. Recording stops automatically about silence_timeout seconds after you go quiet, at the max_recording_seconds cap, or when you pass a per-call override like /voice 8. Set silence_timeout: 0 to always record the full cap instead.
3. Review and edit the transcription in the input field, then press Enter to send.

Under the hood, /voice shells out to ffmpeg (or arecord/sox on Linux) to capture 16 kHz mono audio, then to the whisper-cli/whisper-cpp binary to transcribe it. The first run downloads the model; subsequent runs use the cache. See the Shortcuts section of the CLI docs for the full shortcut list.

When speech_to_text.enabled is set and you run infer daemon, voice notes sent to your Telegram bot are downloaded, decoded with ffmpeg (OGG/Opus to WAV), transcribed, and forwarded to the agent as text - so you can talk to the agent from your phone.

When speech-to-text is disabled, inbound voice messages are ignored (the previous behavior). Text and image messages are unaffected either way. See Channels for Telegram setup and access control.

Microphone capture is platform-specific. The defaults work out of the box on most systems; override input_device only when you need a non-default microphone.

ffmpeg captures audio through avfoundation. With input_device empty, the system default microphone is used. To target a specific device, list the available inputs and set input_device to the index:

ffmpeg -f avfoundation -list_devices true -i ""

Grant microphone permission to your terminal (System Settings - Privacy & Security - Microphone), otherwise capture produces silence.

ffmpeg captures through ALSA or PulseAudio. If ffmpeg microphone capture is unavailable on your system, install arecord (ALSA) or sox as a fallback - the CLI will use whichever capture tool it finds. Install the decoder/encoder with your package manager, e.g. apt install ffmpeg.

• CLI - overview of the infer command-line tool, chat mode, and shortcuts
• Channels - Telegram setup, access control, and how inbound messages reach the agent
• Text-to-Speech - the reverse direction, local speech synthesis and voice cloning
• Configuration - full configuration system across the gateway and CLI
• whisper.cpp - the local transcription engine