libgdx/libgdx · error · GdxRuntimeException

PCM WAV files must be 8 or 16-bit:

Error message

PCM WAV files must be 8 or 16-bit: 

What it means

For format tag 0x0001 (integer PCM), WavInputStream only accepts bitDepth of 8 or 16 — the widths the fixed OpenAL PCM path handles. Values such as 24 or 32-bit integer PCM throw with the offending depth printed.

Source

Thrown at backends/gdx-backend-lwjgl3/src/com/badlogic/gdx/backends/lwjgl3/audio/Wav.java:112

				int fmtChunkLength = seekToChunk('f', 'm', 't', ' ');

				// http://www-mmsp.ece.mcgill.ca/Documents/AudioFormats/WAVE/WAVE.html
				// http://soundfile.sapp.org/doc/WaveFormat/
				type = read() & 0xff | (read() & 0xff) << 8;

				if (type == 0x0055) return; // Handle MP3 in constructor instead
				if (type != 0x0001 && type != 0x0003) throw new GdxRuntimeException(
					"WAV files must be PCM, unsupported format: " + getCodecName(type) + " (" + type + ")");

				channels = read() & 0xff | (read() & 0xff) << 8;
				sampleRate = read() & 0xff | (read() & 0xff) << 8 | (read() & 0xff) << 16 | (read() & 0xff) << 24;

				skipFully(6);

				bitDepth = read() & 0xff | (read() & 0xff) << 8;
				if (type == 0x0001) { // PCM
					if (bitDepth != 8 && bitDepth != 16)
						throw new GdxRuntimeException("PCM WAV files must be 8 or 16-bit: " + bitDepth);
				} else if (type == 0x0003) { // Float
					if (bitDepth != 32 && bitDepth != 64)
						throw new GdxRuntimeException("Floating-point WAV files must be 32 or 64-bit: " + bitDepth);
				}

				skipFully(fmtChunkLength - 16);

				dataRemaining = seekToChunk('d', 'a', 't', 'a');
			} catch (Throwable ex) {
				StreamUtils.closeQuietly(this);
				throw new GdxRuntimeException("Error reading WAV file: " + file, ex);
			}
		}

		private int seekToChunk (char c1, char c2, char c3, char c4) throws IOException {
			while (true) {
				boolean found = read() == c1;
				found &= read() == c2;

View on GitHub (pinned to 97f4086187)

Solutions

1. Re-export or convert to 16-bit PCM WAV for shipped assets.
2. If you need >16-bit precision, export as 32-bit FLOAT WAV (format tag 3), which is accepted.
3. For 24-bit masters: dither down to 16-bit in your audio tool, not by renaming.

Example fix

// before: 24-bit PCM export throws
// after: ffmpeg -i in24.wav -c:a pcm_s16le in16.wav
Sound s = Gdx.audio.newSound(Gdx.files.internal("in16.wav"));

if (fmtTag == 1 && bitsPerSample != 8 && bitsPerSample != 16)
    throw new IllegalArgumentException("PCM WAV must be 8/16-bit, got " + bitsPerSample);

When it happens

Trigger: Loading a PCM WAV with 24-bit samples (very common studio default) or 32-bit integer samples; the check happens right after reading the 2-byte bits-per-sample field of the fmt chunk.

Common situations: Pro Tools/Ableton/Reaper default exports at 24-bit; libraries handing 32-bit int PCM; users assuming '32' works because float32 WAVs do (tag 3 is a different branch).

Related errors

• WAV files must be 8 or 16-bit PCM: {}
• Audio: Bit depth must be 8, 16, 32 or 64.
• WAV files must be PCM, unsupported format:
• Floating-point WAV files must be 32 or 64-bit:
• WAV files must be PCM, unsupported format: {} ({})

AI-assisted analysis of libgdx/libgdx@97f4086187 (2026-08-14). Data as JSON: /api/errors/484c856eae822c7d. Report an issue: GitHub.