This page was generated from examples/sc3nb-examples.ipynb.

Getting Started

Starting sc3nb

[1]:

import sc3nb as scn

To startup sc3nb (sclang, scsynth, and a python OSC server) use startup which will return a SC instance which is the central SuperCollider Interface

[2]:

sc = scn.startup()  # see Configuration of sc3nb startup below for more details

Starting sclang process... Done.
Registering OSC /return callback in sclang... Done.
Loading default sc3nb SynthDefs... Done.
Booting SuperCollider Server... Done.

You can produce a test sound with blip, which should relax any tensions whether the server is up and running. This sound should be played by the default server start.

[3]:

sc.server.blip()

sc provides you the interfaces for

  • scsynth via sc.server

  • sclang via sc.lang

Configuration of sc3nb startup:

  • Specifying the excutable location

    • We try to find the sclang and scsynth executables in the $PATH environment variable and also in the default installation directories

      • On macOS they reside in /Applications/SuperCollider.app/Contents in the folders MacOS and Resources. To add these paths to your $PATH, simply add to your ~/.profile, e.g. (please adapt to your installation): PATH=$PATH:/Applications/SuperCollider.app/Contents/MacOS:/Applications/SuperCollider.app/Contents/Resources

      • On Windows they reside in your Installation folder f.e C:\Program Files\SuperCollider-3.x.x

    • If the executables are not found, you can specify them with sclang_path / scsynth_path e.g. sclang_path="/path/to/sclang-containing-dir/sclang"

  • You could also only use scsynth only and don’t start sclang with start_sclang=False

  • See help(scn.startup) for all options

[4]:

# help(scn.startup)

Basic examples

Use Python implementations to control the SuperCollider audio server

Create and control SuperCollider Synths

[5]:

syn = scn.Synth("s2")
syn

[5]:

<Synth(20001) 's2' s {}>

[6]:

syn.freq = 800
syn

[6]:

<Synth(20001) 's2' ~ {'freq': 800}>

[7]:

syn.free()  # or use the ctrl-. (cmd-.) shortcut in Jupyter notebooks
syn

[7]:

<Synth(20001) 's2' f {'freq': 800}>

Send SynthDefs with python code injection

[8]:

synth_dur = 0.5  # you can use python variables in SynthDefs by prepending ^
synth_def = scn.SynthDef('random', """{ |out|
    var line;
    line = Line.kr(1, 0, ^synth_dur, doneAction: Done.freeSelf);
    Out.ar(out, SinOsc.ar(Rand(400, 800), 0, 0.2) * line);
}""")
synth_def.add()
synth_def  # Note that the representation has synth_dur already injected

[8]:

SynthDef('random', { |out|
    var line;
    line = Line.kr(1, 0, 0.5, doneAction: Done.freeSelf);
    Out.ar(out, SinOsc.ar(Rand(400, 800), 0, 0.2) * line);
})

[9]:

scn.Synth("random")

[9]:

<Synth(20002) 'random' s {}>

Load a file as Buffer and play it

[10]:

buf = scn.Buffer().read("./media/blip.wav")
buf

[10]:

<Buffer(128) on ('127.0.0.1', 57110): 2 x 43008 @ 44100 Hz = 0.975s allocated using mode 'file'>

[11]:

buf.play()

[11]:

<Synth(20003) 'sc3nb_playbuf_128' s {}>

[12]:

buffer_data = buf.to_array()
print(buffer_data.shape)
buffer_data

(43008, 2)

[12]:

array([[-0.00189209, -0.00189209],
       [-0.00430298, -0.00430298],
       [-0.00708008, -0.00708008],
       ...,
       [ 0.19314575,  0.19314575],
       [ 0.18963623,  0.18963623],
       [ 0.18585205,  0.18585205]])

More examples about the above used SuperCollider objects can be found in the respective User Guide sections * Nodes (Synths and Groups) * SynthDef * Buffer

Use OSC to control the SuperCollider audio server

Send OSC Messages with SuperCollider Commands and receive replies

[13]:

sc.server.msg("/status")  # waits for reply message and returns it

[13]:

(1,
 9,
 1,
 9,
 117,
 0.22436478734016418,
 0.35780069231987,
 44100.0,
 43563.0405712431)

