handle9 methods, 10 fields

Audio

A playing audio instance returned by datumhue.audio.synth, sfx and play.

Obtained from: datumhue.audio.synth, datumhue.audio.sfx, datumhue.audio.play, Music:on_end (in its callback)

The examples on this page start from:

lua

local tone = datumhue.audio.synth({
    waveform = "square",
    frequency = 220,
    volume = 0.2,
    looping = true,
})

Fields 10

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.
Example `local theme = datumhue.package:dir():read("sounds/theme.ogg"):audio() local music = datumhue.audio.play(theme, { looping = true }) -- Skip the intro: jump 12 seconds in. music.position = 12`
`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.
Example `local vec2 = datumhue.math.vec2 local drone = datumhue.audio.synth({ waveform = "sawtooth", volume = 0.2, looping = true, at = vec2(200, 0), }) datumhue.on_update(function() -- Circle the ear 200 units out, once every 4 seconds. local a = datumhue.time.now() * math.pi / 2 drone.at = vec2(200 * math.cos(a), 200 * math.sin(a)) end)`
`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.
Example `-- A table adds a filter; the keys left out take their defaults. tone.filter = { cutoff = 800 } -- A later table merges: the cutoff stays, the resonance rises. tone.filter = { resonance = 0.5 } local filter = tone.filter print(filter.kind) --> lowpass print(filter.cutoff, filter.resonance) --> 800.0 0.5 -- nil removes it. tone.filter = nil print(tone.filter) --> nil`

Methods 9

Audio:stop

method

Audio:stop()

Stop playback after a 5 ms fade and release the instance at once.

In the guide: Play sound

Audio:on_end

method

Audio: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.

Example

-- When the first note has been heard ending, play a fifth above it.
local note = { waveform = "triangle", frequency = 440, duration = 0.2 }
local first = datumhue.audio.synth(note)
first:on_end(function()
    note.frequency = 660
    datumhue.audio.synth(note)
end)

In the guide: Play sound

Audio:pause

method

Audio:pause()

Fade out over 5 ms and hold the instance where it is; its own time stops.

Audio:resume

method

Audio:resume()

Fade a paused instance back in over 5 ms from where it was held.

Audio:release

method

Audio: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.

Example

local note = datumhue.audio.synth({
    waveform = "sawtooth",
    frequency = 330,
    looping = true,
    envelope = { attack = 0.02, release = 0.5 },
})
datumhue.time.after(1, function()
    -- Let go: the note falls to silence over its 0.5 s release.
    note:release()
    -- With no envelope, give the fall's length in seconds.
    tone:release(1)
end)

In the guide: Play sound

Audio:volume_to

method

Audio: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.

Example

-- Fade to a quarter of the volume over 3 seconds; it keeps playing.
tone:volume_to(0.05, 3)

In the guide: Play sound

Audio:pan_to

method

Audio: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.

Example

-- Sweep the tone from the left ear to the right over 4 seconds.
tone.pan = -1
tone:pan_to(1, 4)

In the guide: Play sound

Audio:pitch_to

method

Audio: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.

Example

-- Glide an octave up over 2 seconds; speed rises with the pitch.
tone:pitch_to(2, 2)

In the guide: Play sound

Audio:duty_to

method

Audio: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.

Example

-- A pulse-width sweep: narrow the square to a tenth over 2 seconds.
tone:duty_to(0.1, 2)

In the guide: Play sound Make music

`/` or `Ctrl` `K`	Search
`↑` `↓` `Enter`	Pick a result
`Tab`	Next result filter
`j` `k`	Next or previous entry
`[` `]`	Previous or next page
`y`	Copy a link to the current entry
`?`	These shortcuts
`Esc`	Close

Audio

Fields 10

Methods 9

Audio:stop

Audio:on_end

Audio:pause

Audio:resume

Audio:release

Audio:volume_to

Audio:pan_to

Audio:pitch_to

Audio:duty_to

Try

Recently viewed

Settings

Keyboard shortcuts

On this page