Introduction | Main elements | Messages sent and received | Graphical interface | Scripts | Reference | Functions index

Version française

## Principle

Message handling is the main function of IanniX. They can be sent by cursors and triggers.

To see if the messages are actually sent or received, IanniX displays a trace in the "Messages" section of the inspector.

Triggers usually send one only message when a cursor goes past them. IanniX is limited to sending one message per millisecond maximum.

Cursors, by default, generate messages every 20 ms (but you can change this time).

## Message construction

### General pattern

To construct a message in IanniX, you need to follow the model below:

`<protocol>://<destination>/<address> <arguments>`

### Protocols

- osc (Open Sound Control), the IP, the port and the address must be specified.
  Example: `osc://127.0.0.1:1234/oscAddress`
- serial (ASCII Serial Port).
  Example: `serial://`
- udp (Raw UDP, PureData compatible), the IP and the port must be specified.
  Example: `udp//127.0.0.1:5678/`
- http (GET Request), standard URL construction
  Example: `http://localhost/myapp/page.php`
- midi (MIDI Protocol), the portname must be specified without spaces, followed by a slash, followed by the type of MIDI message which can be: `note`, `cc`, `bend` or `pgm (program change)`.
  Example: `midi://portname/note channel note velocity
  ` Example: `midi://portname/cc channel controller value`
  Example: `midi://portname/bend channel value`
- `direct` Send a direct message to IanniX for high-speed orders.
  Example: `direct://`

### Arguments

The arguments represent the useful data of the IanniX message. This is a series of variables that describe the state of an object when the message is sent. These variables are detailed in the references section for triggers and cursors.

In addition to the variables, you can of course specify values or strings directly in the message.

Finally, three global variables can be used in all messages:

- `nb_triggers` number of triggers
- `nb_curves` number of cursors
- `nb_cursors` number of curves

## Edit sent messages

To edit the message that a element has to send, click on "Edit" in the inspector after having selected the object or double-click on the object itself to display this window:

Double-click on the message in order to modify it. Click on "-" to delete it and on "+" to add other messages.

## Reception of a message

IanniX can be controlled by:

- `osc` (Open Sound Control), the default port is `1234`, the default adress is `/iannix`
  Example in PureData: `send /iannix/zoom 100`
- `serial` (ASCII Serial Port)
  Example with Arduino: `Serial.println("zoom 100");`
- `udp` (Raw UDP, PureData compatible), the default port is `1235`.
  Example in PureData: `send zoom 100`
- `http` (GET Reply)
  Example in PHP: `echo "zoom 100";`
- `midi` (MIDI Protocol)
- `direct` Send a direct message to IanniX for high-speed orders.
  Example: `direct:// zoom 100`
- `nxscript file` (JavaScript), an example is given with IanniX
  Example: `iannix.execute("zoom 100");`

You must respect these syntaxes in order to make IanniX able to read your messages. Consult your software documentation to correctly format sending information.

All functions supported by IanniX are described in the reference.

## MIDI Message Details

- The output port must be specified without spaces or slashes.
- On Macintosh (and Linux?) systems IanniX creates a virtual output port called `IanniX_Out` that can be opened in other MIDI applications.
- Other available MIDI ports available on the system are listed on IanniX startup in the Message view of the Inspector.
- Other available MIDI ports available on the system are listed on IanniX startup in the Message view of the Inspector.
- MIDI message parameters are converted to integers if necessary and are truncated to the required range.

MIDI Note-On/Note-Off Messages

- Format: midi://portname/note channel note velocity
- Format: midi://portname/note channel note velocity duration
- The channel must be in the range 0 to 15 (corresponding to MIDI channels 1 to 16).
- The note must be in the range 0 to 127.
- The duration is expressed in milliseconds. e.g. 1000 is one second.
- The duration parameter is optional. If omitted, the note-off will not be automatically sent. The note-off message (velocity zero) must be sent by some other means.
- The optional duration parameter in the message is provided for when it is desired to have a variable note duration, set by some parameter from the score each time the message is triggered.
- A zero velocity note equals note-off.

MIDI Continuous Controller Messages

- Format: midi://portname/cc channel controller value
- The channel must be in the range 0 to 15 (corresponding to MIDI channels 1 to 16).
- The controller must be in the range 0 to 127.
- The value must be in the range 0 to 127.
- See a MIDI specification or your synthesizer's documentation for available controller numbers and how they will affect the sound.

MIDI Pitch Bend Messages

- Format: `midi://portname/bend channel value`
- The channel must be in the range 0 to (corresponding to MIDI channels 1 to 16).
- The bend value must be in the range 0 to 16383.
- A bend value of 8192 specifies zero bend. Values below this bend down and above this bend up.

MIDI Program Change Messages

