Downbeat: Rhythm Game Kit with Beat Clock, Note Highways and Timing Judgement
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.