chat-transformer 0.5.0
Bridge that takes incoming IRC messages and converts them to other formats
License: MIT
Requires Python: >=3.5.3

[![Build Status](https://travis-ci.org/MattBroach/chat_transformer.svg?branch=master)](https://travis-ci.org/MattBroach/chat_transformer)
[![PyPI version](https://badge.fury.io/py/chat-transformer.svg)](https://badge.fury.io/py/chat_transformer)

# chat_transformer

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

## Installation

`chat_transformer` can be installed using `pip`:

```python
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:

```json
{
    "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}}
```

## Usage

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

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

Or with the shorthand commands:

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

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

```bash
export CHAT_TRANSFORMER_CONFIG=/path/to/my/config.json
chat_transformer
```

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

```json
{
    "irc": {
        "server": "chat.freenode.net"
    },
    "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` | 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 |
| `commands.watch` | 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 | 127.0.0.1 |
| `output.osc.post` | 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 | |