Log inGet started
Package

downbeat.package

Newest version

README.md

synth

downbeat.synth is a small song synthesizer for authoring time. It renders a whole song from a pattern description to a stereo f32 buffer, and it returns the exact event list (every drum hit, bass, arp, pad and lead note with its beat and time) so rhythm charts can be generated from what the music really plays. It is pure DSP and deterministic: the same song table always gives the same samples, and no engine service is called. Gameplay code never requires it; the downbeat kit uses it from tools/makeNeonDrive.luau to bake the sample song Neon Drive, the calibration click track and the hit sounds.

Voices: punchy kick (pitch-drop sine, click, saturation), snare, clap, closed/open hats (808-style metallic squares + noise), ride, crash, tom, impact boom and noise riser; a bass (two detuned polyBLEP saws + sub, resonant filter envelope), a chord pad (three detuned saws per tone, slow attack, sidechain pump from the kicks), an arp (pulse + saw, snappy filter envelope, ping-pong delay send) and a lead (detuned saw pair as a stereo chorus, square an octave down, glide, delayed vibrato, filter envelope, optional octave double). Master: dotted-eighth ping-pong delay, 4-line FDN reverb, a lookahead limiter and loudness normalisation to a target RMS.

API

local Synth = require("downbeat.synth")

local seq = Synth.sequence(song)             -- events only (fast, no audio)
local out = Synth.render(song, {             -- events + audio
    yield = function() task.wait() end,      -- optional: give frames back while rendering
    slice = 0.03,                            -- seconds of work between yields
    raw = false,                             -- true: skip limiter / loudness (stems)
})
-- out.pcm          interleaved stereo f32 buffer (frames * 8 bytes)
-- out.frames, out.sampleRate, out.channels (2), out.duration (s)
-- out.events       sorted list, see below
-- out.sections     { name, index, startBar, bars, startBeat, endBeat, startTime, endTime }
-- out.totalBeats, out.bpm, out.offset, out.spb (seconds per beat)
-- out.stats        { peak, peakDb, rmsDb, drive }

asset.create("soundClip", "mySong", { pcm = out.pcm, sampleRate = out.sampleRate, channels = 2,
    settings = { codec = "opus", bitrateKbps = 128 } })

Every event: { beat, time, sample (after render), len (beats), kind, voice, midi?, notes?, vel, cutoff, accent?, step?, chord?, section, sectionIndex, bar } where kind is drum (kick, snare, clap, hat, ohat, crash, ride, tom), bass, arp, pad (with notes = the voicing and root), lead or fx (impact, riser). time = offset + beat * 60 / bpm and the voice starts on sample round(time * sampleRate).

Helpers: Synth.midi("C#5") -> 73, Synth.freq(midi), Synth.chord("Am7"), Synth.chordTones(chord, lowMidi), Synth.voicing(chord, lowMidi), Synth.parseMelody(text), Synth.filter(events, kind?, voice?), Synth.noise(seed), and Synth.oneShot(voice, sampleRate?, params?, gain?) -> (monoBuffer, frames) to render one voice alone (kick, snare, clap, hat, ohat, crash, impact, tom, taikoDon, taikoKa, tick, thud, woodblock with { accent = true }), attack on sample 0. Synth.voices holds the voice constructors; Synth.DEFAULT_MIX, DEFAULT_SENDS ({ reverb, delay }) and DEFAULT_PAN are the defaults a song's mix / sends / pan override per voice.

Song format

{
  bpm = 124, offset = 0.5, beatsPerBar = 4, steps = 16, sampleRate = 48000,
  tail = 3,             -- seconds of ring-out after the last bar
  loudness = -12,       -- target RMS dBFS over the music; ceiling = 0.86 peak
  bassLow = 28, padLow = 55,          -- lowest midi of bass roots / pad voicings
  drums = { name = { kick = "x...x...x...x...", snare = "....X.......X...", hat = "..x...x..." } },
  bassPatterns = { name = "r.r.o.r.r.r.o.f." },      -- r root o octave f fifth t third
                                                     -- F fifth+8va l fifth below, - hold, . rest
  arps = { name = { low = 52, rate = 0.25, steps = "1345134513456543" } },
                                                     -- digits = chord tones upward from `low`
  melodies = { name = "C5!/1 A4/0.5 r/0.5 F5/2" },   -- note/beats, r rest, ! accent
  sections = {
    { name = "verse", bars = 8, chords = { "Am", "F", "C", "G" },   -- one per bar, cycling
      drums = { "verse", "verse", "verse", "fill" },                -- a name, or one per bar
      bass = "drive", arp = "verse", pad = true,                    -- pad = number: level
      lead = "chorus", leadDouble = true, leadLevel = 0.8, leadShift = 0,
      crash = true, impact = true, riser = 4,                       -- riser over the last N beats
      sweep = { 0.3, 1.0 },                                         -- filter multiplier ramp
      level = { 1, 0.8 } },                                         -- velocity ramp
  },
  mix = { kick = 0.85, lead = 0.42 }, sends = { lead = { 0.3, 0.2 } }, pan = { hat = 0.3 },
  -- tone: bassCutoff, bassEnv, bassPump, padCutoff, padAttack, padRelease, padPump,
  --       arpCutoff, arpEnv, arpGate, arpPump, leadCutoff, leadEnv, leadRelease,
  --       delayBeats, delayFeedback, delayReturn, reverbTime, reverbSize, reverbReturn
}

Drum steps: x hit, X accent, g ghost, o medium, . rest; a string longer than one bar spans several bars. tools/neonDriveSong.luau is a complete worked example.

Rendering ~95 s of stereo 48 kHz takes about 7-8 s of CPU; pass yield so the engine keeps drawing frames meanwhile.