midi-request-trigger/README.md

179 lines
4.1 KiB
Markdown
Raw Normal View History

2023-09-09 20:37:39 -05:00
# midi-request-trigger
2024-09-06 20:15:59 -05:00
A service that triggers HTTP requests and/or MQTT messages when MIDI messages are recieved and triggers MIDI messages when HTTP requests and/or MQTT messages are received.
2023-09-09 20:37:39 -05:00
## Install
You can install by building.
### Building
Building should be as simple as running:
```bash
go build
```
### Running as a service
You are likely going to want to run the tool as a service to ensure it runs at boot and restarts in case of failures. Below is an example service config file you can place in `/etc/systemd/system/midi-request-trigger.service` on a linux system to run as a service if you install the binary in `/usr/local/bin/`.
```systemd
[Unit]
Description=MIDI Request Trigger
After=network.target
StartLimitIntervalSec=500
StartLimitBurst=5
[Service]
ExecStart=/usr/local/bin/midi-request-trigger
ExecReload=/bin/kill -s HUP $MAINPID
Restart=on-failure
RestartSec=5s
[Install]
WantedBy=multi-user.target
```
Once the service file is installed, you can run the following to start it:
```bash
systemctl daemon-reload
systemctl start midi-request-trigger.service
```
On MacOS, you can setup a Launch Agent in `~/Library/LaunchAgents/com.mrgeckosmedia.midi-request-trigger.plist` as follows:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.mrgeckosmedia.midi-request-trigger</string>
<key>ProgramArguments</key>
<array>
<string>/path/to/bin/midi-request-trigger</string>
<string>-c</string>
<string>/path/to/config.yaml</string>
</array>
<key>KeepAlive</key>
<dict>
<key>Crashed</key>
<true/>
<key>SuccessfulExit</key>
<false/>
</dict>
<key>RunAtLoad</key>
<true/>
<key>OnDemand</key>
<false/>
</dict>
</plist>
```
Start with:
```bash
launchctl load ~/Library/LaunchAgents/com.mrgeckosmedia.midi-request-trigger.plist
```
Check status with:
```bash
launchctl list com.mrgeckosmedia.midi-request-trigger
```
Stop with:
```bash
launchctl unload ~/Library/LaunchAgents/com.mrgeckosmedia.midi-request-trigger.plist
```
## Config
The default configuration paths are:
- `./config.yaml` - A file in the current working directory.
- `~/.config/midi-request-trigger/config.yaml` - A file in your home directory's config path.
- `/etc/midi-request-trigger/config.yaml` - A file in the etc config folder.
### To verify listener works
You can find the device name by running the following:
```bash
midi-request-trigger -l
```
On MacOS, there is an IAC Driver that can be enabled in Audio MIDI Setup.
```yaml
---
midi_routers:
- name: service_notifications
device: IAC Driver Bus 1
debug_listener: true
```
### Example note trigger configuration
```yaml
---
midi_routers:
- name: service_notifications
device: IAC Driver Bus 1
debug_listener: true
note_triggers:
- channel: 0
note: 0
match_all_velocities: true
url: http://example.com
midi_info_in_request: true
```
### Example request trigger configuration
```yaml
---
midi_routers:
- name: service_notifications
device: IAC Driver Bus 1
debug_listener: true
request_triggers:
- channel: 0
note: 0
velocity: 1
midi_info_in_request: true
uri: /send_note
```
### Example multi part request
```yaml
---
midi_routers:
- name: service_notifications
device: IAC Driver Bus 1
debug_listener: true
note_triggers:
- channel: 0
note: 0
match_all_velocities: true
url: http://example.com
method: POST
body: |
-----------------------------888832887744
Content-Disposition: form-data; name="message"
example variable
-----------------------------888832887744
Content-Disposition: form-data; name="file"; filename="example.txt"
Content-Type: text/plain
Content of file.
-----------------------------888832887744--
headers:
Content-Type:
- multipart/form-data; boundary=---------------------------888832887744
debug_request: true
2024-09-06 20:15:59 -05:00
```