Scintillator Scinth Server Command Reference

OSC Communication Details

While the SuperCollider synth programs support a variety of connection modalities and multi-user scenarios, at present scinsynth only supports a single client commnicating exclusively over UDP. For asynchronous messages the server will respond to whatever UDP address and port messages are received from.

In general Scintillator attempts to follow the command syntax and semantics of the SuperCollider sound synthesis servers, with the addition of a /scin_ prefix to each OSC command and response. In some cases the commands are identical, and the documentation has been copied verbatim from the Server Command Reference.

Some commands are marked as asynchronous, which in this context means they will send a response message back to the sender, sometimes /scin_done, upon completion of the command. For any command marked as asynchronous Scintillator is designed to always return a message, even if the execution of the command failed or the message body didn't parse.

Master Controls

/scin_quit

Quit program. Exits the scinsynth server.

Asynchronous.: Replies to sender with /scin_done just before completion.

/scin_status

Query the status. Replies to sender with the following message:

/scin_status.reply

int	number of Scinths in the render tree.
int	number of Groups in the render tree.
int	number of loaded ScinthDefs.
int	cumulative number of warnings in log.
int	cumulative number of errors in log.
double	approximate graphics memory consumed, in bytes.
double	approximage graphics memory available, in bytes. Some graphics drivers don't support this statistic, in which case it will be 0.
int	target frame rate in frames per second (can be -1 or 0)
double	computed mean framerate.
int	number of dropped frames, if running real time, 0 otherwise.

/scin_dumpOSC

Log incoming OSC messages.

int

0 to disable logging. Nonzero to enable.

/scin_sync

Notify when all outstanding aync commands have completed.

Replies with a /scin_synced message when all asynchronous commands received before this one have completed. The reply will contain the sent unique ID.

Asynchronous.: Replies to sender with /scin_synced, ID when complete.

/scin_logLevel

Set the logging level for the log streams. Lower log levels are inclusive of all higher log levels, so they tend to log more, and the highest log level turns off logging. This overrides any command-line argument supplied to scinsynth at startup.

This command is similar to the SuperCollider server command /error but offers more options for access to the built-in logging.

int

log level

The values for the log level are as follows:

0	Trace
1	Debug
2	Informational
3	Warnings
4	Errors
5	Critical Errors
6	Disable Logging

/scin_version

Query the Scintillator version. Replies to sender with the following message:

/scin_version.reply

string	Program name. Will always be "scinsynth".
int	Scintillator major version number.
int	Scintillator minor version number.
int	Scintillator patch version number.
string	Git branch name.
string	First seven hex digits of the commit hash.

It is expected that the scinsynth binary will always have the same major, minor, and patch version as the Scintillator Quark.

Scinth Definition Commands

/scin_d_recv

Recive a Scinth definition yaml file.

string	A string of yaml data containing one or more ScinthDef documents.
bytes	optional, an OSC message to execute upon completion.

Asynchronous.: Replies to sender with /scin_done when complete.

/scin_d_load

Load a ScinthDef yaml file from disk.

string	pathname of file to load.
bytes	optional, an OSC message to execute upon completion.

Asynchronous.: Replies to sender with /scin_done when complete.

/scin_d_loadDir

Load a directory of Scinth definitions.

string	directory of *.yaml files to load.
bytes	optional, an OSC message to execute upon completion.

Asynchronous.: Replies to sender with /scin_done when complete.

/scin_d_free

Delete Scinth defenitions. Note that any existing Scinths will continue to run, and the resources associated with this ScinthDef will not be reclaimed until all running Scinth instances built from this ScinthDef are also freed.

N * string

ScinthDef names to free.

Node Commands

/scin_n_free

Delete a node.

N * int

node ID

Stops a node abruptly, removes it from its group, and frees its memory. More than one nodeID may be specified as additional integer arguments in the message. If a node is a group this command will free all contained nodes as well.

/scin_n_run

Turn node on or off from rendering.

int	node ID
int	run flag

if the run flag is set to zero then the node will not be rendered.
if the run flag is set to any nonzero value then it will be rendered.

Can take pairs of arguments and will apply the run flag to each provided node ID at the same time.

/scin_n_set

Set a node's control value(s).

int

node ID

N *

int or string	A control index or name
int or float	A control value

/scin_n_before

