From 0c333567f599206cb0be6b74f02e59820536e0b2 Mon Sep 17 00:00:00 2001 From: cbdev Date: Sun, 31 Mar 2019 09:00:12 +0200 Subject: Move backend documentation out of main README --- backends/midi.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 backends/midi.md (limited to 'backends/midi.md') diff --git a/backends/midi.md b/backends/midi.md new file mode 100644 index 0000000..7d3e847 --- /dev/null +++ b/backends/midi.md @@ -0,0 +1,54 @@ +### The `midi` backend + +The MIDI backend provides read-write access to the MIDI protocol via virtual ports. + +#### Global configuration + +| Option | Example value | Default value | Description | +|---------------|-----------------------|-----------------------|-----------------------| +| `name` | `MIDIMonster` | none | MIDI client name | + +#### Instance configuration + +| Option | Example value | Default value | Description | +|---------------|-----------------------|-----------------------|-----------------------| +| `read` | `20:0` | none | MIDI device to connect for input | +| `write` | `DeviceName` | none | MIDI device to connect for output | + +MIDI device names may either be `client:port` portnames or prefixes of MIDI device names. +Run `aconnect -i` to list input ports and `aconnect -o` to list output ports. + +Each instance also provides a virtual port, so MIDI devices can also be connected with `aconnect `. + +#### Channel specification + +The MIDI backend supports multiple channel types + +* `cc` - Control Changes +* `note` - Note On/Off messages +* `nrpn` - NRPNs (not yet implemented) + +A channel is specified using the syntax `channel.`. The shorthand `ch` may be used instead +of `channel`. +The earlier syntax of `.` is officially deprecated but still supported for compatability +reasons. This support may be removed at some future time. + +Channels range from `0` to `15`. Each channel consists of 128 notes (numbered `0` through `127`) and 128 CC's +(numbered likewise), a channel pressure control (also called 'channel aftertouch') and a pitch control. +Each Note also has an additional pressure value associated with it. + +Example mappings: +``` +midi1.ch0.note9 > midi2.channel1.cc4 +midi1.channel15.cc1 > midi1.channel0.note0 +``` +#### Known bugs / problems + +Currently, no Note Off messages are sent (instead, Note On messages with a velocity of 0 are +generated, which amount to the same thing according to the spec). This may be implemented as +a configuration option at a later time. + +NRPNs are not yet fully implemented, though rudimentary support is in the codebase. + +To see which events your MIDI devices output, ALSA provides the `aseqdump` utility. You can +list all incoming events using `aseqdump -p `. \ No newline at end of file -- cgit v1.2.3 From 6b97a08dee55ac4807902fc7ae1b4efe2911b873 Mon Sep 17 00:00:00 2001 From: cbdev Date: Mon, 1 Apr 2019 20:13:22 +0200 Subject: Implement pitch, aftertouch and pressure events for the MIDI backend --- backends/midi.md | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) (limited to 'backends/midi.md') diff --git a/backends/midi.md b/backends/midi.md index 7d3e847..315edfe 100644 --- a/backends/midi.md +++ b/backends/midi.md @@ -22,25 +22,32 @@ Each instance also provides a virtual port, so MIDI devices can also be connecte #### Channel specification -The MIDI backend supports multiple channel types +The MIDI 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 * `nrpn` - NRPNs (not yet implemented) -A channel is specified using the syntax `channel.`. The shorthand `ch` may be used instead -of `channel`. +A MIDIMonster channel is specified using the syntax `channel.`. The shorthand `ch` may be +used instead of the word `channel` (Note that `channel` here refers to the MIDI channel number). The earlier syntax of `.` is officially deprecated but still supported for compatability reasons. This support may be removed at some future time. -Channels range from `0` to `15`. Each channel consists of 128 notes (numbered `0` through `127`) and 128 CC's -(numbered likewise), a channel pressure control (also called 'channel aftertouch') and a pitch control. -Each Note also has an additional pressure value associated with it. +The `pitch` and `aftertouch` events are channel-wide, thus they can be specified as `channel.`. + +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: ``` midi1.ch0.note9 > midi2.channel1.cc4 -midi1.channel15.cc1 > midi1.channel0.note0 +midi1.channel15.pressure1 > midi1.channel0.note0 +midi1.aftertouch > midi2.cc0 +midi1.pitch > midi2.pitch ``` #### Known bugs / problems @@ -51,4 +58,4 @@ a configuration option at a later time. NRPNs are not yet fully implemented, though rudimentary support is in the codebase. To see which events your MIDI devices output, ALSA provides the `aseqdump` utility. You can -list all incoming events using `aseqdump -p `. \ No newline at end of file +list all incoming events using `aseqdump -p `. -- cgit v1.2.3 From dd3ecfd3312673c8cfcfd8fbe96586b23d873c07 Mon Sep 17 00:00:00 2001 From: cbdev Date: Mon, 1 Apr 2019 20:15:50 +0200 Subject: Fix spelling --- backends/midi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'backends/midi.md') diff --git a/backends/midi.md b/backends/midi.md index 315edfe..da9870f 100644 --- a/backends/midi.md +++ b/backends/midi.md @@ -33,7 +33,7 @@ The MIDI backend supports mapping different MIDI events to MIDIMonster channels. A MIDIMonster channel is specified using the syntax `channel.`. The shorthand `ch` may be used instead of the word `channel` (Note that `channel` here refers to the MIDI channel number). -The earlier syntax of `.` is officially deprecated but still supported for compatability +The earlier syntax of `.` is officially deprecated but still supported for compatibility reasons. This support may be removed at some future time. The `pitch` and `aftertouch` events are channel-wide, thus they can be specified as `channel.`. -- cgit v1.2.3 From f4ca1869c3e1a106e4dbab39213ba81141ada1d5 Mon Sep 17 00:00:00 2001 From: cbdev Date: Mon, 1 Apr 2019 20:20:12 +0200 Subject: Fix MIDI example mappings --- backends/midi.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'backends/midi.md') diff --git a/backends/midi.md b/backends/midi.md index da9870f..9733cc2 100644 --- a/backends/midi.md +++ b/backends/midi.md @@ -46,8 +46,8 @@ Example mappings: ``` midi1.ch0.note9 > midi2.channel1.cc4 midi1.channel15.pressure1 > midi1.channel0.note0 -midi1.aftertouch > midi2.cc0 -midi1.pitch > midi2.pitch +midi1.ch1.aftertouch > midi2.ch2.cc0 +midi1.ch0.pitch > midi2.ch1.pitch ``` #### Known bugs / problems -- cgit v1.2.3 From bbeade8898200a8024169ece30c620016fd5eaf1 Mon Sep 17 00:00:00 2001 From: cbdev Date: Thu, 1 Aug 2019 20:58:21 +0200 Subject: Implement midi backend detect option --- backends/midi.md | 1 + 1 file changed, 1 insertion(+) (limited to 'backends/midi.md') diff --git a/backends/midi.md b/backends/midi.md index 9733cc2..5e295ee 100644 --- a/backends/midi.md +++ b/backends/midi.md @@ -7,6 +7,7 @@ The MIDI backend provides read-write access to the MIDI protocol via virtual por | Option | Example value | Default value | Description | |---------------|-----------------------|-----------------------|-----------------------| | `name` | `MIDIMonster` | none | MIDI client name | +| `detect` | `on` | `off` | Output channel specifications for any events coming in on configured instances to help with configuration. | #### Instance configuration -- cgit v1.2.3 From 191949152d803229275d7b98b184ff722a9549a2 Mon Sep 17 00:00:00 2001 From: cbdev Date: Sat, 31 Aug 2019 17:23:22 +0200 Subject: Update documentation --- backends/midi.md | 3 +++ 1 file changed, 3 insertions(+) (limited to 'backends/midi.md') diff --git a/backends/midi.md b/backends/midi.md index 5e295ee..108860e 100644 --- a/backends/midi.md +++ b/backends/midi.md @@ -52,6 +52,9 @@ midi1.ch0.pitch > midi2.ch1.pitch ``` #### Known bugs / problems +To access MIDI data, the user running MIDIMonster needs read & write access to the ALSA sequencer. +This can usually be done by adding this user to the `audio` system group. + Currently, no Note Off messages are sent (instead, Note On messages with a velocity of 0 are generated, which amount to the same thing according to the spec). This may be implemented as a configuration option at a later time. -- cgit v1.2.3