Libgdx Audio Lifecycle

libGDX Audio

Quick reference for libGDX audio APIs. Covers Sound, Music, platform gotchas, and common audio patterns.

Audio: Sound vs Music

| | Sound | Music | |---|---|---| | Loading | Fully into memory | Streamed from disk | | Use for | Short effects ( { // Called when music finishes playing });

bgm.dispose(); // MUST call when done

In non-trivial projects, prefer loading audio via `AssetManager` rather than raw `Gdx.audio.newMusic()`. AssetManager handles disposal via `unload()` and supports async loading.

**Gotchas:**
- **OnCompletionListener does NOT fire when looping is true.** If you need looping + completion callback, set looping=false and restart in the listener.
- libGDX **automatically pauses/resumes Music** on Android pause/resume. You do NOT need to manually pause music in `ApplicationListener.pause()`. Doing so is redundant.
- Only one OnCompletionListener per Music instance (last set wins).
- `setPosition()` is unreliable on some Android devices for MP3 — seeking uses bitrate estimation and can be off by several seconds. OGG seeking is more accurate, but OGG is unsupported on iOS. For cross-platform seeking accuracy, consider WAV (large files) or accept MP3 imprecision.

## Common Patterns

### Shared Music Across Screens

Store Music in the Game class, not in individual Screens. Dispose only in `Game.dispose()`.

```java
public class MyGame extends Game {
    public Music bgm;

    @Override
    public void create() {
        bgm = Gdx.audio.newMusic(Gdx.files.internal("theme.mp3")); // use MP3 for iOS compatibility
        bgm.setLooping(true);
        bgm.play();
        setScreen(new MenuScreen(this));
    }

    @Override
    public void dispose() {
        bgm.dispose();
        getScreen().dispose();
    }
}

Platform Differences

| Behavior | Desktop (LWJGL3) | Android | iOS (RoboVM) | |---|---|---|---| | OGG support | Yes | Yes | No | | Music auto-pause | On minimize only | Yes | Yes | | Sound size limit | None | <1MB PCM | None | | MP3 seeking accuracy | Good | Unreliable | Good |

Common Mistakes

1. Manually pausing Music in pause() — libGDX does this automatically. Redundant code confuses readers.
2. Using Sound for long audio — Sound loads entirely into memory. Use Music for anything over a few seconds.
3. Expecting OnCompletionListener with looping — It won't fire. Use looping=false + manual restart.
4. Using OGG on iOS — Will fail silently or crash. Use WAV/MP3.
5. Playing Sound in create() on Android — Audio system may not be ready. Defer to first render() frame.
6. Relying on Music.setPosition() accuracy with MP3 on Android — Seeking can be off by seconds. Use OGG for accuracy (but not on iOS).
7. Checking Sound.play() return value for failure detection — Behavior is backend-dependent. Don't rely on it.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kyu-n
• Source: kyu-n/gdx-claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.