We offer also high level versions for the commands.

[14]:

sc.server.status()

[14]:

ServerStatus(num_ugens=9, num_synths=1, num_groups=9, num_synthdefs=117, avg_cpu=0.22219102084636688, peak_cpu=0.35780069231987, nominal_sr=44100.0, actual_sr=43548.905905256324)

Create OSC Bundles using SuperCollider Commands directly

[15]:

with sc.server.bundler() as bundler:
    bundler.add(0.2, "/s_new", ["s1", -1, 0, 0])
    bundler.add(0.5, "/s_new", ["s1", -1, 0, 0, "freq", 800, "dur", 0.1])
bundler.messages()

[15]:

{0.2: [<OSCMessage("/s_new", ['s1', -1, 0, 0])>],
 0.5: [<OSCMessage("/s_new", ['s1', -1, 0, 0, 'freq', 800, 'dur', 0.10000000149011612])>]}

or create OSC Bundles with the high level Python implementations

[16]:

with sc.server.bundler() as bundler:
    bundler.wait(0.2)
    scn.Synth("s1")
    bundler.wait(0.3)
    scn.Synth("s1", {"freq": 800, "dur": 0.1})
bundler.messages()

[16]:

{0.2: [<OSCMessage("/s_new", ['s1', 20004, 0, 67108865])>],
 0.5: [<OSCMessage("/s_new", ['s1', 20005, 0, 67108865, 'freq', 800, 'dur', 0.10000000149011612])>]}

More OSC communication examples

Use the SuperCollider Language from Python

Execute SuperCollider Language Code

[17]:

breakfast = "eggs"
sc.lang.cmd('^breakfast.scramble;')

-> gges

or via the %sc IPython magic

[18]:

%sc ^breakfast.scramble

-> gges

Get results from SuperCollider Language in python with cmdg or %scg

[19]:

x = 5
value = %scg (1..^x)
print(f"received {value} with type {type(value)}")

-> [ 1, 2, 3, 4, 5 ]
received [1, 2, 3, 4, 5] with type <class 'list'>

More sclang in sc3nb examples

Stoping the synthesis

There are multiple options to stop the playing audio synthesis

[20]:

%sc x = Synth.new("default")  // starting a Synth with sclang

-> Synth('default' : 1000)

  • to stop all playing synths either use CMD-. (in Jupyter Command mode).

  • It is a shortcut for the ´free_all´ method of the default server

[21]:

sc.server.free_all()

  • or you could also use sclang

[22]:

%sc s.freeAll

-> sc3nb_remote

Combined usage

It is also possible to mix the different interaction styles.

  • create a Synth with sclang and get the nodeid of the Synth via the %scg IPython magic

[23]:

nodeid = %scg x = Synth("default"); x.nodeID;

-> 1001

  • create the corresponding Python Synth instance

[24]:

synth = scn.Synth("default", nodeid=nodeid, new=False)
synth

[24]:

<Synth(1001) 'default' ~ {}>

  • Inspect and control the Synth from Python

[25]:

synth.synth_desc

[25]:

{'out': SynthArgument(name='out', rate='scalar', default=0.0),
 'freq': SynthArgument(name='freq', rate='control', default=440.0),
 'amp': SynthArgument(name='amp', rate='control', default=0.10000000149011612),
 'pan': SynthArgument(name='pan', rate='control', default=0.0),
 'gate': SynthArgument(name='gate', rate='control', default=1.0)}

[26]:

synth.freq

[26]:

440.0

[27]:

synth.freq *= 2
synth.freq

[27]:

880.0

[28]:

synth

[28]:

<Synth(1001) 'default' ~ {'freq': 880.0}>

  • send a OSC Message to free the Synth

[29]:

sc.server.msg("/n_free", nodeid)

[30]:

synth

[30]:

<Synth(1001) 'default' ~ {'freq': 880.0}>

Exiting sc3nb

To shut down the server and sclang subprocesses

[31]:

sc.exit()

Quitting SCServer... Done.
Exiting sclang... Done.

Further information and advanced examples

For more details on the specific parts please refer to the corresponding sections of the User Guide.

[ ]: