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/osc.md | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 backends/osc.md (limited to 'backends/osc.md') diff --git a/backends/osc.md b/backends/osc.md new file mode 100644 index 0000000..c784cda --- /dev/null +++ b/backends/osc.md @@ -0,0 +1,81 @@ +### The `osc` backend + +This backend offers read and write access to the Open Sound Control protocol, +spoken primarily by visual interface tools and hardware such as TouchOSC. + +#### Global configuration + +This backend does not take any global configuration. + +#### Instance configuration + +| Option | Example value | Default value | Description | +|---------------|-----------------------|-----------------------|-----------------------| +| `root` | `/my/osc/path` | none | An OSC path prefix to be prepended to all channels | +| `bind` | `:: 8000` | none | The host and port to listen on | +| `destination` | `10.11.12.13 8001` | none | Remote address to send OSC data to. Setting this enables the instance for output. The special value `learn` causes the MIDImonster to always reply to the address the last incoming packet came from. A different remote port for responses can be forced with the syntax `learn@` | + +Note that specifying an instance root speeds up matching, as packets not matching +it are ignored early in processing. + +Channels that are to be output or require a value range different from the default ranges (see below) +require special configuration, as their types and limits have to be set. + +This is done in the instance configuration using an assignment of the syntax + +``` +/local/osc/path = ... +``` + +The OSC path to be configured must only be the local part (omitting a configured instance root). + +**format** may be any sequence of valid OSC type characters. See below for a table of supported +OSC types. + +For each component of the path, the minimum and maximum values must be given separated by spaces. +Components may be accessed in the mapping section as detailed in the next section. + +An example configuration for transmission of an OSC message with 2 floating point components with +a range between 0.0 and 2.0 (for example, an X-Y control), would look as follows: + +``` +/1/xy1 = ff 0.0 2.0 0.0 2.0 +``` + +#### Channel specification + +A channel may be any valid OSC path, to which the instance root will be prepended if +set. Multi-value controls (such as X-Y pads) are supported by appending `:n` to the path, +where `n` is the parameter index, with the first (and default) one being `0`. + +Example mapping: +``` +osc1./1/xy1:0 > osc2./1/fader1 +``` + +Note that any channel that is to be output will need to be set up in the instance +configuration. + +#### Supported types & value ranges + +OSC allows controls to have individual value ranges and supports different parameter types. +The following types are currently supported by the MIDImonster: + +* **i**: 32-bit signed integer +* **f**: 32-bit IEEE floating point +* **h**: 64-bit signed integer +* **d**: 64-bit double precision floating point + +For each type, there is a default value range which will be assumed if the channel is not otherwise +configured using the instance configuration. Values out of a channels range will be clipped. + +The default ranges are: + +* **i**: `0` to `255` +* **f**: `0.0` to `1.0` +* **h**: `0` to `1024` +* **d**: `0.0` to `1.0` + +#### Known bugs / problems + +Ping requests are not yet answered. There may be some problems using broadcast output and input. \ No newline at end of file -- cgit v1.2.3 From 27eba094a067a0879250a3cf73c83df0da5c63a1 Mon Sep 17 00:00:00 2001 From: cbdev Date: Wed, 24 Jul 2019 21:35:10 +0200 Subject: Add detect option to OSC backend --- backends/osc.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'backends/osc.md') diff --git a/backends/osc.md b/backends/osc.md index c784cda..e9aa4d5 100644 --- a/backends/osc.md +++ b/backends/osc.md @@ -5,7 +5,9 @@ spoken primarily by visual interface tools and hardware such as TouchOSC. #### Global configuration -This backend does not take any global configuration. +| Option | Example value | Default value | Description | +|---------------|-----------------------|-----------------------|-----------------------| +| `detect` | `on` | `off` | Output the path of all incoming OSC packets to allow for easier configuration. Any path filters configured using the `root` instance configuration options still apply. | #### Instance configuration @@ -78,4 +80,4 @@ The default ranges are: #### Known bugs / problems -Ping requests are not yet answered. There may be some problems using broadcast output and input. \ No newline at end of file +Ping requests are not yet answered. There may be some problems using broadcast output and input. -- cgit v1.2.3 From 26ee2eacc7d60aa379c9e4b9b9c6b8bcdcd4bc6b Mon Sep 17 00:00:00 2001 From: cbdev Date: Sat, 27 Jul 2019 19:31:21 +0200 Subject: Refactor OSC backend, implement pattern matching --- backends/osc.md | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) (limited to 'backends/osc.md') diff --git a/backends/osc.md b/backends/osc.md index e9aa4d5..b7ce527 100644 --- a/backends/osc.md +++ b/backends/osc.md @@ -23,13 +23,21 @@ it are ignored early in processing. Channels that are to be output or require a value range different from the default ranges (see below) require special configuration, as their types and limits have to be set. -This is done in the instance configuration using an assignment of the syntax +This is done by specifying *patterns* in the instance configuration using an assignment of the syntax ``` /local/osc/path = ... ``` -The OSC path to be configured must only be the local part (omitting a configured instance root). +The pattern will be matched only against the local part (that is, the path excluding any configured instance root). +Patterns may contain the following expressions (conforming to the [OSC pattern matching specification](http://opensoundcontrol.org/spec-1_0)): +* `?` matches any single legal character +* `*` matches zero or more legal characters +* A comma-separated list of strings inside curly braces `{}` matches any of the strings +* A string of characters within square brackets `[]` matches any character in the string + * Two characters with a `-` between them specify a range of characters + * An exclamation mark immediately after the opening `[` negates the meaning of the expression (ie. it matches characters not in the range) +* Any other legal character matches only itself **format** may be any sequence of valid OSC type characters. See below for a table of supported OSC types. @@ -44,6 +52,12 @@ a range between 0.0 and 2.0 (for example, an X-Y control), would look as follows /1/xy1 = ff 0.0 2.0 0.0 2.0 ``` +To configure a range of faders, an expression similar to the following line could be used + +``` +/1/fader* = f 0.0 1.0 +``` + #### Channel specification A channel may be any valid OSC path, to which the instance root will be prepended if @@ -80,4 +94,7 @@ The default ranges are: #### Known bugs / problems +The OSC path match currently works on the unit of characters. This may lead to some unexpected results +when matching expressions of the form `*`. + Ping requests are not yet answered. There may be some problems using broadcast output and input. -- cgit v1.2.3 From aef72140273b3d98a4d86a42f0f3bcce6d5899ca Mon Sep 17 00:00:00 2001 From: cbdev Date: Sun, 28 Jul 2019 23:19:54 +0200 Subject: Fix Lua timing on non-linux --- backends/osc.md | 3 +++ 1 file changed, 3 insertions(+) (limited to 'backends/osc.md') diff --git a/backends/osc.md b/backends/osc.md index b7ce527..1446e06 100644 --- a/backends/osc.md +++ b/backends/osc.md @@ -58,6 +58,9 @@ To configure a range of faders, an expression similar to the following line coul /1/fader* = f 0.0 1.0 ``` +When matching channels against the patterns to use, the first matching pattern (in the order in which they have been configured) will be used +as configuration for that channel. + #### Channel specification A channel may be any valid OSC path, to which the instance root will be prepended if -- cgit v1.2.3