- Format: `midi://portname/pgm channel value`
- The channel must be in the range 0 to 15 (corresponding to MIDI channels 1 to 16).
- The value of pgm must be in the range 0 to 127.
- For many synthesizers the Progam Change message selects a new program, patch or sound with that number in the sound bank.

All functions supported by IanniX are described in the reference.

## Javascript in Messages

Javascript expressions may be used in messages anywhere an argument could be used.

### Basics

- A Javascript expression is indicated by being enclosed in curly braces, separated from other arguments by at least one space.
- Any variable (see Reference section) that is available for a normal message are also available for use in Javascript expressions.
- The value inserted into a message by a Javascript expression is the value returned by the expression, or by the last single expression if the complete expression consists of multiple statements.
- In addition to the full power of Javascript, a number of convenience functions are provided for frequently required computations. (See Scripting section).
- It is possible to construct useful message expressions even with a limited knowledge of Javascript. The syntax is also very similar to C or Java. To learn Javascript, you are referred to any of the many tutorials or reference documents on the Internet, or to a book on Javascript.

### Examples:

- This message sends the sum of the cursor_xPos and cursor_yPos:
  `osc://127.0.0.1:1234/oscAddress {cursor_xPos+cursor_yPos}`
- This message sends the sin of three times the cursor_angle. The sin which returns values of -1 to 1 is scaled into the range 0 to 1:
  `osc://127.0.0.1:1234/oscAddress {map(sin(3*cursor_angle),-1,1,0,1)}`
- This MIDI message sends note numbers based on the cursor_angle (range 0 to 360), scaled to the range 60 to 100:
  `midi://portname/note channel {map(cursor_angle ,0, 360, 60, 100)} velocity`
- This MIDI message sends note numbers based on the cursor_angle scaled to the range 60 to 100, note velocities in the range 70 to 127 based on the cursor_time_percent, and random note durations in the range 200 milliseconds to 1000 milliseconds.
  `midi://portname/note channel {map(cursor_angle ,0, 360, 60, 100)} {range(cursor_time_percent, 70, 127)} {random(200,1000)}`

### Conditional Actions

- A Javascript conditional operator of the form `test ? DoIfTrue : DoIfFalse` allows the evaluation of the expression to be altered according to a logic test of variable values.
- Example: This message sends zero when the cursor_time is less than 2 and sends the trigger_xPos if the time is greater than 2.
  `osc://127.0.0.1:57120/cursor {(cursor_time>2)?trigger_xPos:0}`
- Example: This message sends the collision distance scaled to a range of 0 to 1, but only if the cursor_angle is greater than the collision_angle. Otherwise the message sends zero. Note: The scaling assumes the collision_distance is in the range 0 to 5.
  `osc://127.0.0.1:1234/oscAddress {(cursor_angle > collision_angle) ? map(collision_distance ,0 ,5 ,0 ,1): 0}`

### Message Suppression

- A message is suppressed (not sent) if any of its expressions returns the string "suppress".
- Example: The following message sends a 1 if the right side of the cursor collides with a trigger. The message is not sent if the left side of the cursor collides with the trigger.
  `osc://127.0.0.1:1234/oscAddress {(trigger_side == 1) ? 1 : "suppress")}`
- Example: Cursor variables of type `collision_<variablename>(e.g. collision_xPos)` only have a meaningful value while a collision with a curve is taking place. However cursor messages are produced continually while the score is playing. Therefore when a collision is not taking place these variables return "no". A conditional expression can be used to suppress the message except when the collision is actually taking place.
  `osc://127.0.0.1:1234/oscAddress {(collision_xPos == "no") ? "suppress" : collision_xPos}`
- Example: This message only is sent if the trigger is in the same group as the colliding cursor. If sent, the message includes the trigger_id, trigger_xPos and trigger_yPos.
  `osc://127.0.0.1:57120/trigger {(trigger_group_id==cursor_group_id)?trigger_id:"suppress"} trigger_xPos trigger_yPos`

### Errors

- If an expression contains an error, the text "**error**" is returned and appears in the message in place of the returned value.
- Messages can be checked for errors in the Inspector Message window while the score is playing.
- Errors might include Javascript syntax errors or references to nonexistent variables or functions.

## Recursion

IanniX can be controlled by IanniX itself (!). You can use all the protocols described above, but we recommend using OSC to communicate between two IanniX applications on network computers and use the `direct` command to send messages inside one IanniX application.
Example: `osc://127.0.0.1:1234/iannix/setTime 11 0` or `direct:// setTime 11 0`.

| Copy / paste this example in Iannix to understand how the code works! `add curve 1 setPointsEllipse current 2 2 setPos current 0 0 0 0 add cursor 11 setCurve 11 1 add trigger 21 setPos current -2 0 0 setMessage current 10, direct:// setTime 11 0`