Chapter 5
The ’set’ message

The set messages can be sent to any address with the form /ITL/scene/identifier. The global form of the message is:

setMsg PICT

It sets a scene component data.

When there is no destination for the OSC address, the component is first created before being given the message.

When the target destination type doesn’t correspond to the message type, the object is replaced by an adequate object.

5.1 Symbolic music notation

Symbolic music notation support is based on the Guido Music Notation format [GMN] or on the MusicXML format. MusicXMl is supported via conversion to the GMN format when the MusicXML library is present.

setMsg PICT

EXAMPLE
Creating a music score using a Guido Music Notation language string.

/ITL/scene/myObject set gmn "[ a b g ]";

Creating the same music score as a stream.

/ITL/scene/myObject set gmnstream "[ a";
/ITL/scene/myObject write "b";
/ITL/scene/myObject write "g";

NOTE For compatibility with previous versions, passing a MusicXML string to a gmn object or a MusicXML file to a gmnf object may succed since the system tries to parse the content as GMN content or as MusicXML content when the former fails.

NOTE Conversion from MusicXML to GMN could be achieved manually using a command line tool that is distributed with the MusicXML library (see at https://github.com/dfober/libmusicxml). It allows to improve the output GMN code afterhand.

5.2 Piano roll music notation

Piano roll music notation is based on the Guido Music Notation format [GMN].

setMsg PICT

EXAMPLE
Creating a pianoroll using a Guido Music Notation language string.

/ITL/scene/myObject set pianoroll "[ a b g ]";

Creating the same piano roll as a stream.

/ITL/scene/myObject set pianorollstream "[ a";
/ITL/scene/myObject write "b";
/ITL/scene/myObject write "g";

5.3 Textual components

setMsg PICT

Text may be specified by a single quoted string or using an arbitrary count of parameters that are converted to a single string with a space used as separator.

txtStream PICT

EXAMPLE
Creating a text object.

/ITL/scene/myObject set txt "Hello ... world!";

Setting the content of a text object using a values stream.

/ITL/scene/myObject set txt Hello 1 world and 0.5;

5.4 Vectorial graphics

setMsg PICT

EXAMPLE
Creating a rectangle with a 0.5 width and a 1.5 height.

/ITL/scene/myObject set rect 0.5 1.5;

Creating a line specified using width and angle.

/ITL/scene/myObject set line wa 1. 45.;

5.5 Signals and graphic signals

Signals are special objects that are stored in a special signal node and that may be composed in parallel to produce graphic signals. Signals and graphic signals are decribed in section 14 p.113.

Signals and computation on signals may be based on FAUST objects that are actually signals processors. FAUST objects are decribed in section 20.1 p.211.
For more information about the FAUST language, see at http://faust.grame.fr.

setMsg PICT

5.6 Images and video

Images and video are supported using various formats. See section 5.9 p.46 for more details on the supported formats.

setMsg PICT

EXAMPLE
Creating an image.

/ITL/scene/myObject set img "myImage.png";

Creating a memory image of a scene.

/ITL/scene/myObject set memimg "/ITL/scene";

NOTE
It is necessary to have an object or scene graphically rendered before a capture can be made. Since the actual graphic rendering is made asynchronously to the model update, a sequence of messages like the following:

/ITL/scene/myObject set gmn "[a f g]";
/ITL/scene/capture set memimg myObject;

won’t work if the messages are handled by the same time task. A delay is necessary between the two messages. To make sure all the objects have been rendered, you can use the scene endPaint event.

5.7 Miscellaneous

setMsg PICT

5.8 File based resources

Most of the types can be either expressed with the corresponding data, or by a path to a file containing the data. For the latter form, the object type is generally suffixed with an ’f’ (e.g. txtf, htmlf, gmnf, musicxmlf, svgf, faustf). The img and video types have only a file form (and no ’f’ suffix).
A file path can be expressed as a Unix path (absolute or relative - see the scene or application rootPath message for relative paths handling), but also as an URL. Only the http: protocol is currently supported.

When the system encounters an URL, it creates an intermediate object that is in charge of retrieving the corresponding data. This object has a specific url type that takes the target type and an url as arguments. It has a graphic appearance (actually a light gray box containing the object name and the target url) that can be controled like for any regular object.

urlType PICT

The url intermediate object acts as a proxy for the target object and will transfer all its properties once the data are ready. A client can thus interact transparently with the target adress, whatever the status of the download request.

EXAMPLE
Creating a score using an URL:

/ITL/scene/score set gmnf "http://anyhost.adomain.org/score.gmn";
  is equivalent to
/ITL/scene/score set url gmnf "http://anyhost.adomain.org/score.gmn";

NOTE The url object handles specific events : success, error and cancel (see the section 16.1.4 p.161).

5.9 The file type

setFile PICT

See also: the application rootPath message (section 8 p.76) for file based objects.


Table 5.1: File extensions supported by the file translation scheme.



file extensiontranslated type


.txt .text txtf
.htm .html htmlf
.gmn gmnf
.xml musicxmlf
.svg svgf
.jpg .jpeg .png .gif .bmp .tiff img
.avi .wmv .mpg .mpeg .mp4 .mov .vob video
.dsp faustdspf



EXAMPLE
Creating an image using the file type.

/ITL/scene/myObject set file "myImage.png";
  is equivalent to
/ITL/scene/myObject set img "myImage.png";

5.10 Web objects

A score can make its content available to the Internet using specific components that provide an image of the scene over http or websocket protocols.

The httpd server depends on the Httpd server plugin and is described in section 20.3 p.223.

The websocket server provides a two-ways communication between INScore and distant clients. The server sends notifications to client using a Screen updated text message when the scene is updated. Clients can request an image by sending a getImage text message to the server. The server responds with a image of the scene in png format, using a Blob type javascript object.

webobject PICT

NOTE
A busy port prevents the server to start. The server status can be checked with the get status message.

EXAMPLE
Creating an websocket server using the port 1234 and limiting the notifications rate to one per 500 milliseconds.

/ITL/scene/myObject set websocket 1234 500;

See also: the http web server plugin (section 20.3 p.223).