Awwdio

Awwdio provides a http interface to the mac say command so you can have other services speak to you.

Usage

pip install poetry -U

[clone, jump into directory]

poetry install
poetry run awwdio - start

— or —
poetry run awwdio --timevoices '["timevoice-market.json"]' --audiolib '["audiolib.json"]' - start

— or adjust the API host and port —
poetry run awwdio --audiolib '["audiolib.json"]' - start --host 0.0.0.0 --port 9994

You can optionally provide multiple filenames of timed events and multiple filenames of audio libraries. A timevoice sample schedule is provided for US stock market timed events (roughly).

API

The API is simple.

There are two endpoints:

/say?voice=X&say=Y&speed=Z&deadline=epoch&prio=N
- voice is an installed macos voice (System Settings -> Spoken Content -> System voice -> Manage Voices...)
  - can also be viewed with command line say -v\?
- say is the phrase to speak
- speed is the speech rate
- deadline is an optional epoch timestamp where the event must be spoken BEFORE the timestamp or the message is dropped
- prio is an optional integer where the speech request will be attempted before lower priorities. lower numbers are higher priority. default priority is 100 if not provided.
- All those options have defaults, so you can just call /say and it will do something.
/play?sound=X
- sound is a sound key defined in one of your audiolib mappings.
- if no sound is provided, a random sound is played. if a non-existing sound key is requested, nothing happens.

Nice Features

Speech Deduplication / Debouncing

One nice feature is the speech endpoint automatically deduplicates requests if they arrive too quickly.

Here, instead of saying "thanks for the memories" 7 times in a row, it says "thanks for the memories — repeated 7" once (or, if the timing is off, it may say "repeated 6" then repeat another full one, but it's close enough).

for i in {1..7}; do curl localhost:8000/say\?say=thanks-for-the-memories; done

Random Sound Playing

If no specific sound is provided, a random sound is chosen and played:

curl localhost:8000/play

TODO

Add optional authentication so you could open your speak engine to public IPs without worrying about unwanted API calls
Add ability for sounds to be URLs and fetched/cached on startup automatically (current demo sounds are from https://mixkit.co/free-sound-effects/)
Add marketplace or contrib directory for sound libraries and timevoice libraries
Improve timevoice parser to allow specific date-at-time events instead of just daily repeating events
Add simple client library so other apps can just call something like await awwdio.Client(host, port, authtoken).speak("my cabbages!")
Add more sound options instead of just using pygame to play sounds (look into adding synthesizer and pychord)
Add ability for timed sounds with [start, interval, stop] durations too (e.g. "starting at 2pm, sound a ding every 20 seconds, stop at 2:15pm")

mattsta / awwdio