API

Application Programming Interfaces for sc applications: declaring them, calling them and mounting them on OSC. Interfaces with supercollider.js

API - SuperCollider API framework

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 code

API.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 to the language on port 57120
// and it will boot the server process
// '/API/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 returning the node ID
// '/API/reply' 1001

Using a client library like supercollider.js

// supercollider
API.mountDuplexOSC;

// start the webserver
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]
});

Included APIs

So far:

group.head
group.free
group.tail
group.new
instr.list
instr.play
instr.head
instr.detail
instr.listBySpec
instr.addSynthDesc
instr.after
instr.loadAll
instr.tail
instr.before
instr.replace
class.allClasses
class.subclasses
class.helpFile
class.helpFilePath
class.hasHelpFile
class.allSubclasses
API.apis
API.paths
interpreter.interpret
interpreter.play
interpreter.executeFile
server.freeAll
server.boot
server.sendMsg
server.quit
server.nextNodeID
server.isRunning
synth.head
synth.release
synth.grain
synth.free
synth.tail
synth.new
synth.get
synth.set
api.apis
api.paths
synthdef.remove
synthdef.add

supercollider.js includes a web app that browses the API and let's you experiment directly with it.

api browser

API
Project
Source file
Extension
Superclass:
ControlSpec
Project
Source file
Extension
Superclass:
JSON
Project
Source file
Extension
Superclass:
RPC
Project
Source file
Extension
Superclass:
Spec
Project
Source file
Extension
Superclass:
2.0.2
Date
2015-01-30
Git hash
50c02391fbfcf36c68e94a9d1e8a60c813957b66
2.0.1
Date
2012-11-11
Git hash
40218ed0a740c0c3d496ab02d1ad5593788f85bc
2.0.0
Date
2012-11-11
Git hash
303314c71ed1f0f9a5350a6d3e1cf7fd15723027

Installation

Repository

URL

https://github.com/crucialfelix/API

Since

2012-05-30

Last update

2015-01-30

Current version

2.0.2

Quark info

name

API

author

felix

summary

Application Programming Interfaces for sc applications: declaring them, calling them and mounting them on OSC. Interfaces with supercollider.js

version

2.0.2

Possible dependcies

Possible dependants