The goal of this project is to provide a simple to use Text to Speech IRC bot. It's mainly focused on Twitch, but might be easily adapt to other IRC chats as well. Anyway, right now some parts are Twitch specific (like `CAP REQ :twitch.tv/commands twitch.tv/tags`). There are some other projects providing TTS for IRC based chats, like [IRC Radio (TTS)](https://play.google.com/store/apps/details?id=com.earthflare.android.ircradio&hl=en&gl=US), but they are missing moderation features like Black-/Whitelists or deletion of single messages, before they are read. Therefore I created my own TTS bot, providing those features.
The project consits of a very simple IRC client, which monitors the incoming messages. If a valid⃰ `!tts` command is detected the message will send into a queue. Depending on your config it will wait there a few seconds for deletion by you/your moderators. If nobody deletes the message, it will send into another queue. This queue will get fetched by the HTML frontend, which will be delivered by an internal webserver (backend). The HTML frontend will use the [Web Speech API](https://wicg.github.io/speech-api/) included in any modern webbrowser to read the incoming TTS message. When this is done it will report back to the webserver and the message will be removed from the queue.
The server part is written in Python. The TTS part is written in Javascript.
By using Javascript for the actual TTS part it's not only very easy to access the Web Speech API and the underlying Speech features of your OS, it also makes it possible to use a wide range of devices to actually play the TTS output. You can start the backend on your PC/Server and open the frontend on your Android/iOS tablet or Mobile Phone. If you expose the backend to the internet (I would recommend to use a reverse proxy, rather than exposing the backend directly) you can also use the TTS bot on the go (e.g. your IRL setup).
(⃰sender is not on the blacklist, message is not too long, etc.)
## Getting Started
### Dependencies
* Browser with Web Speech API support
* Web Speech API Voices (usually already included in your OS and/or browser)
* If you use `tts.py` see `requirements.txt`. If you use `tts.exe` all dependencies are included.
### Installing
1. Clone the repo, or download and unzip the newest [Release](https://gitlab.com/gpvkt/twitchtts/-/releases)
You can generate your `oauth_token` by leaving the value empty when starting `tts.exe/tts.py`. The integrated webserver will then provide an OAuth-Generator. Due to limitations to the `redirect_url` parameter used by twitch, this is only possible if you use Port `8080` or `80` as `http:bind`. If you use a different port, you will need to use another [Twitch OAuth Generator](https://html.duckduckgo.com/html/?q=twitch+oauth+token+generator). The bot will need `chat:edit` and `chat:read` permissions.
Please note that the `oauth_token` is valid for approximately 60 days. If it become invalid the bot will not connect anymore and you will have to renew the token.
Use this section to define key:value pairs of usernames. The first value is the Twitch username, the second value is how the bot should pronouce the user, when reading the message. This is helpfull if you have regulars with numbers or strangs chars in the name. You can add new/change entries on the fly without restarting the bot (changes took up to 60 seconds).
You can add a whitelist section to `config.yml`, a whitelist will override any other settings like `subonly` and `modonly`. Only users on the whitelist are allowed to use `!tts`. Broadcasters and mods can temporarily add users (including themselfs) to the whitelist by using the `!ptts` command, though.
To disable the whitelist, remove it from `config.yml` completely. If you just leave `whitelist:` without entries, everyone must be whitelisted using `!ptts` (even broadcaster and mods). The permit is temporary until the bot restarts or (whichever happens first) if the user is removed from the whitelist using `!dtts`.
Execute `tts.exe` (or `tts.py` if you have Python installed), open the TTS webpage in your browser (the URL depends on your `bind` and `port` configuration, usually it's just `http://localhost`). Click the `Init` button at the button of the TTS webpage (you should hear `Init complete`).
Connect to the configured Twitch channel and send a message starting with `!tts`. After a few seconds (depending on your `clearmsg_timeout` config), the message should be read.
The `!quickvote` feature implements a simple vote system. If a broadcaster or moderator send the `!quickvote` command a vote will be started (or a already running vote will be ended). After a quickvote has been started your community can casts votes by sending a chat message starting with `#`. You can include a message after `!quickvote` (e.g. `!quickvote Is pizza hawaii any good? #yes/#no`). If you do so, this message will be repeated every 60 seconds, so everyone keeps in mind, that a vote is still active.
#### !random
The `!random` command will read a random line from a file called `random.txt`. You can also use multiple files, if you call `!random foo` the bot fetch the random line from a file called `random_foo.txt` instead of `random.txt`. `!random bar` will use the file `random_bar.txt` and so on. The `!random` command is restricted to the broadcaster and moderators.
The `!smartquote` command will read a line from a file called `quotes.txt`. You can add a parameter after the command. If the parameter is numeric the bot will search for a line starting with `#$number`. If the parameter is a string it will search for a line matching the parameter. If no parameter is given it will search for a completely random line.
The `!addvote` command adds a new line to `quotes.txt`. It expects two parameters: `!addquote username quote` where `username` is the name of the user to be quoted.
Only Subs, Mods and Broadcaster are allowed to add quotes.
The voices available depend on your Operating System and/or browser. On some systems only a default voice is available and the `Select voice` dropdown might stay empty or will only show entries after you clicked the `Init` button. Some Android devices will show a huge list of voices, but sounds the same no matter which one you choose.
Feel free to use the [Issuetracker](https://gitlab.com/gpvkt/twitchtts/-/issues) or send an [E-Mail](mailto:contact-project+gpvkt-twitchtts-38486705-issue-@incoming.gitlab.com) if you experience any problems.
