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 Reference/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.
/scin_status
Query the status. Replies to sender with the following message:
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.
/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:
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. |
/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. |
/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. |
/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.
N* |
|
-
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 * |
|
/scin_n_before
Place a node before another.
N * |
|
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 * |
|
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.
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 * |
|
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:
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 * |
|
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):
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 * |
|
Adds the node to the head (first to be executed) of the group.
/scin_g_tail
Add node to tail of group.
N * |
|
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 * |
|
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 * |
|
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: |
|
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. |
/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 * |
|
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. |
/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 |
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. |
/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./scin_logCrashReports
Prints a complete list of crash reports in the log, at the informational log level (2).
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. |