Module xRules
Rewrite MIDI/OSC messages on-the-fly using generated code
About
xRules works by applying "rules" to the input, using specific conditions as triggers.
Each rule can then change the input in a number of different ways.
An implementation of this class (also called xRules) is available from the Renoise tools page (http://www.renoise.com/tools/xrules). The tool adds a visual interface, device management and more.
Functions
Tables
| self.rulesets | table |
| self.midi_inputs | table |
| self.midi_outputs | table |
| self.osc_pattern_map | table |
| self.aspect_handlers | table |
| self.channel_handlers | table |
Fields
| self.active | boolean |
| self.callback | define a function to display matched messages |
| self.midi_input | xMidiInput |
| self.nrpn_order | number, default order of NRPN bytes (output) |
| self.terminate_nrpns | boolean, whether to terminate NRPNs (output) |
| self.osc_devices | table |
| self.osc_client | xOscClient, used for internal routing |
| self.osc_router | xOscRouter, incoming OSC is passed here |
| self.automation | xAutomation, built-in automation recording |
| self.ruleset_observable | observable, track when rulesets are added/swapped/removed |
| self.selected_ruleset_index | int, 0 = no selection |
Functions
- input_sysex (sysex_msg, port_name)
-
input raw sysex messages here (immediately matched)
Parameters:
- sysex_msg (table), sysex message
- port_name (string)
- input_osc (osc_msg, device)
-
pass osc message into router
Parameters:
- osc_msg , renoise.Osc.Message
- device , xOscDevice
- match_message (xmsg, ruleset_idx, rule_idx, force_midi)
-
pass message into our (active) rulesets
Parameters:
- xmsg (xMidiMessage or xOscMessage)
- ruleset_idx (int) optional (set to match against specific ruleset)
- rule_idx (int) optional (set to match against specific rule)
- force_midi (boolean) force match (used by routings)
Returns:
-
matches (table)
{
ruleset: index rules: {index,index,index}},
- transmit (out, xmsg_in, ruleset_idx, rule_idx)
-
transmit matched message - either internally or externally
Parameters:
- out (table) {target=xRules.OUTPUT_OPTIONS,xmsg=xMessage}
- xmsg_in (xMessage)
- ruleset_idx (int)
- rule_idx (int)
Returns:
- bool, true when triggered
- string, error message when failed
- remove_osc_patterns (ruleset_idx, rule_idx)
-
remove pattern from the osc_router
Parameters:
- ruleset_idx , int
- rule_idx , int (optional, leave out to remove whole ruleset)
Returns:
-
int, first route index
- maintain_osc_pattern_map (args, route_idx)
-
maintain active indices of registered rules after they are added/removed
Parameters:
- args (table) {type,index}
- route_idx (int)
- add_osc_patterns (ruleset_idx)
-
add/replace patterns in the osc_router
Parameters:
- ruleset_idx
- register_with_osc_router (osc_pattern, ruleset_idx, rule_idx)
-
register the osc pattern
Parameters:
- osc_pattern
- ruleset_idx
- rule_idx
Returns:
- int, index of pattern within router
- boolean,string
- load_ruleset (file_path, idx)
-
Parameters:
- file_path
- idx
Returns:
-
boolean,string
- toggle_ruleset (ruleset_idx)
-
toggle active state of ruleset
Parameters:
- ruleset_idx
- add_ruleset (ruleset_def, ruleset_idx)
-
add ruleset, attach notifiers
Parameters:
- ruleset_def (table)
- ruleset_idx (int), specify index at which to insert (optional)
Returns:
- xRuleset
- boolean,string
- remove_ruleset (idx)
-
Parameters:
- idx (int)
Returns:
- boolean,string
- boolean,string
- replace_ruleset (file_path, idx)
-
Parameters:
- file_path
- idx
Returns:
-
boolean,string
- save_ruleset ()
-
save current ruleset to file
Returns:
-
boolean,string
- revert_ruleset ()
-
revert changes (reload file)
Returns:
-
boolean,string
- open_midi_input (port_name)
-
open access to midi port
Parameters:
- port_name
- add_osc_device (device)
-
add device, or replace existing with same name
Parameters:
- device , xOscDevice (if not defined, create from scratch) avoid triggering the
- remove_osc_device (device_idx)
-
Parameters:
- device_idx , integer
Returns:
-
xRuleset,int(index) or nil
- get_ruleset_by_name (str_name)
-
Parameters:
- str_name
Returns:
-
xRuleset,int(index) or nil
Tables
- self.rulesets
-
table
- self.midi_inputs
-
table
- self.midi_outputs
-
table
- self.osc_pattern_map
-
table
, relations between osc-patterns and osc router associative array, ordered by the pattern uid {ruleindex=int,rulesetindex=int,router_index=int} - self.aspect_handlers
-
table
rules associated with aspects - self.channel_handlers
-
table
rules associated with channels
Fields
- self.active
- boolean
- self.callback
-
define a function to display matched messages
- xmsg_in (xMessage)
- ruleset_idx (int)
- rule_idx (int)
- self.midi_input
- xMidiInput
- self.nrpn_order
- number, default order of NRPN bytes (output)
- self.terminate_nrpns
- boolean, whether to terminate NRPNs (output)
- self.osc_devices
-
table
- self.osc_client
- xOscClient, used for internal routing
- self.osc_router
- xOscRouter, incoming OSC is passed here
- self.automation
- xAutomation, built-in automation recording
- self.ruleset_observable
- observable, track when rulesets are added/swapped/removed
- self.selected_ruleset_index
- int, 0 = no selection