Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/simonw/ospeak
CLI tool for running text through OpenAI Text to speech
https://github.com/simonw/ospeak
openai openai-api text-to-speech
Last synced: 9 days ago
JSON representation
CLI tool for running text through OpenAI Text to speech
- Host: GitHub
- URL: https://github.com/simonw/ospeak
- Owner: simonw
- License: apache-2.0
- Created: 2023-11-07T03:23:30.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2023-12-13T06:12:17.000Z (11 months ago)
- Last Synced: 2024-05-01T23:17:38.539Z (6 months ago)
- Topics: openai, openai-api, text-to-speech
- Language: Python
- Homepage:
- Size: 34.2 KB
- Stars: 140
- Watchers: 7
- Forks: 7
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ospeak
[](https://pypi.org/project/ospeak/)
[](https://github.com/simonw/ospeak/releases)
[](https://github.com/simonw/ospeak/actions?query=workflow%3ATest)
[](https://github.com/simonw/ospeak/blob/master/LICENSE)
CLI tool for running text through the [OpenAI Text to speech](https://platform.openai.com/docs/guides/text-to-speech) API and speaking or saving the result
See [ospeak: a CLI tool for speaking text in the terminal via OpenAI](https://simonwillison.net/2023/Nov/7/ospeak/) for background on this project.
## Installation
Install this tool using `pipx`:
```bash
pipx install ospeak
```
Note, on MacOS there's a [broken dependency](https://github.com/simonw/ospeak/issues/4) with Python 3.12 so instead run:
```bash
pipx install --python /path/to/python3.11 ospeak
```
This tool also depends on `ffmpeg`. You can install that on macOS using [Homebrew](https://brew.sh/) like this:
```bash
brew install ffmpeg
```
Note that `ospeak` has dependencies that are currently incompatible with [LLM](https://llm.datasette.io) (see [this issue](https://github.com/simonw/llm/issues/325)) so the two tools need to be installed in different virtual environments, hence the recommendation to use [pipx](https://pypa.github.io/pipx/).
## Usage
To get your computer to say something, run:
```bash
ospeak "Hello there"
```
You will need an OpenAI API key. You can set that as an environment variable:
```bash
export OPENAI_API_KEY="..."
```
Or you can pass it using `--token`:
```bash
ospeak --token "..." "Hello there"
```
You can pipe content into the tool:
```bash
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.
```bash
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:
```bash
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):
```bash
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`:
```bash
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:
```bash
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:
```bash
cd ospeak
python -m venv venv
source venv/bin/activate
```
Now install the dependencies and test dependencies:
```bash
pip install -e '.[test]'
```
To run the tests:
```bash
pytest
```