API | SuperCollider 3.13.0 Help

Description

An API is a way to encapsulate all of the publically callable functions for a single application, composition, piece, class, service etc. in one universally accessible place.

Each API object has a name (eg. "server") and a dictionary of functions.

These can then be called:

in SuperCollider codeAPI.async("server.boot", ["default"], { // booted now API.async("group.new", [], { arg groupID; // use this group }) });

over OSC (simple call of functions)API("server").mountOSC; // send OSC message: // '/server/boot' "default"

via the duplex OSC interface (call and response)API.mountDuplexOSC; // send osc message: // '/API/call' "group.new" // reply will be sent back to the caller: // '/API/reply' 1001

Using a client library like supercollider.js// supercollider API.mountDuplexOSC; // start the web and websocket server node api_server.js // point browser at http://localhost:4040 // javascript in a browser or mobile device sc = new SCApi("localhost",4040); sc.call("server.boot", ["default"], function() { sc.call("group.new", [], function(groupID){ // spawn synths into this group }); });

supercollider.js provides a Node.js based api_server through which you can easily communicate with SuperCollider from javascript either on the server (running under Node) or in a browser (communicating back to Node with websockets).

It uses socket.io which is loads of fun and should prove quite useful for installations and pieces that allow many people to interact using mobile phones over normal webrowsers.

https://github.com/crucialfelix/supercolliderjs

Defining APIs

Each Quark can provide a folder called apis/ containing API handler dictionaries.

Post all currently implemented API paths:API.loadAll.allPaths.do(_.postln);

You can easily write APIs for your own application just by putting a file containing a dictionary of handlers in:// {yourquark}/apis/{apiname}.api.scd ( hello: { arg reply; reply.value("hello back") }, lookup: { arg reply, query; var result = (); { // let me think about it // search lots of files for something to do with "query" result['path'] = "some/path"; result['things'] = [1,2,3]; result['quantity'] = 4; result['random'] = 1024.rand; // the dictionary will be sent as JSON // and available in the browser as a JavaScript object reply.value( result ); }.fork } );

Your quark is now on the internets.// javascript sc.call("apiname.lookup",["a query string"], function(result) { console.log(result); console.log(result.random); result.things; // [1,2,3] });

Backwards incompatibility

I know, I hate these.

API 2 always passes in a { arg reply; } callback function while API 1 just used the return value as the result.

API 1 was a bit more confusing to use though for the call and response stuff.

Your old APIs, should you have any, would take just a few minutes to add in the callback, or you can continue to use the old methods:oldCall *oldCall oldAddAll

Class Methods

.new

Arguments:

name	apiname eg. "server" "synthdef" Convention is lowercase. It must match the case of the apis/{apiname}.api.scd file

Returns:

an API

Calling

.async

Call API method receiving the results with a callback.API.async("apiname.method", [arg1, arg2, ...], { arg result; // good news... }, { arg error; // bad news... });

Arguments:

path	"apiname.method"
args	array of arguments
callback	Callback that receives the result
onError	Optional onError handler. If not supplied than errors will be propagated.

Returns:

nothing, the result is returned to the callback

.sync

Call API method, waiting the current thread if needed till the result is returned. You should be inside a Routine, { }.defer {}.fork or similiarresult = API.sync("apiname.method", [arg1, arg2, ...]);

Arguments:

path	"apiname.method"
args	array of arguments
onError	Optional onError handler. If not supplied than errors will be propagated.

Returns:

the result

.call

Call API method, returning the result directly. The handler must not fork or defer. This is vaguely faster and can be used when you know there is no async.result = API.call("apiname.method"), [arg1,args2,...]);

Arguments:

path	"apiname.method"
... args	array of arguments

Returns:

return value

Querying

.allPaths

All available API paths in the form "apiname.method"

Returns:

array of strings

.apis

an array of the names of all available APIs from all /apis/ folders in all Quarks

Returns:

array of strings

.all

Array of all loaded APIs as API objects

Returns:

array of API objects

Loading

.loadAll

Load all APIs from apis/ folders in all quarks.

Arguments:

forceReload

Force reload/reparse

Returns:

this

.load

find and load an API from disk. throws an Error if not found or if failed to parse the file.

Arguments:

name

apiname

Returns:

the API

OSC

.mountDuplexOSC

Registers OSC responders. supercollider.js uses this to communicate.

There is an unfinished python implementation in the python folder of this Quark. Any language that can speak OSC and JSON can use these endpoints./API/call : client_id, request_id, fullpath ... args

client_id and request_id : are used to identify return messages and are up to the implementation of the api consumer

client_id would usually be a specific web browser, program or other independent entity. supercollider.js uses the socket.io socket id hash

request_id would be a unique id for each request from that client. supercollider.js increments a simple counter: 1,2,3 etc.

fullpath: apiname.methodKey dot separated to make it clear that its not an OSC path

Replies:/API/reply : client_id, request_id, result

result is sent as a JSON string: "{result:result}" so the api consumer needs to have a JSON library available. JSON does not distinguish between Symbol and String so all values are strings. Result may be string, int, float, list, dictionary. Date time not yet implemented. All other objects will be sent as their compile string representation.

Possibly .asJSON could allow objects to support their own JSON representations. Or the constructor arguments / storeArgs could be used to form a JSON response./API/not_found : client_id, request_id, fullpath /API/error : client_id, request_id, errorString

Arguments:

addr	An optional NetAddr (basically an IP address), limiting connections to that specific address.
recvPort	Optional port to listen on, otherwise uses the language's default port NetAddr.langPort [57120]

Returns:

this

.unmountDuplexOSC

Returns:

this

Instance Methods

Defining

.add

add a single handler

Arguments:

selector	handler name
func	handler function

Returns:

this

.addAll

Add a dictionary of handlers to this API.d = (key: { arg reply; }, another: { arg reply; }); api.addAll( d );

Arguments:

dict	The dictionary or dictionary subclass. The example above uses an Event because the notation ( ) is simple to type.

Returns:

this

.exposeMethods

Takes an object and turns it into an API by making each method on the object into a function of the same name.

Arguments:

obj	the object
selectors	methods to turn into handlers

Returns:

this

.exposeAllExcept

Takes an object and turns it into an API by making each method on the object into a function of the same name.

Arguments:

obj	the object
selectors	selectors to NOT add to the API.

Returns:

this

Calling

.async

see class method.

Arguments:

selector	(describe argument here)
args	(describe argument here)
callback	(describe argument here)
onError	(describe argument here)

Returns:

(describe returnvalue here)

.sync

see class method.

Arguments:

selector	(describe argument here)
args	(describe argument here)
onError	(describe argument here)

Returns:

(describe returnvalue here)

.call

see class method.

Arguments:

selector	(describe argument here)
... args	(describe argument here)

Returns:

(describe returnvalue here)

OSC

.mountOSC

Arguments:

baseCmdName	The OSC root where the responders are installed: /baseCmdName/method By default /apiname/method
addr	Optional limit to a certain NetAddr

Returns:

this

.unmountOSC

(describe method here)

Returns:

(describe returnvalue here)

Querying

.selectors

List of installed handler names.

Returns:

array of symbols

helpfile source: HelpSource/Classes/API.schelp
link::API/Classes/API::

APIExtension

.new

Arguments:

Returns:

.async

Arguments:

Returns:

.sync

Arguments:

Returns:

.call

Arguments:

Returns:

.allPaths

Returns:

.apis

Returns:

.all

Returns:

.loadAll

Arguments:

Returns:

.load

Arguments:

Returns:

.mountDuplexOSC

Arguments:

Returns:

.unmountDuplexOSC

Returns:

.add

Arguments:

Returns:

.addAll

Arguments:

Returns:

.exposeMethods

Arguments:

Returns:

.exposeAllExcept

Arguments:

Returns:

.async

Arguments:

Returns:

.sync

Arguments:

Returns:

.call

Arguments:

Returns:

.mountOSC

Arguments:

Returns:

.unmountOSC

Returns:

.selectors

Returns:

API
Extension