0972ebd6c2 | ||
---|---|---|
.gitignore | ||
CHANGELOG.md | ||
CONTRIBUTING.md | ||
LICENSE | ||
README.md | ||
bootstrap.min.css | ||
build.py | ||
config-dist.yml | ||
favicon.ico | ||
jquery.js | ||
requirements.txt | ||
tts.exe | ||
tts.html | ||
tts.js | ||
tts.py |
README.md
Twitch TextToSpeech Bot
A simple Twitch TTS bot (Web Speech API)
Description
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), but they often 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. Another very important aspect was that you should use almost any device capable running an HTML5-webbrowser as output. Therefore the bot uses a client-server "architecture". You can run the bot - for example - on your IRL server, but use your phone as output device. A mobile only solution always have the disadvantage of loosing messages, e.g. when your mobile connection drops.
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 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
seerequirements.txt
. If you usetts.exe
all dependencies are included.
Installing
- Clone the repo, or download and unzip the newest Release
- Rename/copy
config-dist.yml
toconfig.yml
- Adapt
config.yml
to your needs. SeeConfiguration
for details.
Configuration
Please use UTF-8
as encoding, when editing config.yml
.
Example:
irc:
channel: "#gpkvt"
username: "ttsbot"
oauth_token: "oauth:ohkoace0wooghue8she9xaN0nooSau"
server: "irc.chat.twitch.tv"
clearmsg_timeout: 10
http:
port: 80
bind: "localhost"
bot:
start_enabled: True
subonly: False
modonly: False
message_length: 200
language: de
messages:
toff: "TTS is now inactive."
ton: "TTS is now active."
too_long: "Sorry, your TTS message is too long."
disabled: "Sorry, TTS is disabled right now."
denied: "Sorry, you are not allowed to use TTS."
subonly: "Sorry, TTS is a sub-only feature."
whitelist: "Sorry, you are not allowed to use TTS."
ready: "TTS bot alpha ready!"
says: "says"
votestart: "Quickvote started. Send #yourchoice to participate."
voteend: "Quickvote ended. The results are:"
votenobody: "Nobody casted a vote. :("
voteresult: "Voting has ended. The result is:"
votes: "Votes"
pickstart: "Pick started. Send #pickme to participate."
pickresult: "Pick ended. The results are:"
picknone: "Nobody was picked. :("
quotenotfound: "Sorry, no quote found."
quoteaddedprefix: "Quote:"
quoteaddedsuffix: "added."
wiki_too_many: "Sorry, there are too many possible results. Try a more narrow search."
wiki_no_result: "Sorry, there was an error fetching the wikipedia answer."
log:
level: "INFO"
usermapping:
gpkvt: "gpk"
whitelist:
Explanation
irc
channel
: Channel you want to monitor (e.g. #gpkvt)username
: The bots username (e.g. gpkvt)oauth_token
: The bots OAUTH-Token (e.g. oauth:ohkoace0wooghue8she9xaN0nooSau)server
: Twitch IRC server to be used (default should be fine)clearmsg_timeout
: Time to wait for an moderator to delete a message, before it's added to the TTS queue
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. 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.
http
port
: Internal Webserver Port to listen to (e.g. 8080)bind
: Interface/IP to bind server to (e.g. localhost)
bot
start_enabled
: Enable the bot on start? IfFalse
you need to use!ton
first to make TTS work.subonly
: IfTrue
only Subs can use TTSmodonly
: IfTrue
only Mods can use TTSmessage_length
: Maximum allowed message length for TTSlanguage
: Language for!wiki
command
messages
toff
: The bots reply when!toff
is used.ton
: The bots reply when!ton
is used.too_long
: The bots reply if message exceedsmessage_length
disabled
: The bots reply if TTS is disableddenied
: The bots reply if the user is not allowed to use TTSsubonly
: The bots reply ifsubonly
is active and the user isn't one.whitelist
: The bots reply ifwhitelist
is set and user isn't on the list.ready
: The bots init messagesays
: Prefix to add between username and messagevotestart
: Message when a quickvote was started.voteend
: Message when a quickvote ends.votenobody
: Message when quickvote ends, but nobody has voted.voteresult
: Prefix for the result (will be read out).votes
: Suffix to vote count.pickstart
: Message when!pick
was started.pickresult
: Message when!pick
ends.picknone
: Message if nobody was picked.quotenotfound
: Message if requests quote wasn't found.quoteaddedprefix
: Prefix forQuote <number> added
message.quoteaddedsuffix
: Suffix forQuote <number> added
message.wiki_too_many
: Message if!wiki
command has more than one result.wiki_no_result
: Message if!wiki
command hasn't a valid result.
log
level
: The loglevel, valid values are:DEBUG
,INFO
,WARNING
,ERROR
,CRITICAL
Do not use DEBUG
in a production environment.
usermapping
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).
Please note: The key (real username) MUST be lowercase.
whitelist
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.
A whitelist looks as follows:
whitelist:
- gpkvt
- foo
- bar
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
.
Please note: Usernames MUST be lowercase.
Executing program
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.
Additional Commands
Additional commands (broadcaster and mods only) are:
!ping
: Check if bot is alive (the bot should reply:Pong!
)!toff
: Turn TTS off (will also empty the current TTS queue)!ton
: Turn TTS back on!dtts <username>
: Disable TTS for the given user!ptts <username>
: Allow TTS for the given user!usermap <username> <spoken name>
: Add an entry to the usermapping inconfig.yml
!delay <int>
: Adjust theclearmsg_timeout
inconfig.yml
Additional features
!quickvote
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.
!smartquote
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 format of quotes.txt
looks as follows:
#1: "the quote" -username/game (date)
!addquote
The !addquote
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.
!wiki
The !wiki
command searchs the wikipedia and fetches the first three sentences of the result.
!pick
The !pick
command will randomly pick a given number of participants. After !pick <max number of participants>
was started by the broadcaster or a moderator, everyone can type #pickme
to become the chance to get picked when !pick
gets triggered again. If no number was given, when !pick
was frist triggered only one participant will get picked.
Build
If you prefer to build your own tts.exe
instead of using the shipped one, you can do as follows:
- Install Python 3
- Install pyinstaller:
pip install pyinstaller
- Install the required dependencies:
pip install -r requirements.txt -v
- Create the executeable:
pyinstaller --onefile tts.py
Voices
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.
On Windows you can install additional voices via Settings
> Time & language
> Speech
> Add voices
or by simply run Add speech voices
.
Do not use Online-Voices, as this will result in serious delays.
Help
Feel free to use the Issuetracker or send an E-Mail if you experience any problems.
Authors
Version History
See CHANGELOG.md
License
This project is licensed under the GPLv3 License - see LICENSE for details.
Acknowledgments
Ideas and Testing
Libraries
Disclaimer
This project is not affiliated, associated, authorized, endorsed by, or in any way officially connected with Twitch Interactive, Inc.