Supex (supex v0.1.0)

View Source

Supex = 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

add(ugen, add)

(since 0.1.0)
@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.

execute(sc_command)

(since 0.1.0)
@spec execute(binary()) :: :ok

Executes a raw SuperCollider's command on the sclang server.

Must be a string.

freq(ugen, freq)

(since 0.1.0)
@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.

lfo(ugen)

(since 0.1.0)
@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

mul(ugen, mul)

(since 0.1.0)
@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.

name(ugen, name)

(since 0.1.0)
@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.

osc(type \\ :sin)

(since 0.1.0)

Create a oscillator. type can be:

:sin (sinus wave) :saw (saw wave) :pulse (pulse wave, aka square wave)

Defaults to :sin.

phase(ugen, phase)

(since 0.1.0)
@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.

play(ugen)

(since 0.1.0)
@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

stop(ugen)

(since 0.1.0)
@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

stop_playing()

(since 0.1.0)
@spec stop_playing() :: :ok

Stops all sound playing.

synth(name)

(since 0.1.0)
@spec synth(binary()) :: binary()

A synth definition.

width(ugen, width)

(since 0.1.0)
@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.