Skip to main content

Bridge that takes incoming IRC messages and converts them to other formats

Project description

Build Status PyPI version


Translates incoming IRC messages to OSC, HTTP, or any other output format you need.


chat_transformer can be installed using pip:

pip install chat_transformer

Set up

You must create a json file that specifies that mapping of IRC messages to output data. The file must contain a JSON object, where each KEY is an IRC command/message, and the VALUE is a JSON object with the parameters for converting the IRC message to OSC commands. For example:

    "brightness": {
        "address": "/osc/brightness/",
        "min": 0.0,
        "max": 2.0,
        "delta": 0.1,
        "initial": 1.0,
        "outputs": {
            "osc": {"address": "/video/brightness"},
            "http": {"command_name": "brightness"}

With the above targets data, the following IRC message:

brightness set 0.75

would translate to the following OSC Message:

/osc/brightness 0.75

and the following POST message to the main HTTP target:

{brightness: {"value": 0.75, "min": 0.0, "max": 2.0}}


chat_transformer can be run as a CLI command. At minimum, you must specify the location of a config file that will hold the various settings necessary for running chat_transformer:

chat_transformer --config /path/to/my/config.json

Or with the shorthand commands:

chat_transformer -c /path/to/my/config.json

Rather than specifying options as command-line arguments, options can instead be set as environment variables:

export CHAT_TRANSFORMER_CONFIG=/path/to/my/config.json

Command Line Options

Argument Env variable name Description Default
-c, --config CHAT_TRANSFORMER_CONFIG filepath of the config JSON file config.json
-v, --verbosity How verbose to make the output 1 (Info)

Configuration File

The configuration JSON file holds all the necessary settings for running your instance of chat_transformer. At bear minimum it must include an irc key with the server and login information, a commands key with information about the the commands JSON file (which contains the list of active commands to listen for and respond to), and at least one output (osc and http are supported out of the box). Here's an example of a minimal configuration file that's listening to freenode:

    "irc": {
        "server": ""
    "commands": {
        "filename": "/path/to/my/commands.json"
    "outputs": {
        "osc": {
            "port": 9876

Configuration File Ooptions

Key Description Default
irc.server Server address of the IRC Server None (Required)
irc.port Port number of the IRC Server 6667
irc.nickname Nickname for authnenticating on IRC None (Required)
irc.password Password for authentication on the IRC server
irc.username Username for authentication on the IRC server irc.nickname (above)
irc.realname Real name on on the IRC server IRC channel to join and listen for incoming commands. irc.nickname (above)
commands.filename Path of the file that holds the IRC commands to listen commands.json Reload the commands file when it has changed on disk False
commands.watch_interval Time (in seconds) between checking for file changes 60
output.osc.ip IP Address of the OSC target Port of the OSC target None (Required if OSC is used)
output.http.base_url URL target to post to None (Required if HTTP is used)
output.http.jwt_secret JWT secret for using JWT encoding

Commands File Options

Key Description Default
min Mininum possible value for this command 0.0
max Maximum possible value for this command 1.0
delta Amount to change whenever an INCREMENT or DECREMENT command is received 0.05
initial Initial value for this command 0.5
outputs.osc.address OSC Address to which the message should be send
outputs.http.command_new Key to used for the POSTed HTTP data
outputs.http.endpoint Endpoint to POST to for this command

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

chat_transformer-0.5.0.tar.gz (14.6 kB view hashes)

Uploaded source

Built Distribution

chat_transformer-0.5.0-py3-none-any.whl (19.4 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page