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 Encoding

Use .wav files with a RIFF/WAVE header and uncompressed integer PCM (format tag 1), either 8-bit or 16-bit, mono or stereo. The source sample rate is converted to the selected output rate during import or build.

24-bit/32-bit PCM, floating-point WAV, compressed WAV, and WAVE_FORMAT_EXTENSIBLE are not accepted. MP3, OGG, FLAC, AAC, and AIFF also need conversion. A reliable export choice is 16-bit PCM WAV at 22,050 or 44,100 Hz; do not just rename the extension.

Use the WAV source for both sound effects and music; .vag and .xa are generated outputs, not replacements for the source import workflow. See Supported File Formats.

If import fails, select the WAV and read the Inspector or Console error. Correct the encoding, choose a supported Target Sample Rate, or resolve the reported file-access problem, then select Reimport. Apply & Import uses the settings currently shown in the Inspector. A failed reimport may leave the previous working clip available; that does not mean the replacement was accepted.

Listening in the Inspector

Use Play Preview to hear the source WAV and Stop Preview to stop and rewind it. Click or drag on the waveform to choose a playback position. A finished preview can be played again from the beginning.

This is a desktop source preview: it does not reproduce VAG/XA compression or physical CD seek delays. Check the exported game to judge the final audio. If preview playback fails, read the status bar and Console, check that the WAV still exists, and confirm that Windows has an available audio output device.

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.

The scene also has a hard limit of 16 unique resident clips. That is separate from the 24 simultaneous voices and the SPU memory budget. The memory warning begins at 70% of the configured SPU bytes, not at 70% of clip slots. See Audio budget warnings.

For a short sound that should repeat, enable Loop in the WAV import settings, select Apply & Import, and enable Loop on its Audio Source. The import setting encodes the loop markers; the component setting chooses whether this source repeats. For one-shot playback, leave the component's Loop disabled. Check the clip's start and end in the exported game for audible clicks or gaps. After changing import settings, rebuild the disc so the game uses the new audio data.

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 and select Apply & Import.
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

Use Music.Play in both Play Mode and the exported game; no Audio Source component is needed. An Audio Source assigned to the same WAV still uses resident VAG playback and can exceed the SPU budget.

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.

Memory Card saves and loads also pause CD-XA playback. The track restarts when the operation finishes; account for this audible interruption when designing save points. Resident sound effects do not require CD-XA streaming.