SuperCollider
SuperCollider
v0.1.5

View Source SuperCollider (SuperCollider v0.1.5)

This is the main SuperCollider module.

With this module, you can:

  • start a SuperCollider.SoundServer, which is a GenServer used to communicate with scynth and recieve messages from it.
  • issue commands
  • access SuperColliders state.

This module aims to minimise the need to pass a pid around representing the active SoundServer by storing it's PID as a persisitient term under :supercollider_soundserver. Calling SuperCollider.start() will automatically store the pid of the SoundServer as a persistient term.

example

 Example 

alias SuperCollider, as :SC

# Start the `SuperCollider.SoundServer` GenServer
SC.start() # this will return the PID of the SoundServer, however, you don't have to assign this to a variable as its stored as a persistient term used by the other functions in this module.

# Issue the verion command and get the response from SoundServer's state
SC.command(:version) # send the version commant to SuperCollider
SC.response(:version) # retrieves the version response from the SoundServer's state

# Play a sine wave UGen on node 600, with a frequency of 300
SC.command(:s_new, ["sine", 600, 1, 0, ["freq", 300]])

# Stop the sine wave by freeing node 600
SC.command(:n_free, 600)

livebook-tour

 LiveBook tour

You can explore this library further in the LiveBook demo. Run in Livebook

Link to this section Summary

Functions

command(command_name)

Send a command to the default SoundServer.

command(command_name, args)

Send a command to the default SoundServer with arguments.

pid()

Returns the PID of the SoundServer stored as a persistent_term as :supercollider_soundserver.

response()

Get's any OSC responses stored in the state of the SoundServer.

response(key)

Get's a specific OSC response stored in the state of the server, by it's key. If no response is available for the specific key, nil is returned.

start(opts \\ [])

Starts the SuperCollider.SoundServer GenServer and returns it's pid.

state()

Get's the state of the global SoundServer (whos PID is stored as a persisitient term under :supercollider_soundserver).

Link to this section Functions

Link to this function

command(command_name)

View Source

Send a command to the default SoundServer.

This function accepts the following parameters:

examples

 Examples 

# Get the server's status
SuperCollider.command(:status) # Make the call
SuperCollider.response(:status) # Get the status response data
Link to this function

command(command_name, args)

View Source

Send a command to the default SoundServer with arguments.

This function accepts the following parameters:

  • command, in a form of an atom representing SuperCollider commands (See: SuperCollider.SoundServer.Command for details)
  • args, commands which take them. Multiple options can be provided as a list.

examples

 Examples 

# Send a command to play a basic 300Hz sinusoidal sound on node 100
SuperCollider.command(:s_new, ["sine", 100, 1, 0, ["freq", 300]])

# Stop the sound by freeing node 100
SuperCollider.command(:n_free, 100)
Link to this function

pid()

View Source

Returns the PID of the SoundServer stored as a persistent_term as :supercollider_soundserver.

Link to this function

response()

View Source

Get's any OSC responses stored in the state of the SoundServer.

Responses are stored in a Map. If there are no responses stored, an empty map is returned, e.g. %{}.

Link to this function

response(key)

View Source

Get's a specific OSC response stored in the state of the server, by it's key. If no response is available for the specific key, nil is returned.

The following are currently stored responses:

  • :version - the version information from a SuperCollider.command(:version) call
  • :status - the last status message stored from a SuperCollider.command(:status) call
  • :fail - the last fail message from a SuperCollider.command(...) call

example

 Example

For example, if a version request was made:

SuperCollider.command(:version)

To get the response held by the SuperCollider.SoundServer you'd call:

SuperCollider.response(:version)

This would return the version response in the following format:

[
  {"Program name. May be "scsynth" or "supernova".", "scsynth"},
  {"Major version number. Equivalent to sclang's Main.scVersionMajor.", 3},
  {"Minor version number. Equivalent to sclang's Main.scVersionMinor.", 13},
  {"Patch version name. Equivalent to the sclang code "." ++ Main.scVersionPatch ++ Main.scVersionTweak.",
   ".0"},
  {"Git branch name.", "Version-3.13.0"},
  {"First seven hex digits of the commit hash.", "3188503"}
]
Link to this function

start(opts \\ [])

View Source

Starts the SuperCollider.SoundServer GenServer and returns it's pid.

The pid for the SuperCollider.SoundServer is also stored as a persisitient term under :supercollider_soundserver. This is used by the SuperCollider.state/0, SuperCollider.response/0, SuperCollider.response/1, SuperCollider.command/1 and SuperCollider.command/2 functions so that they're passed the global SoundServer pid without having to specify it.

If you want to directly interact with a SoundServer through it's pid, see the equivalent functions under SuperCollider.SoundServer, such as {:ok, pid} = SuperCollider.SoundServer.start_link() or through {:ok, pid} = GenServer.start_link(SoundServer, SoundServer.new()).

options

 Options

Additionally, this function can take options:

  • ip: the IP address of scserver. This defaults to '127.0.0.1'
  • hostname: the hostname of the server. This defaults to 'localhost'.
  • port: the port used to communicate with scserver. This defaults to 57110.
  • socket: the UDP socket used to communicate with scserver, once the connection is open.
  • type: the server type being used, accepts :scsynth (default) or :supernova (multicore)

Note if the hostname is set to nil it will try the IP address at ip.

examples

 Examples

Start SuperCollider with defaults

SuperCollider.start()

Start SuperCollider with a supernova server

SuperCollider.start(type: :supernova)

This function starts the SuperCollider.SoundServer GenServer which will check if SuperCollider has booted on your system. If not, it will currently attempt to start scynth or supernova at the following locations:

  • Mac: /Applications/SuperCollider.app/Contents/Resources/
  • Linux: /usr/local/
  • Windows: \Program Files\SuperCollider\
Link to this function

state()

View Source

Get's the state of the global SoundServer (whos PID is stored as a persisitient term under :supercollider_soundserver).

example

 Example 

SuperCollider.state()

## Returns the populated SoundServer struct
# %SuperCollider.SoundServer{
#   ip: '127.0.0.1',
#   hostname: 'localhost',
#   port: 57110,
#   socket: #Port<0.12>,
#   type: :supernova,
#   responses: %{}
# }