Place a node before another.

N *

int	the ID of the node to place (A)
int	the ID of the node before which the above is placed (B)

Places node A in the same group as node B, to execute immediately before node B.

/scin_n_after

Place a node after another.

N *

int	the ID of the node to place (A)
int	the ID of the node after which the above is placed (B)

Places node A in the same group as node B, to execute immediately after node B.

/scin_n_order

Move and order a list of nodes.

int	add action (0,1,2 or 3 see below)
int	add target ID
N * int	node IDs

Move the listed nodes to the location specified by the target and add action, and place them in the order specified. Nodes which have already been freed will be ignored.

add actions:

0	construct the node order at the head of the group specified by the add target ID.
1	construct the node order at the tail of the group specified by the add target ID.
2	construct the node order just before the node specified by the add target ID.
3	construct the node order just after the node specified by the add target ID.

Scinth Commands

/scin_s_new

Create a new Scinth.

string

scinth definition name

int

scinth ID

int

add action

int

add target ID

N *

int or string	A control index or name
int or float	A control value

Create a new Scinth instance from the given ScinthDef, give it an ID, and add it to the tree of nodes. There are four ways to add the node to the tree as determined by the add action argument, with the same values as the SuperCollider audio synth server, defined as follows:

add actions:

0	add the new node to the the head of the group specified by the add target ID.
1	add the new node to the the tail of the group specified by the add target ID.
2	add the new node just before the node specified by the add target ID.
3	add the new node just after the node specified by the add target ID.
4	the new node replaces the node specified by the add target ID. The target node is freed.

NOTE: The SuperCollider Synthesis Server command reference specifies if the provided ID number is -1, the server reserves all negative numbers for IDs, and so will assign a unique negative value to the Synth instance. Scintillator server is similar, but will treat any negative value as a request for a unique ID to be assigned.

Group Commands

/scin_g_new

Create a new group.

N *

int	new group ID
int	add action (0,1,2, 3 or 4 see below)
int	add target ID

Create a new group and add it to the tree of nodes. There are four ways to add the group to the tree as determined by the add action argument which is defined as follows (the same as for /s_new):

add actions:

0	add the new group to the the head of the group specified by the add target ID.
1	add the new group to the the tail of the group specified by the add target ID.
2	add the new group just before the node specified by the add target ID.
3	add the new group just after the node specified by the add target ID.
4	the new node replaces the node specified by the add target ID. The target node is freed.

Multiple groups may be created in one command by adding arguments.

/scin_g_head

Add node to head of group.

N *

int	group ID
int	node ID

Adds the node to the head (first to be executed) of the group.

/scin_g_tail

Add node to tail of group.

N *

int	group ID
int	node ID

Adds the node to the tail (last to be executed) of the group.

/scin_g_freeAll

Deletes all nodes in a group, leaving the group empty but intact.

N * int

group ID(s)

Recursively frees all nodes in the groups specified.

/scin_g_deepFree

Free all Scinths in this group and all its sub-groups.

N * int

group ID(s)

Traverses all groups below this group and frees all the Scinths. Sub-groups are not freed. A list of groups may be specified.

/scin_g_dumpTree

Post a representation of this group's node subtree.

N *

int	group ID
int	flag; if not 0 the current control (arg) values for synths will be posted

Posts a representation of this group's node subtree, i.e. all the groups and synths contained within it, optionally including the current control values for synths. The information is posted at the informational level in the log.

/scin_g_queryTree

Get a representation of this group's node subtree.

N *

int	group ID
int	flag: if not 0 the current control (arg) values for Scinths will be included

Request a representation of this group's node subtree, i.e. all the groups and synths contained within it. Replies to the sender with a /g_queryTree.reply message listing all of the nodes contained within the group in the following format:

int

flag: if Scinth control values are included 1, else 0

int

node ID of the requested group

int

number of child nodes contained within the requested group

then for each node in the subtree:

int

node ID

int

number of child nodes contained within this node. If -1 this is a Scinth, if >=0 it's a group

then, if this node is a Scinth:

symbol

the ScinthDef name for this node.

then, if flag (see above) is true:

int

numControls for this synth (M)

M *

symbol	control name
float	value

N.B. The order of nodes corresponds to their execution order on the server. Thus child nodes (those contained within a group) are listed immediately following their parent.

