Supex (supex v0.1.0)
View SourceSupex = SuperCollider + Elixir
An Elixir wrapper for the music live-coding language SuperCollider.
Supex communicates with SuperCollider’s sclang
tool, letting you generate and control sound directly from Elixir.
- 🎧 Play basic oscillators with a clean, pipeable syntax
- 🔤 Send raw SuperCollider code when needed
- ⛔ Stop sounds by name
Built for musicians, coders, and live performers who want to use Elixir for audio synthesis.
👉 Requires sclang
installed (sudo apt install sclang
on Linux)
Installation
The package can be installed by adding supex
to your list of dependencies in mix.exs
:
def deps do
[
{:supex, "~> 0.1.0"}
]
end
🔍 Learn SuperCollider basics
https://doc.sccode.org/Tutorials/Getting-Started/00-Getting-Started-With-SC.html
⚙️ Requirements:
SuperCollider's sclang
must be installed.
Example (Linux): sudo apt install sclang
🟢 Start the SuperCollider sclang server
iex> Supex.Sclang.start_link(:ok)
💡 Examples
️▶ Play a sine oscillator at 269 Hz and name it "y"; then stop it:
iex> import Supex
iex> osc |> freq(269) |> name("y") |> play
iex> osc |> name("y") |> stop
▶ Modulate volume of a sine wave using another sine as LFO:
iex> import Supex
iex> osc |> mul(osc |> freq(2) |> mul(0.4) |> add(0.5) |> lfo) |> play
iex> osc |> stop
▶ Modulate a pulse wave's frequency and width:
iex> import Supex
iex> osc(:pulse) |> freq("SinOsc.kr(0.4).range(169, 269)") |> width("SinOsc.kr(6.9).range(0.01, 0.8)")|> mul(0.3) |> name("x") |> play
iex> osc |> name("x") |> stop
🔤 Send a raw SuperCollider expression:
iex> import Supex
iex> "RLPF.ar(Pulse.ar([100, 250], 0.5, 0.1), XLine.kr(8000, 400, 5), 0.05)" |> play
iex> osc |> name("z") |> stop
⚠️ Disclaimer
SuperCollider and Supex can produce loud, sudden sounds. Use volume control and a limiter to protect your ears. Avoid hearing damage.
Summary
Functions
Add the value to the signal.
Values can be 0.1
or 1
for example.
Executes a raw SuperCollider's command on the sclang
server.
Tune the frequency of an oscillator.
freq
can be an integer or float.
Transforms a "normal" oscillator to a LFO to use it as a modulator.
Multiplication of the signal.
Chose values between 0.1
and 1
for not hurting your ears.
Adds a name for referencing. e.g. with a name the singnal can be stopped on the SuperCollider server.
Create a oscillator.
type
can be
The phase of a sinus wave.
Play the composed oscillator, or a raw SuperCollider's command (as a string).
Stop playing a oscillator with a name.
Stops all sound playing.
A synth definition.
The pulse width of an pulse wave oscillator.
width
should be a value between 0.01
and 0.99
.
Functions
@spec add( %Supex.Ugen{ add: term(), freq: term(), lfo: term(), mul: term(), osc: term(), phase: term(), sc_command: term(), sc_name: term(), width: term() }, integer() | float() ) :: struct()
Add the value to the signal.
Values can be 0.1
or 1
for example.
@spec execute(binary()) :: :ok
Executes a raw SuperCollider's command on the sclang
server.
Must be a string.
@spec freq( %Supex.Ugen{ add: term(), freq: term(), lfo: term(), mul: term(), osc: term(), phase: term(), sc_command: term(), sc_name: term(), width: term() }, integer() | float() ) :: struct()
Tune the frequency of an oscillator.
freq
can be an integer or float.
@spec lfo(%Supex.Ugen{ add: term(), freq: term(), lfo: term(), mul: term(), osc: term(), phase: term(), sc_command: term(), sc_name: term(), width: term() }) :: binary()
Transforms a "normal" oscillator to a LFO to use it as a modulator.
It uses kr
(control rate) instead of ar
(audio rate),
cf. https://doc.sccode.org/Tutorials/Getting-Started/05-Functions-and-Sound.html
example
Modulate the volume of a sine wave with another sine wave as an LFO:
iex> import SC iex> osc |> mul(osc |> freq(3) |> mul(0.5) |> add(0.5) |> lfo) |> play iex> osc |> stop
or
iex> osc(:pulse) |> mul(osc|>freq(2)|>mul(0.4)|>add(0.5)|>lfo) |> freq(osc(:saw)|>freq(0.2)|>mul(100)|>add(100)|>lfo) |> play
@spec mul( %Supex.Ugen{ add: term(), freq: term(), lfo: term(), mul: term(), osc: term(), phase: term(), sc_command: term(), sc_name: term(), width: term() }, integer() | float() ) :: struct()
Multiplication of the signal.
Chose values between 0.1
and 1
for not hurting your ears.
@spec name( %Supex.Ugen{ add: term(), freq: term(), lfo: term(), mul: term(), osc: term(), phase: term(), sc_command: term(), sc_name: term(), width: term() }, binary() ) :: struct()
Adds a name for referencing. e.g. with a name the singnal can be stopped on the SuperCollider server.
Create a oscillator.
type
can be:
:sin
(sinus wave)
:saw
(saw wave)
:pulse
(pulse wave, aka square wave)
Defaults to :sin
.
@spec phase( %Supex.Ugen{ add: term(), freq: term(), lfo: term(), mul: term(), osc: term(), phase: term(), sc_command: term(), sc_name: term(), width: term() }, integer() | float() ) :: struct()
The phase of a sinus wave.
@spec play( %Supex.Ugen{ add: term(), freq: term(), lfo: term(), mul: term(), osc: term(), phase: term(), sc_command: binary(), sc_name: binary(), width: term() } | binary() ) :: :ok
Play the composed oscillator, or a raw SuperCollider's command (as a string).
example
iex> import SC iex> osc |> freq(269) |> name("y") |> play
@spec stop(%Supex.Ugen{ add: term(), freq: term(), lfo: term(), mul: term(), osc: term(), phase: term(), sc_command: term(), sc_name: binary(), width: term() }) :: :ok
Stop playing a oscillator with a name.
example
iex> import SC iex> osc |> name("y") |> stop
@spec stop_playing() :: :ok
Stops all sound playing.
A synth definition.
@spec width( %Supex.Ugen{ add: term(), freq: term(), lfo: term(), mul: term(), osc: term(), phase: term(), sc_command: term(), sc_name: term(), width: term() }, integer() | float() ) :: struct()
The pulse width of an pulse wave oscillator.
width
should be a value between 0.01
and 0.99
.