View Source README
overview
Overview
This is an Elixir library for interacting with SuperCollider, an audio synthesis and composition platform.
SuperCollider as a platform covers both client (sclang programming language and scide editing environment) and server (scynth or supernova).
This Elixir library deals exclusively with the latter, that is, interacting with either:
- scsynth: a real-time audio server with hundreds of unit generators (UGens) for audio analysis, synthesis, and processing
- supernova: an alternative server to scsynth with support for parallel DSP on multi-core processors.
why-elixir
Why Elixir?
Elixir is dynamic, functional, expressive and fun!
Running on top of the Erlang virtual machine, you’ll find Elixir on embedded systems (see the Nerves project) to large multi-node distributed systems and everything in between. Maybe you’ll use this for your next hardware synth project!
Elixir also offers Livebook, which can be used as a flexible creative coding environment.
If Elixir isn’t your thing, there are other libraries in other programming languages for interacting with SuperCollider, such as Overtone (Clojure), Tidal (Haskell), Sonic Pi (built with Ruby, Erlang and Elixir), Sorceress (Rust) and a number in Python.
status
Status
This library is currently under active development and it’s API is likely to change.
architecture
Architecture
This library consists of a number of modules, the main ones being:
-
SuperCollider
which allows you to quickly get going without needing to understand too much of this library’s architecture. -
SuperCollider.SynthDef
which is an Elixir struct representation of SuperCollider’s synth definitions, built from networks of UGens (unit generators) which generate or process both audio and control signals. -
SuperCollider.SoundServer
a GenServer which is used to create the main process for sending and listening to scsynth or supernova messages. Messages are sent using Open Sound Control (OSC) protocol via UDP.
example
Example
Below shows some basic examples of:
- starting SuperCollider
- sending commands
- loading and decoding .scsyndef files
- encoding a SynthDef struct to binary format
- sending the encoded SynthDef to scsynth or supernova.
alias SuperCollider
alias SuperCollider.SynthDef
# Start the SoundServer. If scynth or supernova isn’t loaded, it will attempt to boot it.
SuperCollider.start()
# Get the status from scynth or supernova
SuperCollider.command(:status)
# The response to some commands, such as :status, is stored in the SuperCollider's GenServer state. You can access that response anytime as below:
SuperCollider.response[:status]
# This reurns the status in a list of Tuples like this:
# [
# {"unused", 1},
# {"number of unit generators", 0},
# {"number of synths", 0},
# {"number of groups", 2},
# {"number of loaded synth definitions", 109},
# {"average percent CPU usage for signal processing", 0.022731395438313484},
# {"peak percent CPU usage for signal processing", 0.09797607362270355},
# {"nominal sample rate", 44100.0},
# {"actual sample rate", 44099.97439210702}
# ]
# Send a command to play a basic 300Hz sinusoidal sound on node 100
# This assumes the sine SynthGen is installed on the server
SuperCollider.command(:s_new, ["sine", 100, 1, 0, ["freq", 300]])
# Stop the sound by freeing node 100
SuperCollider.command(:n_free, 100)
# Decode a .scsyndef file into an %SynthDef{} struct
closed_hat = SynthDef.from_file("closed_hat.scsyndef")
# Encode a SynthDef to binary format, which is used by scsynth or supernova
encoded_data = SynthDef.to_binary(closed_hat)
# Send the encoded SynthDef to scynth or supernova
SuperCollider.command(:d_recv, encoded_data)
getting-started
Getting started
installation-of-supercollider
Installation of SuperCollider
You’ll need to have SuperCollider installed. See SuperCollider’s downloads page for supported platforms. Currently there are Mac, Linux, Windows builds. It can be built on embedded platforms, including Raspberry Pi, Beagle Bone Black and Bela.
adding-it-to-your-elixir-project
Adding it to your Elixir project
The package can be installed by adding supercollider
to your list of dependencies in mix.exs
:
def deps do
[
{:supercollider, "~> 0.1.5"}
]
end
using-within-livebook-and-iex
Using within LiveBook and IEx
Mix.install([{:supercollider, "~> 0.1.5"}])
LiveBook tour
Also see the introductory tour in LiveBook at /livebook/supercollider_tour.livemd.
documentation
Documentation
The docs can be found at https://hexdocs.pm/supercollider.