simonw / ospeak

CLI tool for running text through OpenAI Text to speech

ospeak

CLI tool for running text through the OpenAI Text to speech API and speaking or saving the result

See ospeak: a CLI tool for speaking text in the terminal via OpenAI for background on this project.

Installation

Install this tool using pipx:

pipx install ospeak

Note, on MacOS there's a broken dependency with Python 3.12 so instead run:

pipx install --python /path/to/python3.11 ospeak

This tool also depends on ffmpeg. You can install that on macOS using Homebrew like this:

brew install ffmpeg

Note that ospeak has dependencies that are currently incompatible with LLM (see this issue) so the two tools need to be installed in different virtual environments, hence the recommendation to use pipx.

Usage

To get your computer to say something, run:

ospeak "Hello there"

You will need an OpenAI API key. You can set that as an environment variable:

export OPENAI_API_KEY="..."

Or you can pass it using --token:

ospeak --token "..." "Hello there"

You can pipe content into the tool:

echo "Hello there" | ospeak

Use -v/--voice VOICE to select a voice. The default is alloy. The other options are:

• echo
• fable
• onyx
• nova
• shimmer

You can pass -v all to hear all of the voices, each with the name of the voice spoken first.

ospeak "This is my voice" -v all

The -m/--model option can be used to select a different model. The default is tts-1. Use -m tts-1-hd for a higher quality model that takes slightly longer to generate audio:

ospeak "This is higher quality" -m tts-1-hd

To adjust the speed, pass -x/--speed with a value between 0.25 and 4 (the default is 1.0):

ospeak "This is my fast voice" -x 2

To write the audio to a file, pass -o/--output with a filename ending in either .mp3 or .wav:

ospeak "This is my voice" -o voice.mp3

This will not speak out loud. If you want it to also speak, add the -s/--speak option:

ospeak "This is my voice" -o voice.mp3 -s

ospeak --help

Usage: ospeak [OPTIONS] [TEXT]

  CLI tool for running text through OpenAI Text to speech

  Set the OPENAI_API_KEY environment variable to your OpenAI API key to avoid
  using the --token option every time.

  Example usage:

      ospeak "Everyone deserves a pelican" --voice alloy -x 1.5

Options:
  --version                       Show the version and exit.
  -v, --voice [alloy|echo|fable|onyx|nova|shimmer|all]
                                  Voice to use
  -m, --model TEXT                Model to use - defaults to tts-1
  -o, --output FILE               Save audio to this file on disk
  -x, --speed FLOAT RANGE         Speed of the voice  [0.25<=x<=4.0]
  -s, --speak                     Speak the text even when saving to a file
  --token TEXT                    OpenAI API key
  --help                          Show this message and exit.

Development

To contribute to this tool, first checkout the code. Then create a new virtual environment:

cd ospeak
python -m venv venv
source venv/bin/activate

Now install the dependencies and test dependencies:

pip install -e '.[test]'

To run the tests:

pytest