Why does mixer.music.load hang on my OGG file?

SDL_mixer's Vorbis decoder is sensitive to specific stream layouts. Files exported from non-libvorbis encoders (some DAWs) can stall. Re-encode with libvorbis via ffmpeg -c:a libvorbis.

Should I use mixer.music or mixer.Sound?

music streams from disk; Sound loads to memory. For long tracks (background music), music. For short SFX, Sound. Mixing them up explains many 'stalls' — loading a 5-min Sound takes seconds.

Yes, in Pygame 2 with SDL_mixer 2. Confirm with pygame.mixer.get_init() and check the supported formats. .wav is always safe.

Fix: Pygame mixer.music.load Stalls on Vorbis Stream

Quick answer: Re-encode the OGG with libvorbis: ffmpeg -i in.ogg -c:a libvorbis out.ogg. Or convert to .wav for short clips. SDL_mixer’s Vorbis decoder dislikes some non-standard streams.

Game music loads fine on dev machine, hangs on a player’s install. The OGG was exported from a DAW that produced a quirky Vorbis stream.

The Symptom

mixer.music.load returns or blocks indefinitely on certain .ogg files. Other .oggs work. .wav always works.

The Fix

ffmpeg -i music.ogg -c:a libvorbis -q:a 5 music_safe.ogg

libvorbis produces a clean Vorbis I stream that SDL_mixer parses reliably. Quality 5 is medium; raise to 8 for higher quality.

Use Sound for Short Clips

# Short SFX
sfx = pygame.mixer.Sound("hit.wav")
sfx.play()

# Long music
pygame.mixer.music.load("theme.ogg")
pygame.mixer.music.play(loops=-1)

WAV Fallback

If Vorbis keeps misbehaving, ship as .wav. Larger files but guaranteed compatibility. Or compile to FLAC (also widely supported).

Verifying

Replace problematic OGG with re-encoded version. mixer.music.load returns immediately. Music plays.

“Re-encode with libvorbis. Or use WAV. SDL_mixer is happy.”

Related Issues

For mixer channel overflow, see channel overflow. For sprite group order, see draw order.

Clean Vorbis. Clean playback.