Mx.Engine behaviour (mx v0.1.0)

Copy Markdown View Source

The boundary between mx and the engine that makes its sound.

mx works out every note's time and options on its side, and hands the engine events stamped with the Unix time in microseconds they play at, with their times already in seconds. An event is one of:

  • {:note, id, synth, note, params, chain}, a note of a synth, with its pitch as note, or nil for a drum's own pitch.
  • {:sample, id, sample, params, chain}, a sample as prepare or load_sample handed it back.
  • {:set, target, params}, a change to sounds already playing: {:sounds, ids}, {:part, chain} for every note playing in a chain, or {:effect, chain, index} for one of its effects.

It also renders notes offline, for measuring and fitting synths. id is nil for a sound nothing changes later, and otherwise one new_id/0 gave; chain is nil, or an effect chain as start_fx handed it back, which the note plays into.

Summary

Types

chain()
event()
id()
params()
target()

Callbacks

load_sample(path, loop)

Loads a sample a loop named while playing, and sends the loop {:sample_loaded, path, sample}.

new_id()

An id for a sound that a later event changes.

play(at_us, events)

Plays events at the Unix time in microseconds given.

prepare(song)

Loads the samples a song names, and returns the song with each loop's samples.

record_input(path, source, at_us)

Records {:input, number} of the sound card, or {:sample, path} played in its place, apart from the main output, to a WAV file from the Unix time in microseconds given.

render_note(atom, params, seconds, dir, changes)

Renders one note of a synth offline for some seconds, into a folder, with changes to it as {seconds, params}, and returns its left channel.

render_rate()

The sample rate notes render offline at.

render_through(atom, params, seconds, dir, effects)

Renders one note of a synth offline through effects, each {effect, params}, and returns {left, right}.

set_live(lives, tempo)

Starts, changes and stops the live audio inputs to match a version of the song.

start_fx(effects)

Starts an effect chain from a part's effects, and returns the chain its notes play into.

start_link(opts)

Starts the engine, with options of its own.

stop_fx(chain, at_us)

Removes an effect chain after the Unix time in microseconds given, once its notes and tail have ended.

stop_input()

Stops recording the input and closes its file.

Types

chain()

@type chain() :: term()

event()

@type event() ::
  {:note, id() | nil, atom(), number() | [number()] | nil, params(),
   chain() | nil}
  | {:sample, id() | nil, term(), params(), chain() | nil}
  | {:set, target(), params()}

id()

@type id() :: term()

params()

@type params() :: keyword(number())

target()

@type target() ::
  {:sounds, [id()]} | {:part, chain()} | {:effect, chain(), non_neg_integer()}

Callbacks

load_sample(path, loop)

@callback load_sample(path :: String.t(), loop :: pid()) :: :ok

Loads a sample a loop named while playing, and sends the loop {:sample_loaded, path, sample}.

new_id()

@callback new_id() :: id()

An id for a sound that a later event changes.

play(at_us, events)

@callback play(at_us :: integer(), events :: [event()]) :: :ok

Plays events at the Unix time in microseconds given.

prepare(song)

@callback prepare(
  song :: %Mx.Song{
    live: term(),
    loops: term(),
    osc_from: term(),
    osc_to: term(),
    played: term(),
    tempo: term(),
    tempos: term()
  }
) :: %Mx.Song{
  live: term(),
  loops: term(),
  osc_from: term(),
  osc_to: term(),
  played: term(),
  tempo: term(),
  tempos: term()
}

Loads the samples a song names, and returns the song with each loop's samples.

record_input(path, source, at_us)

@callback record_input(
  path :: String.t(),
  source :: {:input, pos_integer()} | {:sample, String.t()},
  at_us :: integer()
) :: :ok | {:error, String.t()}

Records {:input, number} of the sound card, or {:sample, path} played in its place, apart from the main output, to a WAV file from the Unix time in microseconds given.

render_note(atom, params, seconds, dir, changes)

@callback render_note(
  atom(),
  params(),
  seconds :: number(),
  dir :: String.t(),
  changes :: [{number(), params()}]
) :: [float()]

Renders one note of a synth offline for some seconds, into a folder, with changes to it as {seconds, params}, and returns its left channel.

render_rate()

@callback render_rate() :: pos_integer()

The sample rate notes render offline at.

render_through(atom, params, seconds, dir, effects)

@callback render_through(
  atom(),
  params(),
  seconds :: number(),
  dir :: String.t(),
  effects :: list()
) ::
  {[float()], [float()]}

Renders one note of a synth offline through effects, each {effect, params}, and returns {left, right}.

set_live(lives, tempo)

@callback set_live(lives :: list(), tempo :: number()) :: :ok

Starts, changes and stops the live audio inputs to match a version of the song.

start_fx(effects)

@callback start_fx(effects :: list()) :: chain()

Starts an effect chain from a part's effects, and returns the chain its notes play into.

start_link(opts)

@callback start_link(opts :: Keyword.t()) :: GenServer.on_start()

Starts the engine, with options of its own.

stop_fx(chain, at_us)

@callback stop_fx(chain(), at_us :: integer()) :: :ok

Removes an effect chain after the Unix time in microseconds given, once its notes and tail have ended.

stop_input()

@callback stop_input() :: :ok | {:error, String.t()}

Stops recording the input and closes its file.