Introduction | Main elements |
Messages sent and received |
Graphical interface |
Scripts | Reference | Functions index |
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: - serial (ASCII Serial Port).
Example: - udp (Raw UDP, PureData compatible), the IP and the port must be
specified.
Example: - http (GET Request), standard URL construction
Example: - 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
orpgm (program change)
.
Example:
Example:
Example: direct
Send a direct message to IanniX for high-speed orders.
Example:
Alias
Instead of changing IP manually in messages, you can affect the ip_out
variable. This variable is changeable directly in the Inspector > Network.
Instead of changing MIDI port manually in messages, you can affect the midi_out
variable. This variable is changeable directly in the Inspector > Network.
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 triggersnb_curves
number of cursorsnb_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 is1234
, the default adress is/iannix
Example in PureData:serial
(ASCII Serial Port)
Example with Arduino:udp
(Raw UDP, PureData compatible), the default port is1235
.
Example in PureData:http
(GET Reply)
Example in PHP:midi
(MIDI Protocol)direct
Send a direct message to IanniX for high-speed orders.
Example:nxscript file
(JavaScript), an example is given with IanniX
Example:
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:
- Format:
- 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:
- 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:
- 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:
- 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:
- 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:
- This MIDI message sends note numbers based on the cursor_angle (range 0 to
360), scaled to the range 60 to 100:
- 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.
Conditional Actions
- A Javascript conditional operator of the form
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.
- 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.
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.
- 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.
- 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.
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: or
Copy / paste this example in Iannix to understand how the code works!
add curve 1
|