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.
• Run pip install -r requirements.txt to ensure you have the necessary dependencies.

Authentication

If you intend to send messages, you will require authentication.

1. Go to https://twitchapps.com/tmi/
2. Click "Connect".
3. Log in with Twitch.
4. 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=y

     replacing x and y with your username and oauth token respectively.
     See example.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 twitch_chat_irc.py <channel_name>

2. Output messages from a livestream to a file

python twitch_chat_irc.py <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 twitch_chat_irc.py <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 twitch_chat_irc.py <channel_name> -message_limit <number_of_messages> -output <file_name>

Example outputs

JSON Example:

python twitch_chat_irc.py <channel_name> -output example.json

CSV Example:

python twitch_chat_irc.py <channel_name> -output example.csv

Text Example:

python twitch_chat_irc.py <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 twitch_chat_irc.py --send <channel_name>

2. Send messages to a channel (authentication via arguments)

python twitch_chat_irc.py --send <channel_name> -username <username> -oauth <oauth_token>

Python module

Importing the module

import twitch_chat_irc

Examples

Starting a connection

This allows for both receiving and sending of messages

1. Start a connection with Twitch chat using credentials in .env (if any)

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()