baconscript/README.md

# Bacon Script

A theoretical exercise to control a Hog 4 via OSC, with comment macros.

The comment macro grammar described in `CommentMacro.g4` is based upon the Hog 3.9 manual, Chapter 22.4.  The python3 implementation in `OscCommentMacroListener.py` is based on Chapter 24.2 in the same manual.

Some macros are unsupported/unsupportable with this method.  Some macro features, like timing, are not yet implemented.  Refer to the **Features** table for specific notes.

## Installing

Install Antlr4 for input and Python-OSC for output.
```bash
$ pip3 install antlr4-python3-runtime python-osc
```

Use git to retrieve a copy of the code.
```bash
$ git clone http://company235.com/git/kevin/baconscript.git
$ cd baconscript
```

## Testing

Edit `server.cfg` to the correct values for your Hog4.

`comment.py` will accept macros on the command line, or will run an interactive prompt.  Use the builtin command `exit` to quit the interactive prompt.

```bash
$ ./comment.py
Adding Hog device at net# 1
comment# GL1
Go on List 1
comment# exit
```

Run a baconscript file by passing the script file to `comment.py` as standard input.

```bash
$ ./comment.py < example.bs
```

## Developing

You must also install the ANTLR tool.  On a mac with homebrew, do:
```bash
$ brew install antlr
```

Update the lexer and parser for Python3
```bash
$ antlr -Dlanguage=Python3 CommentMacro.g4
```


## Features
Only features that are supported in both OSC and Comment Macros are able to be
implemented in baconscript.  This table lists all comment macros (as of 3.9)
that are implemented in python.

| Grammar Feature | eg. | Supported |
| ----------------|-----|-----------|
| fade times | t5 | no |
| multiple targets | 1,2 | Yes |
| ranges | 1>4 | Yes, intervals of 1 |
| multiple macros | GM1:GL3 | Yes |
| network devices | h4 | Yes, H devices only |
| wait times | WAIT1 | BaconScript only; Continue script after n seconds.

Benefiting from the LL(*) parser provided by ANTLR, `multiple targets` and
`ranges` may be combined ad infinitum.  This is a known deviation from the
Comment Macro syntax.

### Standard Macros

| Macro | Function | Supported | Notes |
|-------|----------|-----------|-------|
| GM | Go Master | Yes | GOTO on current master only |
| HM | Halt Master | Yes | |
| AM | Assert Master | Partial | on current master only |
| RM | Release Master | Partial | on current master only |
| RA | Release All | Yes | |
| RO | Release Others | no | |
| FM | Fade Master | Partial | no times, no * |
| FGM | Fade Grand Master | Partial | no times |
| CM | Choose Master | Yes | |
| GL | Go List | Yes | |
| HL | Halt List | Yes | |
| AL | Assert List | no | |
| RL | Release List | Yes | |
| GB | Go Batch | no | |
| HB | Halt Batch | no | |
| AB | Assert Batch | no | |
| RB | Release Batch | no | |
| GS | Go Scene | Yes | |
| HS | Halt Scene | Yes | |
| AS | Assert Scene | no | |
| RS | Release Scene | Yes | |
| CP | Change Page | Partial | only CP+ and CP- |
| RV | Recall View | no | |
| ET | Enable Timecode | no | |
| DT | Disable Timecode | no | |
| OT | Open Timecode Toolbar | no | |
| MS | Midi String | no | possible? |
| MN | Midi Note | no | |
| RN | Reset Node | no | |
| GK | Go Keystroke Macro | Yes | |
| HK | Pause Keystroke Macro | Yes | |
| RK | Stop Keystroke Macro | Yes | . |

### Additional Macros
BaconScript also supports several macros that aren't present on Hog4, but become possible/desirable when wrapping OSC.

| Macro | Function | Notes |
|-------|----------|-------|
| INT | Select an Intensity Pallet | keypress macro |
| POS | Select a Position Pallet | keypress macro |
| COLR | Select a Colour Pallet | keypress macro |
| BEAM | Select a Beam Pallet | keypress macro |
| WAIT | Pause for n seconds | |
| PASS | Null instruction | |


## Future Work
Pleas feel welcome to submit pull requests or patches that enable support for:

*   Sending target ranges as OSC arguments
 * Hog4 does not support multiple arguments to a single path.
*   Send multi-macro line as an OSC batch
 * HogOS 3.9 has a bug involving batches.  Whereby only every-other member of the batch will be interpreted.
*   Timing on master fades