Skip to content

speak.md

Latest commit

 

History

History
176 lines (122 loc) · 4.93 KB

speak.md

File metadata and controls

176 lines (122 loc) · 4.93 KB
icon lucide/volume-2

speak

Convert text to speech using a local or remote TTS engine.

Usage

agent-cli speak [TEXT]

Description

A straightforward text-to-speech utility:

  1. Takes text from a command-line argument or your clipboard
  2. Sends the text to a TTS server
  3. Plays the generated audio through your speakers

Examples

# Speak from argument
agent-cli speak "Hello, world!"

# Speak from clipboard
agent-cli speak

# Save to file instead of playing
agent-cli speak "Hello" --save-file hello.wav

# List audio output devices
agent-cli speak --list-devices

Options

Provider Selection

Option Default Description
--tts-provider wyoming The TTS provider to use ('wyoming', 'openai', 'kokoro', 'gemini').

Audio Output

Option Default Description
--output-device-index - Audio output device index (see --list-devices for available devices).
--output-device-name - Partial match on device name (e.g., 'speakers', 'headphones').
--tts-speed 1.0 Speech speed multiplier (1.0 = normal, 2.0 = twice as fast, 0.5 = half speed).

Audio Output: Wyoming

Option Default Description
--tts-wyoming-ip localhost Wyoming TTS server IP address.
--tts-wyoming-port 10200 Wyoming TTS server port.
--tts-wyoming-voice - Voice name to use for Wyoming TTS (e.g., 'en_US-lessac-medium').
--tts-wyoming-language - Language for Wyoming TTS (e.g., 'en_US').
--tts-wyoming-speaker - Speaker name for Wyoming TTS voice.

Audio Output: OpenAI-compatible

Option Default Description
--tts-openai-model tts-1 The OpenAI model to use for TTS.
--tts-openai-voice alloy Voice for OpenAI TTS (alloy, echo, fable, onyx, nova, shimmer).
--tts-openai-base-url - Custom base URL for OpenAI-compatible TTS API (e.g., http://localhost:8000/v1 for a proxy).

Audio Output: Kokoro

Option Default Description
--tts-kokoro-model kokoro The Kokoro model to use for TTS.
--tts-kokoro-voice af_sky The voice to use for Kokoro TTS.
--tts-kokoro-host http://localhost:8880/v1 The base URL for the Kokoro API.

Audio Output: Gemini

Option Default Description
--tts-gemini-model gemini-2.5-flash-preview-tts The Gemini model to use for TTS.
--tts-gemini-voice Kore The voice to use for Gemini TTS (e.g., 'Kore', 'Puck', 'Charon', 'Fenrir').

LLM: Gemini

Option Default Description
--gemini-api-key - Your Gemini API key. Can also be set with the GEMINI_API_KEY environment variable.

Audio Input

Option Default Description
--list-devices false List available audio devices with their indices and exit.

General Options

Option Default Description
--save-file - Save audio to WAV file instead of playing through speakers.
--log-level warning Set logging level.
--log-file - Path to a file to write logs to.
--quiet, -q false Suppress console output from rich.
--json false Output result as JSON (implies --quiet and --no-clipboard).
--config - Path to a TOML configuration file.
--print-args false Print the command line arguments, including variables taken from the configuration file.

Process Management

Option Default Description
--stop false Stop any running instance of this command.
--status false Check if an instance is currently running.
--toggle false Start if not running, stop if running. Ideal for hotkey binding.

Available Voices

Wyoming (Piper)

List available voices:

# Check Piper documentation or run with verbose logging
agent-cli speak --log-level DEBUG "test"

Common voices:

  • en_US-lessac-medium - US English, natural
  • en_GB-alan-medium - British English
  • de_DE-thorsten-medium - German

OpenAI

  • alloy, echo, fable, onyx, nova, shimmer

Kokoro

  • af_sky, af_bella, am_adam, and more

Gemini

  • Kore (default), Puck, Charon, Fenrir

Use Cases

Read Clipboard Aloud

agent-cli speak

Speed Up Audio

agent-cli speak "Long text here" --tts-speed 1.5

Save for Later

agent-cli speak "Important reminder" --save-file reminder.wav