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

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.

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.

setScore
  • gmn: a Guido score defined by a GMN string.
  • gmnf: a Guido score defined by a GMN file.
  • gmnstream: a Guido score defined by a GMN stream (a GMN string that can be written in several times).
  • musicxml: a score defined by a MusicXML string.
  • musicxmlf: a score defined by a MusicXML file.
  • gmn expr: a score defined by a score expression. See section scoreExpr for the score expressions reference.

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.

Piano roll music notation

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

setPianoRoll
  • pianoroll: a piano roll defined by a GMN string.
  • pianorollstream: a piano roll defined by a GMN stream (a GMN string that can be written in several times).
  • pianorollf: a piano roll defined by a guido file (with ".gmn" extension) or by a midi file (with ".mid" extension). Warning: url forms are not supported for midi files.
  • pianoroll expr: a piano roll defined by a score expression. See section scoreExpr for the score expressions reference.

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";

Textual components

setText
  • txt: a textual component.
  • txtf: a textual component defined by a file.
  • html: an html component defined by an HTML string.
  • htmlf: an html component defined by an HTML file.

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

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;

Vectorial graphics

setVGraphics
  • svg: SVG graphics defined by a SVG string.
  • svgf: vectorial graphics defined by a SVG file.
  • rect: a rectangle specified by a width and height. Width and height are expressed in scene coordinates space, thus a width or a height of 2 corresponds to the width or a height of the scene.
  • ellipse: an ellipse specified by a width and height.
  • polygon: a polygon specified by a sequence of points, each point being defined by its (x,y) coordinates. The coordinates are expressed in the scene coordinate space, but only the relative position of the points is taken into account (i.e a polygon A = { (0,0) ; (1,1) ; (0,1) } is equivalent to a polygon B = { (1,1) ; (2,2) ; (1,2) }).
  • curve: a sequence of 4-points bezier cubic curve. If the end-point of a curve doesn't match the start-point of the following one, the curves are linked by a straight line. The first curve follows the last curve. The inner space defined by the sequence of curves is filled, using the object color. The points coordinates are handled like in a polygon.
  • arc: an arc defined by its enclosing rectangle and the start and end angles. Angles are in degrees and express counter-clockwise directions.
  • line: a simple line specified by a point (x,y) expressed in scene coordinate space or by a width and angle. The point form is used to compute a line from (0,0) to (x,y), which is next drawn centered on the scene.

Note: Width and/or height parameters can be expressed as float values or as scene relative values. See section whcontrol.

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.;

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 graphsig.

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

setGraphicSignal
  • graph: graphic of a signal. See section graphsig for details about the graph objects data.
  • fastgraph: fast rendering graphic signal. See also section graphsig.
  • faust: a FAUST object as a plugin (see section faust)
  • faustdsp: a FAUST object defined by a string (see section faust)
  • faustdspf: a FAUST object defined by a file (see section faust)

Media files

Images, video and audio are supported using various formats. See section fileset for more details on the supported formats.

setMedia
  • img: an image file. The image format is inferred from the file extension.
  • memimg: a memory capture of the object given as argument. objectPath indicates the target object that is captured with all its childrens. It may be an object name or a path to an object. Simple object names and relative path are looked for in the receiver layer.
  • video: a video file. The video format is inferred from the file extension. Note that navigation through the video is made using its date.
  • audio: an audio file. The audio format is inferred from the file extension. audio objects appear as a waveform but this waveforom is not (yet) computed from the audio data but randomly generated.

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.

Miscellaneous

setMisc
  • layer: a graphic layer, may be viewed as a container (see section layers).
  • grid: a white transparent object that provides a predefined time to graphic mapping (see section grid for more details and section mapping for time to graphic relations). The parameters are int32 values representing the number of columns and rows.

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, audio 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

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 urlevents).

The file type

setFile
  • file: a generic type to handle file based objects. Actually, the file type is translated into a one of the txtf, gmnf, img, audio or video types, according to the file extension (see table fileTranslate).

See also: the application rootPath message (section ITL) for file based objects.

file extension translated 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
.mp3 .wav .aiff .aif, .m4a, .aac audio
.dsp faustdspf

File extensions supported by the file translation scheme.

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";

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 Httpd.

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
  • port: a port number for the socket communication.
  • frequency: a minimum time in millisecond between two Screen updated notifications.

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 Httpd).