ImageBuffer Commands

The server leaves designation of unique image buffer numbers to the client. Allocation of an image buffer with a number already associated with another image buffer will result in the prior image buffer being deallocated.

/scin_ib_allocRead

Decodes an image, optionally resamples it to the provided size, allocates memory on the graphics device, and transfers the decoded image data to the image buffer.

int	buffer number
string	path to image file to decode
int	width of image (can be -1 to respect width of source image)
int	height of image (can be -1 to respect height of source image)
bytes	(optional) an OSC message to execute upon completion

If both width and height are provided the source image will be resampled to that size, ignoring aspect ratio. If one of the width or height values is -1 then the image will be resampled to a size respecting the provided dimension and maintaining the aspect ratio of the other dimension. If both values are -1 then the image won't be resampled but will be loaded at original size. For example, for a source image that is 200 pixels wide and 100 pixels tall:

width requested	height requested	buffer width	buffer height	notes
400	100	400	100	Server will disregard aspect ratio of source image if both requested dimensions are nonnegative.
-1	50	100	50	In order to maintain 2:1 aspect ratio server has computed a width of 50 px.
400	-1	400	200	In order to maintain 2:1 aspect ratio server has computed a height of 400 px.
-1	-1	200	100	Server has allocated width and height of source image.

Asynchronous.: Replies to sender with /scin_done /scin_ib_readImage bufNum when complete.

/scin_ib_query

Get ImageBuffer info.

N * int

Image buffer number(s)

Responds to the sender with a /scin_ib_info message. The arguments to /scin_ib_info are as follows:

N *

int	Image bufer number
int	Image size in bytes, 0 if invalid
int	Image width, -1 if invalid
int	Image height, -1 if invalid

Non Real Time Commands

/scin_nrt_screenShot

Server will save a screenshot image of the next rendered frame to the supplied file name.

string	file name and path to save the screenshot to.
string	(optional) a mime type of the desired image file, to guide container and codec selection.

Asynchronous.: Replies to sender twice with updates. The first response is /scin_nrt_screenShot.ready, followed by the file name, which is sent once the screenshot is ready to record, and lastly a boolean with file status. The second reponse is on completion of the saving of the screenshot file, the server replies with /scin_done followed by /scin_nrt_screenShot, the name of the file saved, and a boolean with status on completion.

/scin_nrt_advanceFrame

If framerate is at zero, renders one frame at the current time and then advances the time by the supplied fractional increment, in seconds.

int	numerator for fractional time advancement
int	denominator for fractional time advancement

Asynchronous.: Replies to sender with [ /scin_done, /scin_nrt_advanceFrame ].

Testing, Debugging and Development Commands

Commands useful for accessing the diagnostic functions or automated validation of scinsynth behavior.

/scin_echo

Respond back to the caller with the provided message.

bytes

An OSC message to respond to the caller with.

Asynchronous.: Replies to the sender immediately with the provided message blob.

/scin_logAppend

Add the supplied string to the logs at the supplied level.

int	A log level, from 0-6, to associate with this log entry. See the table in /scin_logLevel for the log levels.
string	The string to place in the logs.

/scin_sleepFor

Puts one of the asynchronous worker threads to sleep for the specified number of seconds.

int

The number of seconds to sleep for.

NOTE: This will tie up one of the available threads on the server, and is therefore not recommended for use in a performance or recording context.

Asynchronous.: Replies to the sender on wakeup with /scin_awake.

/scin_logCrashReports

Prints a complete list of crash reports in the log, at the informational log level (2).

Asynchronous.: Replies to sender with [ /scin_done, /scin_logCrashReports ].

subsection:/scin_uploadCrashReport

Mark a specific crash report, or all not uploaded reports, as upload requested.

string

A crash report UUID, or the string "all", in which case all reports will marked for upload.

Asynchronous.: Replies to sender with [ /scin_done, /scin_uploadCrashReport ].

helpfile source: /tmp/tmpjbuo4r8ibaryon_Scintillator/Scintillator/Reference/Scintillator-Scinth-Server-Command-Reference.schelp
link::Scintillator/Reference/Scintillator-Scinth-Server-Command-Reference::

Scintillator Scinth Server Command ReferenceExtension

Scintillator Scinth Server Command Reference
Extension