Console Sound skill

console-sound

The Sound Designer gets a game's audio out as WAV files you can listen to, and puts your own sounds back in the same format. PS2 audio is Sony's SPU2 ADPCM: 16-byte frames of 28 samples each. It lives in .vag files (a 48-byte VAGp header, then the frames), in sound banks (a .hd header plus a .bd of headerless frames) and in game-specific streams. vag.py decodes exactly the way the PS2Recomp runtime does (ps2xRuntime/src/lib/ps2_audio_vag.cpp), so what you hear is what the port plays.

Honest limits. The port's audio is high level: ps2xRuntime/src/lib/ps2_audio.cpp decodes the VAGp blocks a game transfers and plays them through raylib when the game sends libsd voice commands. It is not a full SPU2, so loop flags, reverb, envelopes and music streamed through a game's own driver may not play in the port yet (that is /console-backend work). Banks have no rate in the .bd; it comes from the .hd or from your ears. Movies (PSS) are out of scope.

${CLAUDE_SKILL_DIR} below is this skill's folder (where this SKILL.md lives).

python3 "${CLAUDE_SKILL_DIR}/vag.py" info  console/disc/SOUND/BGM01.VAG          # rate, length, loop points, header
python3 "${CLAUDE_SKILL_DIR}/vag.py" towav console/disc/SOUND/BGM01.VAG          # -> console/audio/BGM01.wav
python3 "${CLAUDE_SKILL_DIR}/vag.py" scan  console/disc/DATA/SOUND.PAK --extract console/audio/pak
python3 "${CLAUDE_SKILL_DIR}/vag.py" split console/disc/SOUND/SE.BD --rate 22050 --out console/audio/se
python3 "${CLAUDE_SKILL_DIR}/vag.py" towav console/disc/SOUND/STREAM.BIN --rate 48000 --channels 2 --interleave 0x800
python3 "${CLAUDE_SKILL_DIR}/vag.py" fromwav my_song.wav --like console/disc/SOUND/BGM01.VAG --out console/audio/BGM01.VAG

Other flags: --offset N (a VAG or raw data inside a bigger file), --all (decode past end flags), --json. For fromwav: --loop, --loop-start N, --no-loop, --rate N, --mono, --stereo split|interleave --interleave N, --allow-bigger, --exhaustive, --no-lead-frame, --name. Exit codes: 0 ok, 1 needs attention (odd frames, a replacement too big), 2 bad input.

What it reads and writes

file	what
*.vag	VAGp header + ADPCM frames: read by info/towav, written by fromwav
*.bd (+ *.hd)	a sound bank. split cuts the .bd at end flags (a heuristic); the .hd (starts IECSsreV) holds the real list
any big file	scan finds VAGp headers inside it; --extract writes each one out
*.wav	16-bit PCM, mono or stereo, in and out. Loop points travel in a smpl chunk both ways
console/audio/	the default output folder
console/audio/<bank>/split.json	offset, size and loop of every sound split found

Format details, the encoder and what is unverified: reference/vag-format.md. Where audio lives on a PS2 disc and how the port plays it: reference/game-audio.md.

The method

1. Find the audio. Map the extracted disc with /console-levels (datascan.py scan <disc folder> --embedded). Look for kind VAG, IECS (a bank header), MPEG-PS (movies) and big high-entropy data files (streams or archives). Run vag.py scan on archives to find VAGs inside them. datascan.py files <run log> shows which files the port looked up, in order.
2. Rip it. towav for a VAG, scan --extract for VAGs inside a file, split --rate N for a .bd bank. A bank's rate is in its .hd; if you cannot read it, try 22050, then 44100, 32000 and 48000 and pick the one that sounds right. For a raw stereo stream try --channels 2 with interleave sizes such as 0x800, 0x1000 and 0x4000 until it sounds clean. A WARNING ... out-of-range filter or shift means a wrong offset or not ADPCM at all.
3. Make the replacement. Your own recording, or music you have the rights to. Export a 16-bit PCM WAV. Shorter than the original is safest. Set loop points in your audio editor (they go in the WAV's smpl chunk) or pass --loop / --loop-start N.
4. Encode against the original. fromwav mine.wav --like ORIGINAL.VAG --out console/audio/NAME.VAG copies the original's rate (resampling linearly if needed), header version and name, and looping, and refuses if the result is bigger: games often load sounds into fixed slots in the SPU2's 2 MB of sound RAM. Read the quality line: above about 25 dB signal to noise is clean. A loop length that is not a multiple of 28 samples gets a short gap at the loop point; the tool says so.
5. Swap it in. Close the port first. It reads cdrom0:\ from the folder the game's ELF is in (cdRoot, set by PS2Runtime::configureIoPathsFromElf). Copy the original aside first (BGM01.VAG.orig), then copy your file over it with the same name. For a sound inside an archive, use /console-levels unpack, replace the entry, repack. The runtime looks disc files up by name and gives each its real host size, so a new size is fine for files the game finds by name; a game that reads fixed sector numbers needs the exact original size.
6. Playtest. Run the port with /console-tester. If your sound is silent, check whether the original plays in the port. If neither does, the gap is the runtime's audio, not your file: hand it to /console-backend with the table below.
7. Write it down. One line in the session log of console/STATE.md: which file, where the original is backed up, the rate and size.

Where audio fixes go in PS2Recomp

symptom	layer	where
a VAG plays wrong in the port but right in towav	runtime decoder	ps2xRuntime/src/lib/ps2_audio_vag.cpp
no sound at all, game sends libsd commands	runtime audio backend	ps2xRuntime/src/lib/ps2_audio.cpp (PS2AudioBackend::onSoundCommand, libsd SID 0x80000701)
sound RPCs never reach the backend	IOP module HLE	ps2xIOP/src/modules/libsd.cpp
an audio library call logs Unimplemented PS2 stub	kernel stubs	ps2xRuntime/src/lib/Kernel/Stubs/Audio.cpp
your file is right but the game ignores it	data	wrong file swapped, or the sound lives in an archive: /console-levels

Never edit headers or ps2xRuntime/src/runner/ for audio: a header change rebuilds every generated file. Runtime .cpp changes are /console-backend's job.

Guard rails

• Bring your own game. Rip only from discs you own and dumped yourself (ImgBurn on Windows, dd from a DVD drive on macOS or Linux). Never download ISOs, ELFs or BIOS files, never help find them, never ask the user for them. PS2Recomp needs no BIOS.
• Nothing from the game gets published. Ripped music, voices and effects stay on your machine, like the disc, the ELF, the IRX modules and the recompiled C++. Share your own tracks, the steps and patches, never the game's audio or a modified disc.
• Your replacement must be yours. Use music you made or have the rights to use.
• Back up before you swap. Keep the original next to it (.orig) or in console/, and never write over your only copy of a disc file. This tool never writes into the disc folder itself.
• Not affiliated with Sony. PlayStation is a trademark of Sony Interactive Entertainment.

Hands off to

• /console-levels to unpack and repack archives that hold sounds, and to find which files a level loads.
• /console-tester to playtest the swap and check nothing else broke.
• /console-backend when the port itself does not play audio (runtime decoder, audio backend, libsd).
• /console-mod for behaviour changes around sound (a new trigger, a volume change in code).