Audio Import

Polygon Engine accepts uncompressed PCM WAV files and provides two target paths. Choose the path according to how the sound is used on the PS1.

Path	Best for	Storage and playback
Resident VAG	Sound effects, short voice clips, short loops	Imported to .vag, loaded into SPU RAM, played by an AudioSource
Streaming CD-XA	Background music and other long tracks	Encoded to .xa during build, streamed from CD, played through the global Music API

Supported source WAV files are 8-bit or 16-bit PCM, mono or stereo.

Resident VAG Audio

The importer mixes stereo sources to mono and converts them to PS1 SPU ADPCM.

Setting	Default	Description
Target Sample Rate	22050 Hz	Output rate: 11025, 22050, or 44100 Hz
Loop	false	Encode VAG loop markers
Streaming Music (CD-XA)	false	Switch this source to the streaming path

Lower rates use less SPU RAM. Use 11025 Hz for small effects when the quality is acceptable, 22050 Hz for most effects and voice, and 44100 Hz only when the extra memory is justified.

VAG sample memory is estimated as:

blocks = ceil(sample_count / 28)
spu_bytes = (blocks + 1) * 16

The hardware provides 512 KB of SPU RAM; the default project budget is 491,520 bytes. All resident clips needed by a scene must fit together. The SPU has 24 hardware voices, and Polygon Engine does not silently steal an active voice. Playback returns false and logs Audio: no channel available when no voice is free.

Resident workflow

1. Place the WAV under Assets/Audio/.
2. Select it in the Project panel.
3. Choose the sample rate and loop setting, then select Apply & Import.
4. Add an Audio Source to a GameObject and assign the imported clip.
5. Configure Volume, Loop, and Play On Start, or control it with the Audio Lua API.

Streaming CD-XA Music

Enable Streaming Music (CD-XA) on a WAV intended for a long music track. During a PS1 build, the pipeline resamples it to 37.8 kHz stereo XA, stages it under DATA/X, and registers the source filename stem as its track name. Track lookup is case-insensitive, so Music.Play("TITLE_THEME") and Music.Play("title_theme") address title_theme.wav.

Streaming music does not consume the resident VAG sample budget, but it uses the CD-ROM data path. The current runtime supports:

• up to 8 registered streaming tracks per build,
• one global XA music stream at a time,
• looped or one-shot playback,
• volume control through Lua,
• suspension around scene data loading; resuming restarts the track from its beginning.

Streaming workflow

1. Place the WAV under Assets/Audio/.
2. Enable Streaming Music (CD-XA) in the Inspector.
3. Build the PS1 package; XA encoding happens during staging.
4. Start the track from Lua:

function Start(gameObjectId)
    if not Music.Play("title_theme", true) then
        Log.Print("Could not start title_theme")
    end
end

See the Music Lua API for stop, volume, and playback-state functions.

Build Safety

Source and import-setting hashes are checked before staging. Changed resident WAV files are reimported or blocked if their VAG output is stale. Streaming tracks are encoded from their source WAV during the build, and the build fails if XA encoding fails or more than 8 tracks are enabled.

Use resident VAG for responsive effects and CD-XA for long music. A long looping AudioSource can exhaust SPU RAM even when the same content would fit comfortably as a streamed track.

XA timing and transition limits

On PS1, XA duration and loop bookkeeping use elapsed VBlanks at the selected PAL/NTSC refresh rate, independently of how many game frames render. Scene loads share the CD device with music: the current resume path restarts the track, rather than continuing from a sample-accurate saved position. Test the audible restart when designing scene transitions. Play Mode audio is a desktop preview and does not reproduce physical disc seek timing.