Music:stop
methodMusic:stop()Stop playback after a 5 ms fade and release the instance at once.
handle13 methods, 13 fieldsUI apps only
Music
A playing datumhue.audio.music: every Audio member, plus live edits and the step heard now.
- Obtained from
datumhue.audio.music
The examples on this page start from:
lua
local hi = { waveform = "square", frequency = 880, duration = 0.25 }
local lo = { waveform = "square", frequency = 440, duration = 0.25 }
local song = datumhue.audio.music({
patterns = { { hi, lo, lo, lo }, { lo, lo, hi, hi } },
sequence = { 1, 2 },
looping = true,
})Fields 13
| Field | Type | Access | Description |
|---|---|---|---|
position | number? | read/write | Seconds of the sound's own time, as heard: source seconds for a clip, written seconds for a synth, sfx or music (pitch and tempo speed it up). Wraps at each loop pass, follows seek, and before a future start_time reads where the sound will start; nil once the instance is gone. Assigning it on a clip's play jumps there after a 5 ms fade (at once before the sound has started), clamped to the clip, and reads back at once; on a synth, sfx or music it raises. |
at | Vec2? | read/write | Where a sound played with at stands, in the units of its ear. An assignment moves it: its pan and distance gain follow, gliding like volume, so a sound assigned a new place each frame moves smoothly. nil on any other sound, where assigning raises, and once the instance is gone. |
playing | boolean | read-only | true from the call until the sound has ended (as heard), except while paused; false once stopped. |
volume | number? | read/write | The instance's own linear gain, clamped to 0..4; the audible volume is master x bus x instance. An assignment reads back at once and glides over 50 ms (or the device period, if longer) from the level sounding; nil once the instance is gone. |
pan | number? | read/write | Stereo position, clamped to -1 (left) .. 1 (right), constant power with the centre at the sound's own level; a sequence's per-note pans add to it. An assignment reads back at once and glides like volume; nil once the instance is gone. On a sound played with at it reads the pan its position gives, and assigning it raises. |
level | number? | read-only | The RMS of what the instance played over the last 1024 frames heard (about 21 ms at 48 kHz), linear, after its own volume and pan; nil once the instance is gone. |
peak | number? | read-only | The largest absolute sample the instance played over the same span as level; nil once the instance is gone. |
pitch | number? | read/write | Playback rate, clamped to 0.25..4: the sound plays as if resampled, so rate and pitch move together (2.0 plays an octave up at double speed), and so do its notes, envelope, muffle, space and duty sweeps; its filter keeps its cutoff in heard Hz. Steps at once with no click; nil once the instance is gone. |
duty | number? | read/write | A square synth's pulse width, clamped to 0..1; it steps at once, taking effect at the next cycle. Reads nil on any other voice, where assigning raises. |
filter | AudioFilter? | read/write | The voice's filter, or nil with none. Assigning a table merges into it (creating it, with its required keys, when there is none); assigning nil removes it with a 20 ms crossfade. |
step | integer? | read-only | The 1-based step of the slot's first track heard now, to about one device period; nil before the first step and after the end. |
slot | integer? | read-only | The 1-based sequence entry heard now; nil before the first step and after the end. |
tempo | number? | read/write | Playback speed of the written durations, clamped to 0.25..4 (2 plays twice as fast), for every track; pitch is unchanged and envelope, vibrato and arpeggio times keep their seconds. Steps at once. |
Methods 13
Music:on_end
methodMusic:on_end(callback?: fun(audio: Audio))Set, replace, or clear (pass nil) the callback run once when the sound is heard ending: it played out, was released or was stolen, or its clip failed to load. It does not run after stop(), after its bus's remove() or once the app has ended.
Music:pause
methodMusic:pause()Fade out over 5 ms and hold the instance where it is; its own time stops.
Music:resume
methodMusic:resume()Fade a paused instance back in over 5 ms from where it was held.
Music:release
methodMusic:release(seconds?: number)Start no further notes: the sounding note falls from its current level over its envelope's release, or over seconds of the sound's own time (5 ms with no envelope), then the instance ends after any space tail. A seconds of 0 or less falls over 2 ms. Called again with seconds, the fall restarts from the current level; without, it changes nothing. A paused instance ends at once; a clip fades out, then ends.
Music:volume_to
methodMusic:volume_to(volume: number, seconds: number)Ramp the instance gain linearly to volume (clamped to 0..4) over seconds of played sound, from the value sounding; the sound keeps playing. Assigning volume cancels the ramp, and a seconds of 0 or less is an assignment.
Music:pan_to
methodMusic:pan_to(pan: number, seconds: number)Ramp the stereo position linearly to pan (clamped to -1..1) over seconds of played sound, sample-exact; assigning pan cancels the ramp, and a seconds of 0 or less is an assignment. On a sound played with at it raises: its position pans it.
Music:pitch_to
methodMusic:pitch_to(pitch: number, seconds: number)Ramp the playback rate to pitch (clamped to 0.25..4) in equal ratios, so each octave takes the same time, over seconds of played sound, sample-exact; assigning pitch cancels the ramp, and a seconds of 0 or less applies it at once.
Music:duty_to
methodMusic:duty_to(duty: number, seconds: number)Ramp a square synth's pulse width linearly to duty (clamped to 0..1) over seconds of the sound's own time, so pitch speeds it up; any other voice raises. Assigning duty cancels the ramp, and a seconds of 0 or less applies it at once.
Music:set_pattern
methodMusic:set_pattern(index: integer, notes: audio.SfxNote[])Replace pattern index (1-based; #patterns + 1 appends). Every slot and track playing it switches at the current time: notes starting from now play, the sounding note finishes, and no note starts part-way; nothing restarts. An index outside 1..#patterns + 1 raises.
-- Rewrite pattern 2 while the song plays; nothing restarts.
song:set_pattern(2, { hi, hi, lo, lo })
-- One past the last pattern adds a new one.
song:set_pattern(3, { lo, hi, lo, hi })notes audio.SfxNote options 16 keys
| Key | Type | Default | Description |
|---|---|---|---|
| waveform required | "sine" | "square" | "triangle" | "sawtooth" | "noise" | Wavetable | no default | Oscillator waveform for this note: a named shape or a Wavetable. |
| frequency | number | 440 | Tone frequency in Hz. |
| duration | number | 0.1 | Note duration in seconds, at least 0.001: the note's gate. |
| volume | number | 1 | Linear volume for this note, at most 4 (clamped); 0 is a rest, which lets the previous note's release ring on. |
| slide | number | the pitch holds | Target frequency in Hz to glide toward over the note. |
| vibrato | audio.Vibrato | no vibrato | Pitch vibrato parameters. |
| arpeggio | number[] | no arpeggio | Semitone offsets cycled per arpeggio step; an empty list is no arpeggio. |
| arpeggio_ticks | number | 1; giving it without arpeggio raises | 1/60 s ticks per arpeggio step, fractions allowed. |
| envelope | audio.Envelope | 2 ms edges | The note's volume envelope. |
| pan | number | 0 | Stereo position, -1 (left) .. 1 (right), added to the play's pan and clamped. |
| duty | number | 0.5; giving it for any waveform but square raises | Pulse width 0..1, clamped. |
| duty_slide | number | the duty holds; giving it for any waveform but square raises | Target pulse width of a linear sweep across the note. |
| noise_mode | "white" | "long" | "periodic" | white noise; giving it for any waveform but noise raises | The noise generator. |
| sync | number | no sync | Hard sync: the cycle runs at this ratio of frequency and restarts at each cycle of frequency. |
| sync_slide | number | the sync ratio holds; giving it without sync raises | Target sync ratio of a linear sweep across the note. |
| ring | number | no ring modulation | Ring modulation by a ±1 square at this ratio of frequency. |
In the guide: Make music
Music:set_sequence
methodMusic:set_sequence(sequence: (integer | integer[])[])Play sequence after the current slot: the slot playing finishes, then entry slot + 1 of the new order plays; past its end the music wraps to entry 1 when looping and ends otherwise. Validated as MusicOptions.sequence is.
-- A new order: pattern 1, then patterns 1 and 2 together as tracks.
-- The entry playing finishes, then the new order goes on from the
-- entry after it.
song:set_sequence({ 1, { 1, 2 } })In the guide: Make music
Music:seek
methodMusic:seek(slot: integer, step?: integer)After a 5 ms fade, jump to step (1-based) of slot (1-based) in the newest order; notes already under way there sound from where they would be. step and slot read back at once, and on_step fires once for the target. A position outside the sequence raises.
-- Jump to step 3 of the second entry; both read back at once.
song:seek(2, 3)
print(song.slot, song.step) --> 2 3In the guide: Make music
Music:on_step
methodMusic:on_step(callback?: fun(music: Music, slot: integer, step: integer))Set, replace, or clear (pass nil) the callback fired as each step is heard, with the music and the 1-based slot and step. Fires that wait fold into one carrying the latest step, as timers do.
In the guide: Make music