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.

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

JSON Example:

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

CSV Example:

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

Text Example:

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

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