A short guide for anyone putting original music into a Defold game and wondering why the loop never quite sounds like the track.

Defold makes looping easy. Put a sound component on a game object, tick Looping, play it, and the music repeats for as long as you want.

What it repeats is the whole file, first sample to last. That one detail is why your reverb keeps getting chopped off, and once you know it, the fix is simple.

How Defold loops a sound

A sound component holds one audio file, with properties for Sound, Looping, Loopcount, Group, Gain, Pan and Speed. Tick Looping and it plays Loopcount times, or forever when Loopcount is 0, which is what you want for music. Starting it is one line:

sound.play("#music")

and sound.stop("#music") stops it. You can pass a delay, a gain, a pan or a speed to that one playback if you need to.

There are no loop points in that list. Defold doesn’t read loop markers out of a WAV or an OGG, so there’s no way to tell it “play the first eight seconds once, then repeat the rest”. Looping means the whole file. Several other engines do read loop points embedded in the file, and Defold is the other kind, which shapes everything below.

What it does do, it does accurately. Testing in Defold 1.14.0, a file prepared to loop on its own started exactly on its first sample and came back around on the sample it should, every pass, recorded from the game’s own output. There’s no gap and no drift to design around. The seam is as good as the file you hand it.

Why the tail is the hard part

Most music keeps sounding after the last bar of the loop. Reverb, a delay repeat, a final note ringing out. That’s the tail, and a whole-file loop leaves you two bad choices.

Cut the file at the loop end and the tail is gone. Every time the music wraps, the reverb stops dead and the next pass starts dry. On an orchestral or ambient cue that ends up being the thing you notice most.

Leave the ring-out on the end of the file and Defold plays it, because as far as Defold is concerned it’s part of the loop. Now every pass runs long by the length of the tail, the restart lands late, and the groove falls apart.

There’s no setting that lets the tail ring over the restart, because one sound component has one playhead. So the fix has to happen in the audio file.

Fold the tail into the start of the loop

Take the ring-out that sounds after the loop end, mix it into the opening of the loop, and cut the file so it ends exactly at the loop end. Now the audio at the start of the file already carries the tail, and when Defold jumps back, the reverb is simply there. This is called a folded tail, and a whole-file engine is exactly what it’s for.

It has one cost worth knowing. The first pass carries that folded-in tail at its start too, before anything has actually rung out. In an engine that can play a lead-in once you can hide it behind that lead-in. In Defold you can’t, because the lead-in would come back every pass. Most of the time it just sounds like the music starting in a room with the reverb already up, but listen to it and decide for yourself.

The tail also has to exist in the render. Nothing can add a reverb or a delay that was never there, so render the track with the tail ringing out past the loop end, and keep that audio.

Leave the lead-in out

Since Defold repeats the whole file, anything in front of the loop comes back every time. So a one-time intro doesn’t belong in the looping file. Export the loop on its own.

If a cue really needs a lead-in, that’s a second sound played first with the loop started after it, and the handoff between the two is your code’s problem. I haven’t measured how tightly that lands in Defold, so I’m not going to tell you it’s seamless.

Use 16-bit WAV or Ogg Vorbis

Defold plays Wave, Ogg Vorbis and Ogg Opus, and its Wave support is 8-bit and 16-bit PCM. That last part catches people out. Hand Defold a 24-bit WAV, which is what most of us render out of a DAW, and the project builds, the sound plays, and you hear nothing at all. The only clue is a line in Defold’s console saying it only takes 8 or 16 bit PCM. If your music is silent in the game and fine everywhere else, check the bit depth before you check anything else.

So 16-bit WAV or Ogg Vorbis. Both looped correctly for me in Defold 1.14.0. Opus plays too, but it’s not in the engine by default (you turn its decoder on in the app manifest) and I haven’t tested a loop in it.

One nice thing about Defold is that it leaves your audio alone. The bytes in the build came out identical to the file I exported, so there’s no import step re-encoding your music and moving the loop point behind your back. The file you deliver is the file that plays.

The smaller things that bite

If the file’s sample rate doesn’t match the sound device’s, Defold resamples it. A 48 kHz file on a 44.1 kHz device ran a hair slow, about 0.005%, and that was spread evenly across the pass instead of bunching up at the loop, so the seam still sounded smooth. It just isn’t sample-exact any more, and since you can’t choose the sound device a player has, that’s worth knowing rather than worth fighting.

A centred stereo sound plays about 3 dB below the file, which is Defold’s pan law. It’s consistent, so there’s nothing to fix, but it’s worth knowing before you decide the music came out too quiet. Set your levels by ear in the game rather than against the file.

Each call to sound.play starts another copy, so if that call can run twice you’ll get two copies of the music stacked on top of each other. Guard it. And a sound carries on playing even if its game object is deleted, so stop it on purpose.

Stopping the music

Defold’s docs list gain, pan and speed as the properties you can read and change while a sound is playing. Looping isn’t one of them, so there’s no “let this pass finish and then play the ending” the way a couple of other engines have. The clean way out of a looping cue in Defold is to bring the gain down over a second or two and then stop the sound.

How Loopsmith makes this easier

This is the part I built Loopsmith to take off your plate. You finish the music, and it does the setup.

  • If you’re the composer, you don’t need to know any of this. You hand over one file, and it loops on a plain sound component with nothing else to set up.
  • The tail is folded for you, out of your own render. Choose Single file: folded tail and export as 16-bit WAV or Ogg Vorbis with Intro unticked, and the file comes out cut to exactly the loop length with the ring-out already blended into its start. Defold isn’t in Set up for, so the button stays Export loop.
  • It’s tested there. From 1.22.0, that export loops sample-exactly on a Defold sound component with Looping ticked, measured in Defold 1.14.0 by recording the game’s own output, and Loopsmith’s manual tells your developer the same thing, including the 24-bit WAV trap.
  • You hear it the way the game will play it, before it’s in Defold. The restart with the tail ringing over it, and a check that flags a click, a loudness jump or a sound getting cut off at the loop point.

The demo is the full app with three free tracks you can export as often as you like, which is enough to hear one of your own tracks looping in your own Defold project tonight. It’s Windows, and it costs nothing to find out.

If you also work in GameMaker or Ren’Py, both can play a lead-in once and then loop, and each has its own guide. The full map of which engine reads what is in How Game Engines Handle Loop Points in Audio Files.

Austin Haynes is a composer for games, including Cognition: An Erica Reed Thriller (AdventureGamers Best Music of 2013) and The Silver Lining. If your project needs music, you can hear his work at austinhaynesmusic.com.