audio.synth
Making sound from nothing: oscillators, envelopes and voices.
import audio.synth
Everything else in this family reads sound that already exists. This package makes it. Six waveforms, an envelope to shape a note, three colours of noise, and four ways of building a voice that sounds like something rather than like a test tone.
The quickest way in is Tone for a bare waveform or ToneEnvelope for a note that starts and stops the way an instrument does. To play a phrase, fill a vector of Note and hand it to RenderNotes, which mixes and pans them into one clip.
Things to know
- An oscillator carries its own phase, so stepping it with
OscNextin a loop gives a continuous tone.WaveValueis the stateless form. - A note lasts longer than you asked:
ADSRTotaladds the release onto the hold, and that is the lengthToneEnvelopegives you. Chorddivides by the number of notes, so three notes together do not clip.RenderNotesdoes not, so give its notes a gain that leaves room.- For which notes to play, see audio.music, which also carries the Persian dastgah; to play a file of notes, see audio.midi.
A first tone
Tone takes a frequency, a length in seconds, a sample rate and a wave shape and returns a mono clip of float samples. Sine, square, saw, triangle, noise and pulse are available as constants.
The example measures the clip with Duration, Peak and IsClipped, then encodes it as WAV in memory. Free the clip with audio.Free and the buffer with compress.BufFree.
import audio
import audio.synth
import audio.wav
import compress
func main:
clip := synth.Tone(440.0, 1.0, 44100, synth.WaveSine)
println clip.rate, clip.channels, clip.frames
println "seconds:", audio.Duration(clip)
println "loud enough:", audio.Peak(clip) > 0.9
println "clipped:", audio.IsClipped(clip)
mut enc := wav.EncodeWAV(clip)
println "wav bytes:", compress.BufLen(enc)
println "is wav:", wav.IsWAV(enc.data, enc.len)
mut c := clip
audio.Free(c)
compress.BufFree(enc)
endShaping a note with an envelope
A bare tone starts and stops abruptly, which clicks. An ADSR envelope fixes that: the level rises over attack seconds, falls to sustain over decay, holds while the note is held, and fades over release.
ADSRAt gives the level at a moment in time for a note held a given number of seconds, which is a good way to check your numbers. ToneEnvelope applies the envelope and a gain while it renders.
import audio
import audio.synth
func main:
e := synth.ADSR { attack = 0.05, decay = 0.1, sustain = 0.6, release = 0.2 }
println "total:", synth.ADSRTotal(e, 0.5)
each t in [0.0, 0.025, 0.05, 0.3, 0.5]:
println t, synth.ADSRAt(e, t, 0.5)
end
flat := synth.Tone(440.0, 0.7, 22050, synth.WaveSaw)
shaped := synth.ToneEnvelope(440.0, 0.5, 22050, synth.WaveSaw, e, 0.8)
println "flat peak:", audio.Peak(flat) > 0.9
println "shaped peak:", audio.Peak(shaped) <= 0.81
println "starts silent:", audio.Sample(shaped, 0, 0) == 0.0
mut a := flat
audio.Free(a)
mut b := shaped
audio.Free(b)
endPlaying several notes
For more than one note, build a vector of Note values with NoteAt, giving each a note number, a start time, a length, a gain and a wave. RenderNotes mixes them all into one clip, with the channel count you ask for and the envelope applied to every note.
Here the notes come from a major scale in audio.music, one every quarter second.
import audio
import audio.music
import audio.synth
func main:
e := synth.ADSR { attack = 0.01, decay = 0.05, sustain = 0.5, release = 0.1 }
mut notes := Vector {} as Vector<synth.Note>
defer notes.Free()
mut scale := music.ScaleNotes(60, music.ScaleMajor, 8)
defer scale.Free()
mut i := 0
until i < scale.Len():
start := (i as f64) * 0.25
notes.Push(synth.NoteAt(scale.Get(i), start, 0.25, 0.5, synth.WaveTriangle))
i++
end
println "notes:", notes.Len()
song := synth.RenderNotes(notes, 22050, 2, e)
println song.channels, song.rate
println "seconds:", audio.Duration(song) > 2.0
println "clipped:", audio.IsClipped(song)
mut s := song
audio.Free(s)
endTypes
Osc
struct Osc| Name | Type | Description |
|---|---|---|
wave | int = 0 | Which waveform it makes. |
freq | f64 = 440 | Its pitch in hertz. |
phase | f64 = 0 | Where in the cycle it is, from 0 to 1. |
duty | f64 = 0.5 | How much of a pulse cycle is high. |
rate | int = 44100 | The sample rate it is stepping at. |
import audio
import audio.synth
import math
func main:
mut o := synth.NewOsc(synth.WaveSine, 440.0, 44100)
println o.wave, o.freq, o.rate, o.phase
first := synth.OscNext(o)
println math.Abs(first) < 0.0001, o.phase > 0.0
println synth.WaveValue(synth.WaveSine, 0.0, 0.5)
println synth.WaveValue(synth.WaveSaw, 0.5, 0.5)
println synth.WaveValue(synth.WaveSquare, 0.25, 0.5), synth.WaveValue(synth.WaveSquare, 0.75, 0.5)
println synth.WaveValue(synth.WaveTriangle, 0.25, 0.5)
println synth.WaveValue(synth.WavePulse, 0.1, 0.25)
t := synth.Tone(440.0, 0.05, 22050, synth.WaveSine)
println t.frames, t.rate, audio.Peak(t) > 0.9
e := synth.ADSR { attack = 0.1, decay = 0.1, sustain = 0.5, release = 0.2 }
println e.attack, e.sustain
println synth.ADSRAt(e, 0.0, 1.0), synth.ADSRAt(e, 0.05, 1.0), synth.ADSRAt(e, 0.1, 1.0)
println synth.ADSRAt(e, 0.2, 1.0), synth.ADSRAt(e, 0.5, 1.0)
println synth.ADSRAt(e, 1.2, 1.0) < 0.0001, synth.ADSRAt(e, 5.0, 1.0)
println synth.ADSRTotal(e, 1.0)
shaped := synth.ToneEnvelope(440.0, 0.05, 22050, synth.WaveSine, e, 0.8)
println audio.Sample(shaped, 0, 0), audio.Peak(shaped) <= 0.81
mut d := t
audio.Free(d)
mut d2 := shaped
audio.Free(d2)
endADSR
struct ADSR| Name | Type | Description |
|---|---|---|
attack | f64 = 0.01 | Seconds from silence to full. |
decay | f64 = 0.05 | Seconds from full down to the sustain level. |
sustain | f64 = 0.7 | The level a held note rests at. |
release | f64 = 0.1 | Seconds from the sustain level back to silence. |
The example for this item is shown with the ones above: synth-Osc.salam
Note
struct Note| Name | Type | Description |
|---|---|---|
note | int = 60 | The MIDI note number. |
start | f64 = 0 | When it starts, in seconds. |
length | f64 = 0.5 | How long it is held, in seconds. |
gain | f64 = 0.5 | How loud it is. |
wave | int = 0 | Which waveform plays it. |
pan | f64 = 0.5 | Where it sits between the speakers, 0 left to 1 right. |
import audio
import audio.music
import audio.synth
func main:
mut freqs := music.DastgahFreqs(57, music.DastgahShur)
ch := synth.Chord(freqs, 0.05, 22050, synth.WaveSine)
println ch.frames, audio.Peak(ch) > 0.1, audio.IsClipped(ch)
freqs.Free()
wn := synth.NoiseWhite(0.05, 22050)
pn := synth.NoisePink(0.05, 22050)
bn := synth.NoiseBrown(0.05, 22050)
println audio.RMS(wn) > 0.3, audio.RMS(pn) > 0.01, audio.RMS(bn) > 0.001
fm := synth.FMTone(220.0, 2.0, 3.0, 0.05, 22050)
println fm.frames, audio.Peak(fm) > 0.5
add := synth.Additive(220.0, 6, 0.6, 0.05, 22050)
println add.frames, audio.Peak(add) > 0.1
ks := synth.KarplusStrong(220.0, 0.05, 22050, 0.99)
println ks.frames, audio.Peak(ks) > 0.1
one := synth.NoteAt(60, 0.0, 0.1, 0.4, synth.WaveSine)
println one.note, one.start, one.length, one.gain, one.wave
mut phrase := Vector {} as Vector<synth.Note>
mut scale := music.ScaleNotes(60, music.ScaleMajor, 4)
mut k := 0
until k < scale.Len():
phrase.Push(synth.NoteAt(scale.Get(k), (k as f64) * 0.05, 0.04, 0.4, synth.WaveSine))
k++
end
scale.Free()
e := synth.ADSR { attack = 0.005, decay = 0.01, sustain = 0.6, release = 0.02 }
song := synth.RenderNotes(phrase, 22050, 2, e)
println song.channels, song.frames > 0, audio.Peak(song) > 0.1, audio.IsClipped(song)
phrase.Free()
nothing := synth.RenderNotes(Vector {} as Vector<synth.Note>, 22050, 1, e)
println audio.IsEmpty(nothing)
mut a := ch
audio.Free(a)
mut b := wn
audio.Free(b)
mut c := pn
audio.Free(c)
mut d := bn
audio.Free(d)
mut f := fm
audio.Free(f)
mut g := add
audio.Free(g)
mut h := ks
audio.Free(h)
mut i := song
audio.Free(i)
endConstants and variables
Waveform numbers Wave…
| Name | Value |
|---|---|
WaveSine | 0 |
WaveSquare | 1 |
WaveSaw | 2 |
WaveTriangle | 3 |
WaveNoise | 4 |
WavePulse | 5 |
The example for this item is shown with the ones above: synth-Osc.salam
Functions
NewOsc
func NewOsc(wave: int, freq: f64, rate: int): OscThe example for this item is shown with the ones above: synth-Osc.salam
OscNext
func OscNext(o &: Osc): f64The example for this item is shown with the ones above: synth-Osc.salam
WaveValue
func WaveValue(wave: int, phase: f64, duty: f64): f64The example for this item is shown with the ones above: synth-Osc.salam
ADSRAt
func ADSRAt(e: ADSR, t: f64, held: f64): f64The example for this item is shown with the ones above: synth-Osc.salam
ADSRTotal
func ADSRTotal(e: ADSR, held: f64): f64The example for this item is shown with the ones above: synth-Osc.salam
Tone
func Tone(freq: f64, seconds: f64, rate: int, wave: int): audio.ClipThe example for this item is shown with the ones above: synth-Osc.salam
ToneEnvelope
func ToneEnvelope(freq: f64, seconds: f64, rate: int, wave: int, e: ADSR, gain: f64): audio.ClipThe example for this item is shown with the ones above: synth-Osc.salam
Chord
func Chord(freqs: Vector<f64>, seconds: f64, rate: int, wave: int): audio.ClipThe example for this item is shown with the ones above: synth-Voice.salam
NoiseWhite
func NoiseWhite(seconds: f64, rate: int): audio.ClipThe example for this item is shown with the ones above: synth-Voice.salam
NoisePink
func NoisePink(seconds: f64, rate: int): audio.ClipThe example for this item is shown with the ones above: synth-Voice.salam
NoiseBrown
func NoiseBrown(seconds: f64, rate: int): audio.ClipThe example for this item is shown with the ones above: synth-Voice.salam
FMTone
func FMTone(carrier: f64, ratio: f64, index: f64, seconds: f64, rate: int): audio.ClipThe example for this item is shown with the ones above: synth-Voice.salam
Additive
func Additive(freq: f64, partials: int, decay: f64, seconds: f64, rate: int): audio.ClipThe example for this item is shown with the ones above: synth-Voice.salam
KarplusStrong
func KarplusStrong(freq: f64, seconds: f64, rate: int, damping: f64): audio.ClipThe example for this item is shown with the ones above: synth-Voice.salam
RenderNotes
func RenderNotes(notes: Vector<Note>, rate: int, channels: int, e: ADSR): audio.ClipThe example for this item is shown with the ones above: synth-Voice.salam
NoteAt
func NoteAt(note: int, start: f64, length: f64, gain: f64, wave: int): NoteThe example for this item is shown with the ones above: synth-Voice.salam