dymokomi/luce-audio
Source of release 0.4.2
## The engine a song plays through: a program of tracks, units and lanes
## (`program`), run on the output device's realtime thread or offline, with
## a transport and a sequencer that start and end notes on the sample.
##
## Threads. The main thread builds (`begin` ... `commit`), sends commands
## (parameters, transport, played notes) through a lock-free ring, and
## frees programs the audio thread has retired. The audio thread owns the
## running program and the transport; it publishes position, load and
## meters through atomics. Nothing the audio thread does allocates, locks,
## fails or calls into Luce.
##
## A new program takes over at the start of a buffer, its running state
## (voices, phases, filters, envelopes, lines, sounding notes) carried over
## by id from the one before, so an edit while playing neither clicks nor
## drops notes.
import memory
import atomic
import strings
import c
from luce_std import files
import time
import interop
import result
import program
import dsp
import kinds
import scale
from luce_midi import midi
from scale import Scale, Key
from luce_midi.midi import Ring as MidiRing, Event as MidiEvent, Input as MidiInput
from luce_std import wake
from program import Program, Builder, KeyDraft, ListenDraft, TrackDraft, UnitDraft, NodeDraft, WireDraft, FeedDraft, LaneDraft, NoteDraft, PointDraft, TargetDraft, Note, Point, Lane, Unit, Track
from device import Device, Block
from dsp import chunk
pub let most_tracks: usize = 128
let command_param: u32 = 1
let command_play: u32 = 2
let command_stop: u32 = 3
let command_seek: u32 = 4
let command_tempo: u32 = 5
let command_loop: u32 = 6
let command_note_on: u32 = 7
let command_note_off: u32 = 8
let command_track: u32 = 9
let command_master: u32 = 10
let command_panic: u32 = 11
let command_metronome: u32 = 12
struct Command:
var kind: u32
var a: i64
var b: i64
var c: i64
var value: f64
var other: f64
let ring_size: u64 = 4096
## What the main and audio threads share. Fields without `@` belong to
## the audio thread while the device runs, and to the main thread while
## it does not.
struct Shared:
var pending: @Program*?
var retired: @Program*?
var current: Program*?
var commands: Command[4096]
var written: @u64
var taken: @u64
var rate: f64
var playing: bool
var beat: f64
var tempo: f64
var looping: bool
var loop_start: f64
var loop_end: f64
var master: f32
var reposition: bool
var shown_beat: @u64
var shown_playing: @bool
var load: @u64
var peak_load: @u64
var voices: @u32
var peaks: (@u32)[128]
## Where tempo-synced kinds are while the transport is stopped.
var idle_beat: f64
## The audio thread's side of the MIDI input, while one is open.
var midi: @MidiRing*?
## The clock a recording reads (`beat_at`): the beat the block's first
## frame is heard at, that moment in host nanoseconds, and the beats a
## nanosecond; `clock_seq` is odd while the audio thread writes them.
var clock_seq: @u64
var clock_beat: @u64
var clock_nanos: @u64
var clock_rate: @u64
## How long after its callback a block is heard, in nanoseconds.
var heard_after: u64
## The metronome: on, the beats a bar, and the click sounding.
var metronome: bool
var click_bar: i64
var click_left: f32
var click_phase: f32
var click_step: f32
# ---------------------------------------------------------------- audio thread
## The device's callback: one hardware buffer.
func device_render(context: void*?, block: Block*):
let raw = context else return
let shared = (Shared*)raw
let left = block.output(0)
let right = block.output(1) if block.channels > 1 else left
process(shared, left, right, block.frames, block.host_nanos)
for channel in 2..<block.channels:
let rest = block.output(channel)
for i in 0..<rest.length: rest[i] = 0.0
## Fill `left` and `right` with the next `frames` samples.
func process(shared: Shared*, left: f32[], right: f32[], frames: usize, host: u64 = 0):
let started = time.now()
take_program(shared)
drain(shared)
publish_clock(shared, host)
if let running = shared.current:
take_midi(shared, running)
if shared.current == none:
for i in 0..<frames:
left[i] = 0.0
right[i] = 0.0
return
let running = shared.current else return
var done: usize = 0
var sounding: u32 = 0
while done < frames:
var n = frames - done
if n > chunk: n = chunk
let per_sample = shared.tempo / 60.0 / shared.rate
if shared.playing:
if shared.reposition:
reposition(running, shared.beat, per_sample)
shared.reposition = false
fire(running, shared.beat, per_sample)
let next = next_event(running, shared, per_sample)
if next < 1.0e300:
let until = (next - shared.beat) / per_sample
if until < (f64)n:
var whole = (usize)until
if (f64)whole < until: whole += 1
if whole < 1: whole = 1
if whole < n: n = whole
let span = per_sample * (f64)n if shared.playing else 0.0
curves(running, shared.beat, shared.beat + span, n)
running.beat = shared.beat if shared.playing else shared.idle_beat
running.beats_per_sample = per_sample
shared.idle_beat = shared.beat + span if shared.playing else shared.idle_beat + per_sample * (f64)n
var l = left[done..<done + n]
var r = right[done..<done + n]
for i in 0..<n:
l[i] = 0.0
r[i] = 0.0
for t in 0..<running.tracks.length:
var track = &running.tracks[t]
if track.master: continue
program.run_track(running, track, n)
mix_track(shared, running, track, t, l, r, n)
if running.master >= 0:
# The mix through the master's chain becomes the output.
for i in 0..<n:
running.mix_left[i] = l[i]
running.mix_right[i] = r[i]
l[i] = 0.0
r[i] = 0.0
let m = (usize)running.master
var bus = &running.tracks[m]
program.run_track(running, bus, n)
mix_track(shared, running, bus, m, l, r, n)
let master = shared.master
for i in 0..<n:
l[i] = l[i] * master
r[i] = r[i] * master
if shared.metronome and shared.playing:
click(shared, l, r, n, per_sample)
for i in 0..<n:
l[i] = safety(l[i])
r[i] = safety(r[i])
if shared.playing:
shared.beat += span
if shared.looping and shared.loop_end > shared.loop_start and shared.beat >= shared.loop_end - per_sample * 0.5:
end_all(running)
shared.beat = shared.loop_start + (shared.beat - shared.loop_end)
if shared.beat < shared.loop_start: shared.beat = shared.loop_start
reposition(running, shared.beat, per_sample)
done += n
for instrument in running.units:
for voice in instrument.voices:
if voice.active and instrument.played: sounding += 1
shared.voices.store(sounding, .relaxed)
shared.shown_beat.store(shared.beat.bits(), .relaxed)
shared.shown_playing.store(shared.playing, .relaxed)
let budget = (f64)frames / shared.rate * 1000000000.0
let busy = (f64)time.since(started) / budget
shared.load.store(busy.bits(), .relaxed)
if busy > f64.bits(shared.peak_load.load(.relaxed)):
shared.peak_load.store(busy.bits(), .relaxed)
## Say where the transport is for `beat_at`: the block about to play is
## heard `heard_after` its callback's host time.
func publish_clock(shared: Shared*, host: u64):
if host == 0: return
let seq = shared.clock_seq.load(.relaxed)
shared.clock_seq.store(seq +% 1, .release)
let beat = shared.beat if shared.playing else shared.idle_beat
let rate = shared.tempo / 60.0 / 1000000000.0 if shared.playing else 0.0
shared.clock_beat.store(beat.bits(), .relaxed)
shared.clock_nanos.store(host + shared.heard_after, .relaxed)
shared.clock_rate.store(rate.bits(), .relaxed)
shared.clock_seq.store(seq +% 2, .release)
## Play the MIDI that came in since the last block on the tracks hearing it.
func take_midi(shared: Shared*, running: Program*):
let ring = shared.midi.load(.acquire) else return
var event: MidiEvent
while ring.next(&event):
route_midi(shared, running, event)
## One MIDI message to every track listening for its source and channel:
## notes through the track's scale, all-notes-off releasing them.
func route_midi(shared: Shared*, running: Program*, event: MidiEvent):
let kind = event.status & 0xF0
if kind != 0x80 and kind != 0x90 and kind != 0xB0: return
let channel = (i32)(event.status & 0x0F) + 1
let beat = shared.beat if shared.playing else 0.0
for t in 0..<running.tracks.length:
let track = &running.tracks[t]
if track.listens.length == 0 or track.midi_source < 0: continue
if track.midi_source != 0 and track.midi_source != (i64)event.source: continue
if track.midi_channel != 0 and track.midi_channel != channel: continue
let written = (i32)event.data1
if kind == 0x90 and event.data2 > 0:
let pitch = scale.quantize(written, program.track_scale(running, track, beat))
for u in track.listens:
program.note_on(&running.units[(usize)u], pitch, (f32)event.data2 / 127.0, 0.0, written = written)
elif kind == 0x80 or kind == 0x90:
for u in track.listens:
program.note_off_written(&running.units[(usize)u], written)
elif event.data1 == 120 or event.data1 == 123:
for u in track.listens:
program.release_all(&running.units[(usize)u])
## The metronome's click into `n` samples: a short high blip on each bar's
## first beat, a lower one on the others.
func click(shared: Shared*, l: f32[], r: f32[], n: usize, per_sample: f64):
for i in 0..<n:
let beat = shared.beat + per_sample * (f64)i
let whole = (f64)(i64)beat - (1.0 if beat < 0.0 and (f64)(i64)beat != beat else 0.0)
if beat - per_sample < whole and beat >= whole:
let bar = shared.click_bar if shared.click_bar > 0 else 4
let first = (i64)whole % bar == 0
shared.click_step = (f32)((1600.0 if first else 1000.0) / shared.rate)
shared.click_left = (f32)(0.03 * shared.rate)
shared.click_phase = 0.0
if shared.click_left > 0.0:
let fade = shared.click_left / (f32)(0.03 * shared.rate)
let y = 0.3 * dsp.sin_turns(shared.click_phase) * fade * fade
shared.click_phase += shared.click_step
shared.click_left -= 1.0
l[i] += y
r[i] += y
## Take a pending program, carrying the running state into it, when the
## main thread has collected the last one retired.
func take_program(shared: Shared*):
if shared.retired.load(.acquire) != none:
return
let next = shared.pending.swap(none, .acq_rel) else return
if let old = shared.current:
program.carry(next, old)
shared.retired.store(old, .release)
shared.current = next
shared.reposition = true
func drain(shared: Shared*):
let written = shared.written.load(.acquire)
var taken = shared.taken.load(.relaxed)
while taken != written:
let command = shared.commands[(usize)(taken % ring_size)]
apply(shared, command)
taken +%= 1
shared.taken.store(taken, .release)
func unit_of(running: Program*, id: i64) -> Unit*?:
for u in 0..<running.units.length:
if running.units[u].id == id: return &running.units[u]
return none
func apply(shared: Shared*, command: Command):
let kind = command.kind
if kind == command_play:
if not shared.playing:
shared.playing = true
shared.reposition = true
elif kind == command_stop:
shared.playing = false
if let running = shared.current: end_all(running)
elif kind == command_seek:
shared.beat = command.value if command.value > 0.0 else 0.0
if let running = shared.current: end_all(running)
shared.reposition = true
elif kind == command_tempo:
shared.tempo = dsp_clamp(command.value, 10.0, 999.0)
elif kind == command_loop:
shared.looping = command.a != 0
shared.loop_start = command.value
shared.loop_end = command.other
elif kind == command_master:
shared.master = (f32)command.value
elif kind == command_metronome:
shared.metronome = command.a != 0
shared.click_bar = command.b
else:
let running = shared.current else return
if kind == command_param:
let instrument = unit_of(running, command.a) else return
for k in 0..<instrument.nodes.length:
if instrument.nodes[k].id == command.b and command.c >= 0 and command.c < 16:
instrument.nodes[k].target[(usize)command.c] = (f32)command.value
elif kind == command_note_on:
let instrument = unit_of(running, command.a) else return
instrument.played = true
# A key plays the note its track's scale gives now.
let beat = shared.beat if shared.playing else 0.0
let pitch = scale.quantize((i32)command.b, program.track_scale(running, &running.tracks[(usize)instrument.track], beat))
program.note_on(instrument, pitch, (f32)command.value, 0.0, written = (i32)command.b)
elif kind == command_note_off:
let instrument = unit_of(running, command.a) else return
program.note_off_written(instrument, (i32)command.b)
elif kind == command_track:
for t in 0..<running.tracks.length:
var track = &running.tracks[t]
if track.id == command.a:
track.volume = (f32)command.value
track.pan = (f32)command.other
track.mute = (command.b & 1) != 0
track.solo = (command.b & 2) != 0
running.any_solo = false
for track in running.tracks:
if track.solo: running.any_solo = true
elif kind == command_panic:
for u in 0..<running.units.length:
program.silence(&running.units[u])
for l in 0..<running.lanes.length:
running.lanes[l].count = 0
## The master's last stage: linear to 0.92 (-0.7 dBFS, so a master limited
## to -1 dBTP passes untouched), then bending smoothly toward full scale, so
## an overloaded mix rounds off instead of clipping.
inline func safety(x: f32) -> f32:
let size = dsp.absf(x)
if size <= 0.92:
return x
let bent = 0.92 + 0.08 * dsp.soft_clip((size - 0.92) * 12.5)
return bent if x > 0.0 else -bent
func dsp_clamp(x: f64, low: f64, high: f64) -> f64:
if x < low: return low
if x > high: return high
return x
## Release every sounding note of every lane.
func end_all(running: Program*):
for l in 0..<running.lanes.length:
var lane = &running.lanes[l]
for s in 0..<lane.count:
for target in lane.targets:
program.note_off(&running.units[(usize)target], lane.sounding[s].pitch)
lane.count = 0
## Put each lane's cursor at the first note starting at or after `beat`.
func reposition(running: Program*, beat: f64, per_sample: f64):
let early = beat - per_sample * 0.5
for l in 0..<running.lanes.length:
var lane = &running.lanes[l]
var low: usize = 0
var high = lane.notes.length
while low < high:
let middle = low + (high - low) // 2
if lane.notes[middle].start < early:
low = middle + 1
else:
high = middle
lane.cursor = low
## End the notes due by `beat`, then start the ones due.
func fire(running: Program*, beat: f64, per_sample: f64):
let due = beat + per_sample * 0.5
for l in 0..<running.lanes.length:
var lane = &running.lanes[l]
if lane.curve: continue
var s: usize = 0
while s < lane.count:
if lane.sounding[s].end <= due:
for target in lane.targets:
program.note_off(&running.units[(usize)target], lane.sounding[s].pitch)
lane.count -= 1
lane.sounding[s] = lane.sounding[lane.count]
else:
s += 1
while lane.cursor < lane.notes.length and lane.notes[lane.cursor].start <= due:
let written = lane.notes[lane.cursor]
lane.cursor += 1
if written.end <= due: continue
# The note the track's scale gives, where it starts.
var note = written
note.pitch = scale.quantize(written.pitch, program.track_scale(running, &running.tracks[(usize)lane.track], written.start))
# The same pitch sounding again ends first, as a keyboard would.
var k: usize = 0
while k < lane.count:
if lane.sounding[k].pitch == note.pitch:
for target in lane.targets:
program.note_off(&running.units[(usize)target], note.pitch)
lane.count -= 1
lane.sounding[k] = lane.sounding[lane.count]
else:
k += 1
for target in lane.targets:
program.note_on(&running.units[(usize)target], note.pitch, note.velocity, note.pan)
if lane.count < program.most_sounding:
lane.sounding[lane.count] = program.Sounding(pitch = note.pitch, end = note.end)
lane.count += 1
## The beat of the next note start or end, or the loop's end.
func next_event(running: Program*, shared: Shared*, per_sample: f64) -> f64:
var next = 1.0e301
let after = shared.beat + per_sample * 0.5
for lane in running.lanes:
if lane.curve: continue
if lane.cursor < lane.notes.length:
let start = lane.notes[lane.cursor].start
if start > after and start < next: next = start
for s in 0..<lane.count:
let end = lane.sounding[s].end
if end > after and end < next: next = end
if shared.looping and shared.loop_end > shared.loop_start and shared.loop_end > after and shared.loop_end < next:
next = shared.loop_end
return next
## A curve lane's value at `beat`.
pub func curve_at(lane: const Lane*, beat: f64) -> f32:
let points = lane.points
if points.length == 0: return 0.0
if beat <= points[0].beat: return points[0].value
let last = points[points.length - 1]
if beat >= last.beat: return last.value
var low: usize = 0
var high = points.length - 1
while high - low > 1:
let middle = low + (high - low) // 2
if points[middle].beat <= beat: low = middle
else: high = middle
let a = points[low]
let b = points[high]
if a.shape == 1 or b.beat <= a.beat: return a.value
let t = (f32)((beat - a.beat) / (b.beat - a.beat))
return a.value + (b.value - a.value) * t
## Fill the controls curve lanes drive for the block from beat `first` to `last`.
func curves(running: Program*, first: f64, last: f64, frames: usize):
for u in 0..<running.units.length:
let controls = running.units[u].controls
for i in 0..<controls.length: controls[i] = 0.0
for l in 0..<running.lanes.length:
let lane = &running.lanes[l]
if not lane.curve or lane.unit < 0: continue
let instrument = &running.units[(usize)lane.unit]
let control = (usize)lane.control
if control >= program.most_controls: continue
let a = curve_at(lane, first)
let b = curve_at(lane, last)
let step = (b - a) / (f32)frames
let values = instrument.controls[control * chunk..<control * chunk + frames]
for i in 0..<frames:
values[i] += a + step * (f32)i
## Add `track`'s bus to the master at its volume and pan, and meter it.
func mix_track(shared: Shared*, running: Program*, track: Track*, index: usize, left: f32[], right: f32[], frames: usize):
if track.mute or (running.any_solo and not track.solo and not track.master):
return
var volume = track.volume
if track.volume_curve >= 0: volume = curve_at(&running.lanes[(usize)track.volume_curve], shared.beat)
var pan = track.pan
if track.pan_curve >= 0: pan = curve_at(&running.lanes[(usize)track.pan_curve], shared.beat)
pan = dsp.clampf(pan, -1.0, 1.0)
var lg: f32 = 1.0
var rg: f32 = 1.0
if track.channels == 1:
lg = dsp.sin_turns((1.0 - pan) * 0.125)
rg = dsp.sin_turns((1.0 + pan) * 0.125)
else:
if pan > 0.0: lg = 1.0 - pan
if pan < 0.0: rg = 1.0 + pan
lg *= volume
rg *= volume
var peak: f32 = 0.0
for i in 0..<frames:
var l = track.left[i]
var r = track.right[i]
if track.channels == 1:
let m = (l + r) * 0.5
l = m
r = m
l *= lg
r *= rg
left[i] += l
right[i] += r
let a = dsp.absf(l)
let b = dsp.absf(r)
if a > peak: peak = a
if b > peak: peak = b
if index < most_tracks:
_ = shared.peaks[index].max(peak.bits(), .relaxed)
# ---------------------------------------------------------------- the main thread
## The engine, as an application holds it.
pub struct Engine:
var shared: Shared*?
var output: Device?
var midi_input: MidiInput?
## The last message `midi_next` took from the input's main ring.
var last_midi: MidiEvent
## The sources as `midi_refresh` last read them.
var sources: midi.Endpoint[32]
var source_count: usize
var builder: Builder
var left: f32[]
var right: f32[]
var rendered: usize
## Stop sound and free everything.
pub func close():
self.stop_output()
self.close_midi()
if let shared = self.shared:
if let p = shared.pending.swap(none, .acq_rel): program.destroy(p)
if let p = shared.retired.swap(none, .acq_rel): program.destroy(p)
if let p = shared.current: program.destroy(p)
free(shared) in memory.heap
self.shared = none
self.builder.destroy()
if self.left.length > 0: free(self.left) in memory.heap
if self.right.length > 0: free(self.right) in memory.heap
self.left = self.left[0..<0]
self.right = self.right[0..<0]
func link() -> Shared*:
return self.shared else trap("the engine is closed")
# ------------------------------------------------ building
## Start describing a new program; `commit` makes it play.
pub func begin():
self.builder.clear()
## A track; answers its index for `add_unit` and `add_lane`. `volume`
## is a gain (1 is unity), `pan` -1..1, `channels` 1 or 2.
## A `master` track hears every other track's mix through its effects
## (Audio In) and gives the song's output: the mastering chain.
## `keyed` is how its notes take a scale: 0 as written, 1 the song's
## keys, 2 its own keys (`add_key`).
## `midi_in` is the MIDI it plays live (-1 none, 0 every source, else a
## source's id, `midi_sources`) on `channel` (0 any, 1..16), into the
## units `listen` names.
pub func add_track(id: i64, channels: i64, volume: f64, pan: f64, mute: bool, solo: bool, master: bool = false, keyed: i64 = 1, midi_in: i64 = -1, channel: i64 = 0) -> i64!:
try self.builder.tracks.append(TrackDraft(id = id, channels = (u32)channels, volume = (f32)volume, pan = (f32)pan, mute = mute, solo = solo, master = master, scale_mode = (u32)keyed,
midi_source = midi_in, midi_channel = (i32)channel))
return (i64)self.builder.tracks.length() - 1
## An instrument or effect on `track` with `voices` voices (1 to 32);
## `to_track` sends its output to the track's bus.
pub func add_unit(track: i64, id: i64, voices: i64, to_track: bool) -> i64!:
if track < 0 or voices < 1 or voices > (i64)program.most_voices:
error(result.invalid, "a unit has a track and 1 to 32 voices")
try self.builder.units.append(UnitDraft(id = id, track = (u32)track, voices = (u32)voices, to_track = to_track))
return (i64)self.builder.units.length() - 1
## A node of `kind` in `unit`'s patch, its parameters at their defaults.
pub func add_node(instrument: i64, id: i64, kind: i64) -> i64!:
if instrument < 0 or kind < 0 or kind >= (i64)kinds.count:
error(result.invalid, "a node has a unit and a known kind")
var params: f32[16]
for p in 0..<kinds.param_count((u32)kind):
params[p] = (f32)kinds.param((u32)kind, p).initial
try self.builder.nodes.append(NodeDraft(unit = (u32)instrument, id = id, kind = (u32)kind, params = params))
return (i64)self.builder.nodes.length() - 1
## Set parameter `slot` of node `node` (as `add_node` answered).
pub func node_param(node: i64, slot: i64, value: f64):
if node < 0 or node >= (i64)self.builder.nodes.length() or slot < 0 or slot >= 16:
return
var draft = self.builder.nodes.at((usize)node)
draft.params[(usize)slot] = (f32)value
self.builder.nodes.set((usize)node, draft)
## Wire output `output` of node `source` to input `input` of node
## `target` (both as `add_node` answered, in one unit).
pub func wire(source: i64, output: i64, target: i64, input: i64) -> !:
let count = (i64)self.builder.nodes.length()
if source < 0 or target < 0 or source >= count or target >= count or output < 0 or input < 0:
error(result.invalid, "a wire joins two nodes")
let instrument = self.builder.nodes.at((usize)source).unit
if self.builder.nodes.at((usize)target).unit != instrument:
error(result.invalid, "a wire joins two nodes of one unit")
try self.builder.wires.append(WireDraft(unit = instrument, source = (u32)source, output = (u32)output, target = (u32)target, input = (u32)input))
## `unit` hears `source`'s output at its Audio In.
pub func feed(instrument: i64, source: i64) -> !:
if instrument < 0 or source < 0:
error(result.invalid, "a feed joins two units")
try self.builder.feeds.append(FeedDraft(unit = (u32)instrument, source = (u32)source))
## A lane on `track` of notes, or with `curve` of curve points.
pub func add_lane(track: i64, id: i64, curve: bool) -> i64!:
if track < 0:
error(result.invalid, "a lane has a track")
try self.builder.lanes.append(LaneDraft(id = id, track = (u32)track, curve = curve, unit = -1, control = 0))
return (i64)self.builder.lanes.length() - 1
## Note lane `lane` plays `unit`.
pub func play_notes(lane: i64, instrument: i64) -> !:
if lane < 0 or instrument < 0:
error(result.invalid, "a lane plays a unit")
try self.builder.targets.append(TargetDraft(lane = (u32)lane, unit = (u32)instrument))
## Curve lane `lane` drives control `control` (0..7) of `unit`, or with
## `unit` -1 its track's volume (control 0) or pan (control 1).
pub func drive(lane: i64, instrument: i64, control: i64):
if lane < 0 or lane >= (i64)self.builder.lanes.length():
return
var draft = self.builder.lanes.at((usize)lane)
draft.unit = (i32)instrument
draft.control = (u32)control
self.builder.lanes.set((usize)lane, draft)
## A note in `lane`, `start` and `length` in beats.
pub func add_note(lane: i64, start: f64, length: f64, pitch: i64, velocity: f64, pan: f64) -> !:
if lane < 0 or length <= 0.0 or pitch < 0 or pitch > 127:
error(result.invalid, "a note has a lane, a length and a pitch 0..127")
try self.builder.notes.append(NoteDraft(lane = (u32)lane, note = Note(start = start, end = start + length, pitch = (i32)pitch, velocity = (f32)velocity, pan = (f32)pan)))
## A curve point in `lane`; `shape` 0 ramps to the next point, 1 holds.
pub func add_point(lane: i64, beat: f64, value: f64, shape: i64) -> !:
if lane < 0:
error(result.invalid, "a point has a lane")
try self.builder.points.append(PointDraft(lane = (u32)lane, point = Point(beat = beat, value = (f32)value, shape = (u32)shape)))
## Track `track` plays unit `unit` from the MIDI it hears.
pub func listen(track: i64, instrument: i64) -> !:
if track < 0 or instrument < 0:
error(result.invalid, "a track listens with a unit")
try self.builder.listens.append(ListenDraft(track = (u32)track, unit = (u32)instrument))
## A scale key: from `beat` on, `track`'s notes (with track -1, the
## song's: every track following it) take mode `mode` (`scale_modes`)
## on `root` 0..11 (C..B), until the next key.
pub func add_key(track: i64, beat: f64, root: i64, mode: i64) -> !:
if root < 0 or root > 11:
error(result.invalid, "a key's root is 0..11")
try self.builder.keys.append(KeyDraft(track = (i32)track, key = Key(beat = beat, scale = Scale(root = (i32)root, mask = scale.mode_mask(mode)))))
## Compile what was described since `begin` and hand it to the audio.
pub func commit() -> !:
let shared = self.link()
let made = try program.compile(&self.builder, shared.rate)
if let old = shared.pending.swap(made, .acq_rel):
program.destroy(old)
self.poll()
# ------------------------------------------------ playing
func send(command: Command):
let shared = self.link()
let written = shared.written.load(.relaxed)
if written -% shared.taken.load(.acquire) >= ring_size:
# The audio thread has fallen behind by a whole ring: drop it.
return
shared.commands[(usize)(written % ring_size)] = command
shared.written.store(written +% 1, .release)
if self.output == none:
self.poll()
func message(kind: u32, a: i64 = 0, b: i64 = 0, third: i64 = 0, value: f64 = 0.0, other: f64 = 0.0):
self.send(Command(kind = kind, a = a, b = b, c = third, value = value, other = other))
## Set parameter `slot` of node `node` of unit `unit` (by their ids) while playing.
pub func set_param(instrument: i64, node: i64, slot: i64, value: f64):
self.message(command_param, instrument, node, slot, value)
pub func play():
self.message(command_play)
pub func stop():
self.message(command_stop)
pub func seek(beat: f64):
self.message(command_seek, value = beat)
pub func set_tempo(bpm: f64):
self.message(command_tempo, value = bpm)
pub func set_loop(on: bool, start: f64, end: f64):
self.message(command_loop, 1 if on else 0, value = start, other = end)
pub func set_master(gain: f64):
self.message(command_master, value = gain)
## The metronome on or off, counting `beats_per_bar` to a bar.
pub func set_metronome(on: bool, beats_per_bar: i64):
self.message(command_metronome, 1 if on else 0, beats_per_bar)
# ------------------------------------------------ MIDI
## Listen to every MIDI source. `waker` is woken (on any thread) when
## messages wait in `midi_next` or the sources change.
pub func open_midi(waker: interop.Reference[wake.Waker]? = none) -> !:
if self.midi_input != none: return
var input = try MidiInput.open(waker = waker, name = "Luced Music")
self.midi_input = input
let shared = self.link()
shared.midi.store(input.audio(), .release)
## Close the MIDI input; the device is stopped first (`close`), so no
## block still holds its ring.
func close_midi():
if let input = self.midi_input:
var held = input
let shared = self.link()
shared.midi.store(none, .release)
held.close()
self.midi_input = none
## Take the next MIDI message for the main thread (recording, a light),
## then read it with `midi_status` and the rest. False when none waits.
pub func midi_next() -> bool:
let input = self.midi_input else return false
let ring = input.main() else return false
return ring.next(&self.last_midi)
pub func midi_status() -> i64:
return (i64)self.last_midi.status
pub func midi_data1() -> i64:
return (i64)self.last_midi.data1
pub func midi_data2() -> i64:
return (i64)self.last_midi.data2
pub func midi_source() -> i64:
return (i64)self.last_midi.source
## When the last message arrived, in host nanoseconds (as `beat_at` takes).
pub func midi_nanos() -> i64:
return (i64)self.last_midi.nanos
## Read the MIDI sources as they are now, for `midi_source_id` and
## `midi_source_name`; answers how many there are.
pub func midi_refresh() -> i64:
self.source_count = midi.sources(self.sources)
return (i64)self.source_count
## Source `index`'s unique id (what `add_track`'s `midi` names), as of
## the last `midi_refresh`.
pub func midi_source_id(index: i64) -> i64:
if index < 0 or (usize)index >= self.source_count: return -1
return (i64)self.sources[(usize)index].id
pub func midi_source_name(index: i64) -> str:
if index < 0 or (usize)index >= self.source_count: return ""
return self.sources[(usize)index].name()
## Bumped whenever MIDI sources come or go.
pub func midi_generation() -> i64:
let input = self.midi_input else return 0
return (i64)input.generation()
## The beat heard at host time `nanos` (`midi_nanos`), from the clock the
## device's last block set; the transport's beat without a device.
pub func beat_at(nanos: i64) -> f64:
let shared = self.link()
if self.output == none: return shared.beat
var tries = 0
while tries < 8:
let before = shared.clock_seq.load(.acquire)
let beat = f64.bits(shared.clock_beat.load(.relaxed))
let at = shared.clock_nanos.load(.relaxed)
let rate = f64.bits(shared.clock_rate.load(.relaxed))
if before % 2 == 0 and shared.clock_seq.load(.acquire) == before:
return beat + ((f64)nanos - (f64)at) * rate
tries += 1
return f64.bits(shared.clock_beat.load(.relaxed))
## Now on the clock `beat_at` and `midi_nanos` use.
pub func now_nanos() -> i64:
return (i64)midi.now_nanos()
## A track's live mix settings, by its id.
pub func set_track(id: i64, volume: f64, pan: f64, mute: bool, solo: bool):
self.message(command_track, id, (1 if mute else 0) | (2 if solo else 0), value = volume, other = pan)
## Play `pitch` on unit `unit` (by id) now, as a keyboard does.
pub func note_on(instrument: i64, pitch: i64, velocity: f64):
self.message(command_note_on, instrument, pitch, value = velocity)
pub func note_off(instrument: i64, pitch: i64):
self.message(command_note_off, instrument, pitch)
## Silence everything at once.
pub func panic():
self.message(command_panic)
# ------------------------------------------------ what it is doing
## Where the transport is, in beats.
pub func position() -> f64:
return f64.bits(self.link().shown_beat.load(.relaxed))
pub func is_playing() -> bool:
return self.link().shown_playing.load(.relaxed)
## The loudest sample track `index` (in commit order) played since the
## last call.
pub func peak(index: i64) -> f64:
if index < 0 or index >= (i64)most_tracks: return 0.0
return (f64)f32.bits(self.link().peaks[(usize)index].swap(0, .relaxed))
## The last buffer's processing time as a share of its duration, and
## the largest since the last call.
pub func load() -> f64:
return f64.bits(self.link().load.load(.relaxed))
pub func peak_load() -> f64:
return f64.bits(self.link().peak_load.swap(0, .relaxed))
pub func sounding_voices() -> i64:
return (i64)self.link().voices.load(.relaxed)
pub func sample_rate() -> f64:
return self.link().rate
## Free what the audio thread has retired; with no device running, also
## take a pending program and commands, as the audio thread would.
pub func poll():
let shared = self.link()
if let old = shared.retired.swap(none, .acq_rel):
program.destroy(old)
if self.output == none:
take_program(shared)
drain(shared)
if let old = shared.retired.swap(none, .acq_rel):
program.destroy(old)
## Whether the audio thread has yet to act on what was sent it: a command it
## hasn't read, a program waiting for it, or one it retired that `poll` has
## yet to free. The UI polls again while this holds, and sleeps once it
## settles.
pub func settling() -> bool:
let shared = self.link()
if shared.written.load(.acquire) != shared.taken.load(.acquire): return true
return shared.pending.load(.acquire) != none or shared.retired.load(.acquire) != none
# ------------------------------------------------ the device
## Play through the default output device, asking for `frames` per buffer.
pub func start_output(frames: i64 = 64) -> !:
if self.output != none: return
let shared = self.link()
self.poll()
var made = try Device.open(device_render, (void*)shared, frames = (u32)frames, channels = 2)
errdefer made.close()
if made.sample_rate != shared.rate and made.sample_rate > 0.0:
shared.rate = made.sample_rate
if shared.current != none or shared.pending.load(.acquire) != none:
let again = try program.compile(&self.builder, shared.rate)
if let old = shared.pending.swap(again, .acq_rel): program.destroy(old)
shared.heard_after = (u64)((f64)(made.output_latency + made.buffer_frames) / made.sample_rate * 1000000000.0) if made.sample_rate > 0.0 else 0
try made.start()
self.output = made
pub func stop_output():
if let running = self.output:
var made = running
made.stop()
made.close()
self.output = none
if self.shared != none: self.poll()
pub func output_running() -> bool:
return self.output != none
## Frames per buffer of the running device, else 0.
pub func buffer_frames() -> i64:
if let made = self.output: return (i64)made.buffer_frames
return 0
## What it takes a note to reach the speaker: the buffer and the
## device's own latency, in milliseconds.
pub func output_latency() -> f64:
if let made = self.output:
return f64(made.buffer_frames + made.output_latency) / made.sample_rate * 1000.0
return 0.0
# ------------------------------------------------ offline
## Render `frames` samples without a device (tests, bouncing); read
## them with `sample` and `level`.
pub func render(frames: i64) -> !:
if self.output != none:
error(result.invalid, "the engine renders offline only while no device plays")
if frames < 0:
error(result.invalid, "a render has a length")
if self.left.length > 0: free(self.left) in memory.heap
if self.right.length > 0: free(self.right) in memory.heap
self.left = self.left[0..<0]
self.right = self.right[0..<0]
self.left = try new f32[(usize)frames] in memory.heap
self.right = try new f32[(usize)frames] in memory.heap
let shared = self.link()
if let old = shared.retired.swap(none, .acq_rel): program.destroy(old)
process(shared, self.left, self.right, (usize)frames)
# Offline, the live MIDI ring has no listener: empty it.
if let ring = shared.midi.load(.acquire):
var event: MidiEvent
while ring.next(&event): _ = 0
if let old = shared.retired.swap(none, .acq_rel): program.destroy(old)
self.rendered = (usize)frames
## Write the last render to `path` as a 24-bit stereo WAV.
pub func export_wav(path: str) -> !:
try save_wav(&self, path)
## Sample `index` of channel `channel` (0 left, 1 right) of the last render.
pub func sample(channel: i64, index: i64) -> f64:
if index < 0 or (usize)index >= self.rendered: return 0.0
return (f64)(self.left[(usize)index] if channel == 0 else self.right[(usize)index])
## The RMS level of channel `channel` of the last render, from sample
## `start` to `end` (-1: its end).
pub func level(channel: i64, start: i64 = 0, end: i64 = -1) -> f64:
let samples = self.left if channel == 0 else self.right
var sum: f64 = 0.0
var count: usize = 0
var i = (usize)(start if start > 0 else 0)
let stop = self.rendered if end < 0 or (usize)end > self.rendered else (usize)end
while i < stop:
sum += (f64)samples[i] * (f64)samples[i]
count += 1
i += 1
if count == 0: return 0.0
return f64_sqrt(sum / (f64)count)
## Write the last render to `path` as a 24-bit stereo WAV.
pub func save_wav(engine: const Engine*, path: str) -> !:
let frames = engine.rendered
let rate = (u32)engine.link().rate
let size = 44 + frames * 6
var bytes = try new u8[size] --- in memory.heap
defer free(bytes) in memory.heap
put(bytes, 0, b"RIFF")
put32(bytes, 4, (u32)(size - 8))
put(bytes, 8, b"WAVEfmt ")
put32(bytes, 16, 16)
put16(bytes, 20, 1)
put16(bytes, 22, 2)
put32(bytes, 24, rate)
put32(bytes, 28, rate * 6)
put16(bytes, 32, 6)
put16(bytes, 34, 24)
put(bytes, 36, b"data")
put32(bytes, 40, (u32)(frames * 6))
for i in 0..<frames:
put24(bytes, 44 + i * 6, engine.left[i])
put24(bytes, 47 + i * 6, engine.right[i])
let name = try strings.copy(path)
defer strings.release(name)
try files.write((c.str)name, bytes)
func put(bytes: u8[], at: usize, text: const u8[]):
for i in 0..<text.length: bytes[at + i] = text[i]
func put16(bytes: u8[], at: usize, value: u16):
bytes[at] = (u8)value
bytes[at + 1] = (u8)(value >> 8)
func put32(bytes: u8[], at: usize, value: u32):
bytes[at] = (u8)value
bytes[at + 1] = (u8)(value >> 8)
bytes[at + 2] = (u8)(value >> 16)
bytes[at + 3] = (u8)(value >> 24)
func put24(bytes: u8[], at: usize, sample: f32):
let clipped = dsp.clampf(sample, -1.0, 1.0)
let value = (u32)(i32)(clipped * 8388607.0)
bytes[at] = (u8)value
bytes[at + 1] = (u8)(value >> 8)
bytes[at + 2] = (u8)(value >> 16)
extern func sqrt(x: f64) -> f64
func f64_sqrt(x: f64) -> f64:
return sqrt(x)
pub let engine_type: interop.Type[Engine] = interop.Type[Engine]("Engine", Engine.close, closeable = true, main_thread = true)
## A stopped engine at `rate` samples a second, playing nothing.
pub func create(rate: f64 = 48000.0) -> Engine!:
let shared = try new Shared in memory.heap
shared.rate = rate
shared.tempo = 120.0
shared.master = 1.0
shared.loop_end = 16.0
return Engine(shared = shared, output = none, rendered = 0)
## An engine for Luce.
pub func open(rate: f64 = 48000.0) -> interop.Reference[Engine]!:
var made = try create(rate)
let held = new Engine(shared = made.shared, output = none, rendered = 0) in memory.heap catch failure:
made.close()
error(failure.code, failure.message)
return try interop.Reference[Engine].adopt(held, engine_type, memory.heap)
# ---------------------------------------------------------------- the kinds, for Luce
## The scale modes `add_key` takes, as menu items: "Chromatic|Major|…".
pub func scale_modes() -> str:
return scale.mode_names
## The root names, "C|C♯|D|…".
pub func scale_roots() -> str:
return scale.root_names
## Whether MIDI note `note` is in mode `mode` on `root`.
pub func in_scale(note: i64, root: i64, mode: i64) -> bool:
return scale.contains(Scale(root = (i32)root, mask = scale.mode_mask(mode)), (i32)note)
## The note mode `mode` on `root` gives `note`.
pub func quantize_note(note: i64, root: i64, mode: i64) -> i64:
return (i64)scale.quantize((i32)note, Scale(root = (i32)root, mask = scale.mode_mask(mode)))
pub func kind_count() -> i64:
return (i64)kinds.count
func kind_spec(kind: i64) -> kinds.KindSpec:
return kinds.kinds[(usize)kind if kind >= 0 and kind < (i64)kinds.count else 0]
pub func kind_name(kind: i64) -> str:
return kind_spec(kind).name
pub func kind_category(kind: i64) -> str:
return kind_spec(kind).category
pub func kind_doc(kind: i64) -> str:
return kind_spec(kind).doc
## A kind's input (or output) ports, comma-separated.
pub func kind_inputs(kind: i64) -> str:
return kind_spec(kind).inputs
pub func kind_outputs(kind: i64) -> str:
return kind_spec(kind).outputs
pub func param_count(kind: i64) -> i64:
return (i64)kind_spec(kind).count
func param_spec(kind: i64, index: i64) -> kinds.ParamSpec:
let spec = kind_spec(kind)
let at = (usize)index if index >= 0 and index < (i64)spec.count else 0
return kinds.params[(usize)spec.first + at]
pub func param_name(kind: i64, index: i64) -> str:
return param_spec(kind, index).name
pub func param_minimum(kind: i64, index: i64) -> f64:
return param_spec(kind, index).minimum
pub func param_maximum(kind: i64, index: i64) -> f64:
return param_spec(kind, index).maximum
pub func param_default(kind: i64, index: i64) -> f64:
return param_spec(kind, index).initial
pub func param_units(kind: i64, index: i64) -> str:
return param_spec(kind, index).units
pub func param_items(kind: i64, index: i64) -> str:
return param_spec(kind, index).items
pub func param_logarithmic(kind: i64, index: i64) -> bool:
return param_spec(kind, index).logarithmic
# ---------------------------------------------------------------- tests
## A track playing a four-voice synth: Note In → Oscillator (sine) →
## Multiply by an Envelope → Output. Answers (track, synth, lane, envelope).
func synth(engine: Engine*) -> (i64, i64, i64, i64)!:
let track = try engine.add_track(1, 2, 1.0, 0.0, false, false)
let voice = try engine.add_unit(track, 10, 4, true)
let note = try engine.add_node(voice, 100, (i64)kinds.note_in)
let tone = try engine.add_node(voice, 101, (i64)kinds.oscillator)
let shape = try engine.add_node(voice, 102, (i64)kinds.envelope)
let amp = try engine.add_node(voice, 103, (i64)kinds.multiply)
let out = try engine.add_node(voice, 104, (i64)kinds.output)
engine.node_param(tone, 0, 0.0)
engine.node_param(tone, 4, 0.5)
engine.node_param(shape, 3, 0.05)
try engine.wire(note, 0, tone, 0)
try engine.wire(tone, 0, amp, 0)
try engine.wire(shape, 0, amp, 1)
try engine.wire(amp, 0, out, 0)
let lane = try engine.add_lane(track, 20, false)
try engine.play_notes(lane, voice)
return (track, voice, lane, shape)
func crossings(engine: const Engine*, start: usize, end: usize) -> i64:
var count: i64 = 0
for i in start + 1..<end:
if (engine.left[i - 1] < 0.0) != (engine.left[i] < 0.0): count += 1
return count
test "a note sounds at its pitch and falls silent after its release":
var engine = try create(48000.0)
defer engine.close()
engine.begin()
let (track, voice, lane, shape) = try synth(&engine)
# A4 for one beat: half a second at 120 bpm.
try engine.add_note(lane, 0.0, 1.0, 69, 1.0, 0.0)
try engine.commit()
engine.play()
try engine.render(48000)
assert(engine.level(0, 0, 19200) > 0.1)
# 440 Hz crosses zero 880 times a second: 352 in 0.4 s.
let crossed = crossings(&engine, 0, 19200)
assert(crossed >= 350 and crossed <= 354)
# Released at 0.5 s with a 50 ms release: silent by 0.7 s.
assert(engine.level(0, 33600, 48000) < 0.0005)
assert(engine.position() > 1.99 and engine.position() < 2.01)
test "a note starts on its sample":
var engine = try create(48000.0)
defer engine.close()
engine.begin()
let (track, voice, lane, shape) = try synth(&engine)
# Beat 0.5 is 0.25 s: sample 12000.
try engine.add_note(lane, 0.5, 0.5, 60, 1.0, 0.0)
try engine.commit()
engine.play()
try engine.render(13000)
var before: f64 = 0.0
for i in 0..<12000: before += dsp_abs(engine.sample(0, (i64)i))
var after: f64 = 0.0
for i in 12000..<12100: after += dsp_abs(engine.sample(0, (i64)i))
assert(before == 0.0 and after > 0.0)
test "notes take the song's key where they start, and a track playing as written keeps them":
var engine = try create(48000.0)
defer engine.close()
engine.begin()
let (track, voice, lane, shape) = try synth(&engine)
# A minor, then B♭ major from beat 2 (120 bpm: a beat is 24000 samples).
try engine.add_key(-1, 0.0, 9, 2)
try engine.add_key(-1, 2.0, 10, 1)
# B♭4 twice: A minor has no B♭, so the first is A4 (440 Hz); the second is B♭ (466 Hz).
try engine.add_note(lane, 0.0, 1.0, 70, 1.0, 0.0)
try engine.add_note(lane, 2.0, 1.0, 70, 1.0, 0.0)
try engine.commit()
engine.play()
try engine.render(72000)
let first = crossings(&engine, 0, 19200)
let second = crossings(&engine, 48000, 67200)
assert(first >= 350 and first <= 354, "A minor moves B♭ to A")
assert(second >= 371 and second <= 375, "B♭ major keeps B♭")
# As written: the first note stays B♭.
engine.begin()
let plain = try engine.add_track(1, 2, 1.0, 0.0, false, false, keyed = 0)
try engine.add_key(-1, 0.0, 9, 2)
let player = try engine.add_unit(plain, 10, 4, true)
let note = try engine.add_node(player, 100, (i64)kinds.note_in)
let tone = try engine.add_node(player, 101, (i64)kinds.oscillator)
let out = try engine.add_node(player, 104, (i64)kinds.output)
engine.node_param(tone, 0, 0.0)
engine.node_param(tone, 4, 0.5)
try engine.wire(note, 0, tone, 0)
try engine.wire(tone, 0, out, 0)
let written = try engine.add_lane(plain, 20, false)
try engine.play_notes(written, player)
try engine.add_note(written, 0.0, 1.0, 70, 1.0, 0.0)
try engine.commit()
engine.stop()
engine.seek(0.0)
engine.play()
try engine.render(24000)
let kept = crossings(&engine, 0, 19200)
assert(kept >= 371 and kept <= 375, "a track as written ignores the key")
test "a held key's release finds the voice its scale moved":
var engine = try create(48000.0)
defer engine.close()
engine.begin()
let (track, voice, lane, shape) = try synth(&engine)
try engine.add_key(-1, 0.0, 0, 1)
try engine.commit()
# C♯ in C major sounds C; releasing C♯ must end it.
engine.note_on(10, 61, 1.0)
try engine.render(4800)
assert(engine.level(0, 0, 4800) > 0.1)
engine.note_off(10, 61)
try engine.render(48000)
assert(engine.level(0, 24000, 48000) < 0.0005)
test "MIDI plays the tracks listening for its source and channel, through their scale":
var engine = try create(48000.0)
defer engine.close()
engine.begin()
let keys = try engine.add_track(1, 2, 1.0, 0.0, false, false, midi_in = 0, channel = 2)
let player = try engine.add_unit(keys, 10, 4, true)
let note = try engine.add_node(player, 100, (i64)kinds.note_in)
let tone = try engine.add_node(player, 101, (i64)kinds.oscillator)
let out = try engine.add_node(player, 104, (i64)kinds.output)
engine.node_param(tone, 0, 0.0)
engine.node_param(tone, 4, 0.5)
try engine.wire(note, 0, tone, 0)
try engine.wire(tone, 0, out, 0)
try engine.listen(keys, player)
try engine.add_key(-1, 0.0, 9, 2)
try engine.commit()
let shared = engine.link()
let running = shared.current else trap("no program")
# Channel 1 is not this track's.
route_midi(shared, running, MidiEvent(source = 5, status = 0x90, data1 = 70, data2 = 100, nanos = 0))
try engine.render(4800)
assert(engine.level(0, 0, 4800) == 0.0)
# Channel 2: B♭4 in A minor sounds A4.
route_midi(shared, running, MidiEvent(source = 5, status = 0x91, data1 = 70, data2 = 100, nanos = 0))
try engine.render(19200)
let crossed = crossings(&engine, 0, 19200)
assert(crossed >= 350 and crossed <= 354)
# Its note-off (a note-on at velocity 0) names the key pressed, B♭.
route_midi(shared, running, MidiEvent(source = 5, status = 0x91, data1 = 70, data2 = 0, nanos = 0))
try engine.render(48000)
assert(engine.level(0, 24000, 48000) < 0.0005)
test "the metronome clicks on the beat, higher on the bar":
var engine = try create(48000.0)
defer engine.close()
engine.begin()
let track = try engine.add_track(1, 2, 1.0, 0.0, false, false)
try engine.commit()
engine.set_metronome(true, 4)
engine.play()
# 120 bpm: beats at 0, 24000, 48000 samples.
try engine.render(50000)
assert(engine.level(0, 0, 1200) > 0.05 and engine.level(0, 2000, 23900) == 0.0)
assert(engine.level(0, 24000, 25200) > 0.05)
let bar = crossings(&engine, 0, 1200)
let beat = crossings(&engine, 24000, 25200)
assert(bar > beat)
func dsp_abs(x: f64) -> f64:
return -x if x < 0.0 else x
test "an edit while a note sounds keeps the note going":
var engine = try create(48000.0)
defer engine.close()
engine.begin()
var parts = try synth(&engine)
try engine.add_note(parts.2, 0.0, 4.0, 60, 1.0, 0.0)
try engine.commit()
engine.play()
try engine.render(4800)
let first = engine.level(0, 2400, 4800)
# The same song again, the oscillator a square now: the voice carries over.
engine.begin()
parts = try synth(&engine)
engine.node_param(1, 0, 3.0)
try engine.add_note(parts.2, 0.0, 4.0, 60, 1.0, 0.0)
try engine.commit()
try engine.render(4800)
# No restart: the attack would begin from silence.
assert(engine.level(0, 0, 240) > first * 0.5)
assert(engine.sounding_voices() == 1)
test "a curve lane drives a control input across the beats":
var engine = try create(48000.0)
defer engine.close()
engine.begin()
let track = try engine.add_track(1, 2, 1.0, 0.0, false, false)
let level = try engine.add_unit(track, 30, 1, true)
let control = try engine.add_node(level, 300, (i64)kinds.control_in)
let out = try engine.add_node(level, 301, (i64)kinds.output)
try engine.wire(control, 0, out, 0)
let lane = try engine.add_lane(track, 40, true)
engine.drive(lane, level, 0)
try engine.add_point(lane, 0.0, 0.0, 0)
try engine.add_point(lane, 4.0, 1.0, 0)
try engine.commit()
engine.play()
# Two beats at 120 bpm: one second, halfway up the ramp.
try engine.render(48000)
let last = engine.sample(0, 47999)
assert(last > 0.49 and last < 0.51)
test "an effect hears the instrument it is fed and a muted track is silent":
var engine = try create(48000.0)
defer engine.close()
engine.begin()
let track = try engine.add_track(1, 2, 1.0, 0.0, false, false)
let voice = try engine.add_unit(track, 10, 1, false)
let note = try engine.add_node(voice, 100, (i64)kinds.note_in)
let tone = try engine.add_node(voice, 101, (i64)kinds.oscillator)
let out = try engine.add_node(voice, 102, (i64)kinds.output)
try engine.wire(note, 0, tone, 0)
try engine.wire(tone, 0, out, 0)
let effect = try engine.add_unit(track, 11, 1, true)
let input = try engine.add_node(effect, 110, (i64)kinds.audio_in)
let louder = try engine.add_node(effect, 111, (i64)kinds.gain)
let after = try engine.add_node(effect, 112, (i64)kinds.output)
engine.node_param(louder, 0, -6.0206)
try engine.wire(input, 0, louder, 0)
try engine.wire(louder, 0, after, 0)
try engine.feed(effect, voice)
let lane = try engine.add_lane(track, 20, false)
try engine.play_notes(lane, voice)
try engine.add_note(lane, 0.0, 8.0, 60, 1.0, 0.0)
try engine.commit()
engine.play()
try engine.render(9600)
# A saw at level 0.5 halved: RMS 0.25 / sqrt(3).
let heard = engine.level(0, 2400, 9600)
assert(heard > 0.13 and heard < 0.16)
engine.set_track(1, 1.0, 0.0, true, false)
try engine.render(4800)
assert(engine.level(0) == 0.0)
test "the master track's chain hears the whole mix, and solo leaves it on":
for chained in [false, true]:
var engine = try create(48000.0)
defer engine.close()
engine.begin()
let track = try engine.add_track(1, 2, 1.0, 0.0, false, false)
let voice = try engine.add_unit(track, 10, 1, true)
let note = try engine.add_node(voice, 100, (i64)kinds.note_in)
let tone = try engine.add_node(voice, 101, (i64)kinds.oscillator)
let out = try engine.add_node(voice, 102, (i64)kinds.output)
try engine.wire(note, 0, tone, 0)
try engine.wire(tone, 0, out, 0)
let master = try engine.add_track(2, 2, 1.0, 0.0, false, false, true)
if chained:
let effect = try engine.add_unit(master, 20, 1, true)
let input = try engine.add_node(effect, 200, (i64)kinds.audio_in)
let quieter = try engine.add_node(effect, 201, (i64)kinds.gain)
let after = try engine.add_node(effect, 202, (i64)kinds.output)
engine.node_param(quieter, 0, -6.0206)
try engine.wire(input, 0, quieter, 0)
try engine.wire(input, 1, quieter, 0)
try engine.wire(quieter, 0, after, 0)
let lane = try engine.add_lane(track, 30, false)
try engine.play_notes(lane, voice)
try engine.add_note(lane, 0.0, 8.0, 60, 1.0, 0.0)
try engine.commit()
engine.play()
try engine.render(9600)
let heard = engine.level(0, 2400, 9600)
# The saw at 0.5: RMS 0.289, halved by the master's chain.
if chained:
assert(heard > 0.13 and heard < 0.16, "the master's gain")
else:
assert(heard > 0.27 and heard < 0.31, "an empty master passes the mix")
engine.set_track(1, 1.0, 0.0, false, true)
try engine.render(4800)
assert(engine.level(0) > 0.1, "a solo does not silence the master")
test "every kind, fed a loud saw on every input, stays finite and bounded":
for kind in 0..<(i64)kinds.count:
var engine = try create(48000.0)
defer engine.close()
engine.begin()
let track = try engine.add_track(1, 2, 1.0, 0.0, false, false)
let voice = try engine.add_unit(track, 10, 2, true)
let note = try engine.add_node(voice, 100, (i64)kinds.note_in)
let saw = try engine.add_node(voice, 101, (i64)kinds.oscillator)
let node = try engine.add_node(voice, 102, kind)
let out = try engine.add_node(voice, 103, (i64)kinds.output)
engine.node_param(saw, 4, 1.0)
try engine.wire(note, 0, saw, 0)
let inputs = kinds.input_count((u32)kind)
for input in 0..<inputs:
# The note's gate where a kind takes one, the saw elsewhere.
if kinds.name_at(kinds.kinds[(usize)kind].inputs, input) == "gate":
try engine.wire(note, 1, node, (i64)input)
else:
try engine.wire(saw, 0, node, (i64)input)
if kinds.output_count((u32)kind) > 0:
try engine.wire(node, 0, out, 0)
let lane = try engine.add_lane(track, 20, false)
try engine.play_notes(lane, voice)
try engine.add_note(lane, 0.0, 1.0, 48, 1.0, 0.0)
try engine.add_note(lane, 0.5, 1.0, 84, 1.0, 0.0)
try engine.commit()
engine.play()
try engine.render(48000)
for i in 0..<48000:
let v = engine.sample(0, (i64)i)
assert(v == v and v < 1.01 and v > -1.01, "a kind went non-finite or out of bounds")