Twitch Chat IRC
A simple tool used to send and receive Twitch chat messages over IRC with python web sockets. Receiving does not require authentication, while sending does.
Setup
Requirements:
- This tool was created in a Python 3 environment.
- Install via pip with
pip install twitch-chat-irc
- Or install manually with
pip install .
Authentication
If you intend to send messages, you will require authentication.
- Go to https://twitchapps.com/tmi/
- Click "Connect".
- Log in with Twitch.
- Copy the generated oath token. Now, there are 2 ways to proceed:
-
(Recommended) Create a file called
.env
and save your credentials here as:NICK=x
PASS=yreplacing
x
andy
with your username and oauth token respectively.
Seeexample.env
for an example. -
Pass your credentials as function/command line arguments. See below for examples.
-
Command line:
Usage
usage: twitch_chat_irc.py [-h] [-timeout TIMEOUT]
[-message_timeout MESSAGE_TIMEOUT]
[-buffer_size BUFFER_SIZE]
[-message_limit MESSAGE_LIMIT] [-username USERNAME]
[-oauth OAUTH] [--send] [-output OUTPUT]
channel_name
Send and receive Twitch chat messages over IRC with python web sockets. For
more info, go to https://dev.twitch.tv/docs/irc/guide
positional arguments:
channel_name Twitch channel name (username)
optional arguments:
-h, --help show this help message and exit
-timeout TIMEOUT, -t TIMEOUT
time in seconds needed to close connection after not
receiving any new data (default: None = no timeout)
-message_timeout MESSAGE_TIMEOUT, -mt MESSAGE_TIMEOUT
time in seconds between checks for new data (default:
1 second)
-buffer_size BUFFER_SIZE, -b BUFFER_SIZE
buffer size (default: 4096 bytes = 4 KB)
-message_limit MESSAGE_LIMIT, -l MESSAGE_LIMIT
maximum amount of messages to get (default: None =
unlimited)
-username USERNAME, -u USERNAME
username (default: None)
-oauth OAUTH, -password OAUTH, -p OAUTH
oath token (default: None). Get custom one from
https://twitchapps.com/tmi/
--send send mode (default: False)
-output OUTPUT, -o OUTPUT
output file (default: None = print to standard output)
Examples
Receiving messages
1. Output messages from a livestream to standard output
python -m twitch_chat_irc <channel_name>
2. Output messages from a livestream to a file
python -m twitch_chat_irc <channel_name> -output <file_name>
If the file name ends in .json
, the array will be written to the file in JSON format. Similarly, if the file name ends in .csv
, the data will be written in CSV format.
Otherwise, the chat messages will be outputted to the file in the following format:
[<time>] <author>: <message>
3. Set a timeout (close connection if no message has been sent in a certain time)
python -m twitch_chat_irc <channel_name> -timeout <time_in_seconds> -output <file_name>
There are other options, such as message_timeout
and buffer_size
, but these normally do not need to be changed. See above for a description of all options.
4. Set a maximum number of messages to read (close connection once limit has been reached)
python -m twitch_chat_irc <channel_name> -message_limit <number_of_messages> -output <file_name>
Example outputs
python -m twitch_chat_irc <channel_name> -output example.json
python -m twitch_chat_irc <channel_name> -output example.csv
python -m twitch_chat_irc <channel_name> -output example.txt
Sending messages
This will open an interactive session which allows you to send messages to the specified channel.
1. Send messages to a channel (authentication via .env)
python -m twitch_chat_irc --send <channel_name>
2. Send messages to a channel (authentication via arguments)
python -m twitch_chat_irc --send <channel_name> -username <username> -oauth <oauth_token>
Python module
Importing the module
from twitch_chat_irc import twitch_chat_irc
Examples
Starting a connection
This allows for both receiving and sending of messages
.env
(if any)
1. Start a connection with Twitch chat using credentials in connection = twitch_chat_irc.TwitchChatIRC()
2. Start a connection with Twitch chat using credentials
connection = twitch_chat_irc.TwitchChatIRC('username','oauth:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx')
Receiving messages
The listen
method returns a list when a KeyboardInterrupt
is fired, or when a timeout/limit has been reached. The arguments shown below can be used together to form more complex method calls.
1. Get a list of messages from a channel
messages = connection.listen('channel_name')
2. Get a list of messages from a channel, stopping after not getting a message for 30 seconds
messages = connection.listen('channel_name', timeout=30)
3. Get a list of messages from a channel, stopping after getting 100 messages
messages = connection.listen('channel_name', message_limit=100)
4. Write messages from a channel to a file
connection.listen('channel_name', output='file.txt')
5. Set a callback function to be fired each time a message is received
def do_something(message):
print(message)
connection.listen('channel_name', on_message=do_something)
Sending messages
The send
method allows for messages to be sent to different channels. This method requires valid authentication to be provided, otherwise an exception will be called.
1. Send a message
message = 'Hello world!'
connection.send('channel_name', message)
Close connection
The close_connection
method closes the connection with Twitch chat. No futher messages can be received or sent now.
1. Close a connection
connection.close_connection()