Partly redesign rtpmidi backend

1 files changed, 85 insertions, 0 deletions

diff --git a/backends/rtpmidi.md b/backends/rtpmidi.md
new file mode 100644
index 0000000..49c6baf
--- /dev/null
+++ b/backends/rtpmidi.md
@@ -0,0 +1,85 @@
+### The `rtpmidi` backend
+
+This backend provides read-write access to RTP MIDI streams, which transfer MIDI data
+over the network.
+
+As the specification for RTP MIDI does not normatively indicate any method
+for session management, most vendors define their own standards for this.
+The MIDIMonster supports the following session management methods, which are
+selectable per-instance, with some methods requiring additional global configuration:
+
+* Direct connection: The instance will send and receive data from peers configured in the
+	instance configuration
+* Direct connection with peer learning: The instance will send and receive data from peers
+	configured in the instance configuration as well as previously unknown peers that
+	voluntarily send data to the instance.
+* AppleMIDI session management:
+
+Note that instances that receive data from multiple peers will combine all inputs into one
+stream, which may lead to inconsistencies during playback.
+
+#### Global configuration
+
+| Option	| Example value		| Default value 	| Description		|
+|---------------|-----------------------|-----------------------|-----------------------|
+| `detect`      | `on`                  | `off`                 | Output channel specifications for any events coming in on configured instances to help with configuration |
+| `mdns-bind`	| `10.1.2.1 5353`	| `0.0.0.0 5353`	| Bind host for the mDNS discovery server |
+| `mdns-name`	| `computer1`		| none			| mDNS hostname to announce, also used as AppleMIDI peer name |
+
+#### Instance configuration
+
+Common instance configuration parameters
+
+| Option	| Example value		| Default value 	| Description		|
+|---------------|-----------------------|-----------------------|-----------------------|
+| `ssrc`	| `0xDEADBEEF`		| Randomly generated	| 32-bit synchronization source identifier |
+| `mode`	| `direct`		| none			| Instance session management mode (`direct` or `apple`) |
+
+`direct` mode instance configuration parameters
+
+| Option	| Example value		| Default value 	| Description		|
+|---------------|-----------------------|-----------------------|-----------------------|
+| `bind`	| `10.1.2.1 9001`	| `0.0.0.0 <random>`	| Local network address to bind to | 
+| `learn`	| `true`		| `false`		| Accept new peers for data exchange at runtime |
+| `peer`	| `10.1.2.3 9001`	| none			| MIDI session peer, may be specified multiple times |
+
+`apple` mode instance configuration parameters
+
+| Option	| Example value		| Default value 	| Description		|
+|---------------|-----------------------|-----------------------|-----------------------|
+| `bind`	| `10.1.2.1 9001`	| `0.0.0.0 <random>`	| Local network address to bind to (note that AppleMIDI requires two consecutive port numbers to be allocated) |
+| `session`	| `Just Jamming`	| `MIDIMonster`		| Session name to announce via mDNS |
+| `invite`	| `pad,piano`		| none			| Devices to send invitations to when discovered (the special value `*` invites all discovered peers) |
+
+Note that AppleMIDI session establishment requires mDNS functionality, thus the `mdns-name` global parameter
+(and, depending on your setup, the `mdns-bind` parameter) need to be configured properly. 
+
+#### Channel specification
+
+The `rtpmidi` backend supports mapping different MIDI events to MIDIMonster channels. The currently supported event types are
+
+* `cc` - Control Changes
+* `note` - Note On/Off messages
+* `pressure` - Note pressure/aftertouch messages
+* `aftertouch` - Channel-wide aftertouch messages
+* `pitch` - Channel pitchbend messages
+
+A MIDIMonster channel is specified using the syntax `channel<channel>.<type><index>`. The shorthand `ch` may be
+used instead of the word `channel` (Note that `channel` here refers to the MIDI channel number).
+
+The `pitch` and `aftertouch` events are channel-wide, thus they can be specified as `channel<channel>.<type>`.
+
+MIDI channels range from `0` to `15`. Each MIDI channel consists of 128 notes (numbered `0` through `127`), which
+additionally each have a pressure control, 128 CC's (numbered likewise), a channel pressure control (also called
+'channel aftertouch') and a pitch control which may all be mapped to individual MIDIMonster channels.
+
+Example mappings:
+
+```
+rmidi1.ch0.note9 > rmidi2.channel1.cc4
+rmidi1.channel15.pressure1 > rmidi1.channel0.note0
+rmidi1.ch1.aftertouch > rmidi2.ch2.cc0
+rmidi1.ch0.pitch > rmidi2.ch1.pitch
+```
+
+#### Known bugs / problems