Luawe All pages

Sound and music

A script can play sounds, change how high they are, and listen to them: how strong their low, middle and high sounds are right now, and how loud they are. The same goes for the level's song, which a script reaches as music. Listening is what a music visualizer is made of: bars, shapes or colors that move with the song.

Playing sounds, looping them and their filters are on the page Things, the character and the camera. This page is about pitch and about listening.

Pitch

pitch says how many times higher a sound is: 1 as it is, 2 an octave up, 0.5 an octave down (from 0.25 to 4). How the pitch moves is the sound's pitchMode, an item of cat.PitchMode:

  • cat.PitchMode.changeSpeed (the default): higher is quicker and lower is slower, like a tape played faster or slower. A sound at pitch 2 lasts half as long.
  • cat.PitchMode.keepSpeed: higher or lower, but just as long. A footstep can go up and down without hurrying.
sound.play("@coin", { pitch = 2 })                                     -- higher and quicker
sound.play("@coin", { pitch = 2, pitchMode = cat.PitchMode.keepSpeed }) -- higher, just as long

local hum = sound.loop("assets/hum.wav", { pitchMode = cat.PitchMode.keepSpeed })
hum.pitch = 0.75                           -- lower, at the same speed
hum.pitchMode = cat.PitchMode.changeSpeed  -- now lower and slower

A sound whose speed is kept starts a tiny moment later, about four hundredths of a second, because the game works on it in short pieces to move its pitch.

The song has a pitch too, music.pitch, and it always keeps its speed: the level stays in time with the song whatever its pitch. It can be keyed in the editor (Level > Music), set by a Set property node and tweened like the song's volume:

music.pitch = 0.5                              -- an octave down, at the same speed
camera:tween({ ["music.pitch"] = 1 }, beats(4)) -- back up over four beats

Listening: the spectrum

music:spectrum() gives what the song sounds like right now as a list of numbers, its bands. Band 1 is the lowest sounds (the boom of a kick drum, a bass), the last band the highest (hi-hats, the hiss of cymbals), and the ones between go up step by step, the way ears hear pitch. Each is a number from 0 (nothing there) to 1 (as loud as a sound can be).

local bands = music:spectrum(8) -- 8 bands; 16 when you don't say, 64 at most
print(#bands)                    -- 8
print(bands[1])                  -- the low end: high when the drums hit

music:loudness() is how loud the song is in all, from 0 (silent) to 1. It is not the same as music.volume: the volume is how loud the level makes the song, the loudness is how loud the song is at this moment.

if music:loudness() > 0.8 then
    camera:effect(cat.CameraEffect.pulse, 0.3, 0.2)
end

What they give is what is heard: the song as its pitch, its volume and its low-pass and high-pass have it at that moment. A song turned an octave up has its bands one octave higher; at volume 0 all of them are 0. The numbers are smoothed a little, so that they rise at once and fall back gently instead of flickering.

A looped sound can be listened to in the same way: playing:spectrum(bands) and playing:loudness(). Once it has stopped, they give zeros.

local rain = sound.loop("assets/rain.mp3")
print(rain:spectrum(4)[4], rain:loudness())

When the numbers are there. The game goes through the song in the background once, as the level starts, when anything in the level reads its spectrum: a script, or a node's sum. It takes a moment, and until then the numbers are 0. A sound is gone through the first time a script asks for it. After that, reading them costs next to nothing, as often as you like, and they are the same every time the level is played: in a test play, from a checkpoint, at the editor's playhead.

Nodes can listen too

A node's sum can read the same numbers: spectrum(1, 8) is band 1 of 8, and loudness() how loud the song is. They give exactly what music:spectrum(8)[1] and music:loudness() give in a script, so a node and a script that do the same thing look the same.

A music visualizer

The example "A music visualizer" (in the editor's Scripts side, and its twin in the nodes' examples) puts eight bars behind the level and makes them move with the song. The bars are in a group, Visualizer, which goes along with the camera, colors them with its Gradient (warm at the low end, cool at the high end) and mixes them with the background by Multiply, its Blend mode: they darken what is behind them in their colors, like tinted glass.

local visualizer = things.find("Visualizer")
local bars = visualizer:inside() -- the eight bars, from left to right

level.step:connect(function()
    local bands = music:spectrum(8)
    for i, bar in bars do
        bar.height = 0.5 + bands[i] * 6 -- each bar as tall as its band
    end
    visualizer.alpha = music:loudness() -- the louder, the more they show
end)

level.step happens many times a beat, each time the nodes are worked out, so the bars change exactly when the nodes' would. Change the numbers to try other looks: more bands and thinner bars, bands[i] * 9 for taller ones, or a color for each bar from a gradient: bar.color = colors:colorAt(bands[i]).