← Back to Home

Getting Started with SPA

Learn how to create and play procedural audio with SPA in just a few steps

1

Install the Packages

Choose your platform and install the SPA packages. All packages are lightweight and have zero dependencies.

Install React package

npm install @spa-audio/react

Components:

import { SPAButton, SPAPlayer } from '@spa-audio/react';

// Button with sound
<SPAButton src="/sounds/click.spa">
  Click Me
</SPAButton>

// Inline SPA
<SPAButton spa='<spa><tone wave="sine" freq="800" dur="0.05"/></spa>'>
  Play
</SPAButton>

// Full player
<SPAPlayer src="/sounds/music.spa" />

Hook for custom usage:

import { useSPA } from '@spa-audio/react';

const { play, stop, loading } = useSPA('/sound.spa');

// Trigger playback
<button onClick={play}>Play</button>
2

Generate with AI

SPA was designed to be AI-friendly. LLMs can easily generate valid SPA files because the format is declarative XML with clear parameters.

How to Generate SPA with AI

1.Copy the prompt template below
2.Paste it into your favorite AI (ChatGPT, Claude, etc.)
3.Add your sound description at the end

AI Prompt Template

This comprehensive prompt includes:

  • Complete SPA documentation and specification
  • All core elements: tone, noise, group, sequence
  • ADSR envelopes, filters, and parameter automation
  • Sound design patterns for UI, games, and music
  • Working examples with explanations
  • Expert instructions for generating valid SPA files

Example Descriptions to Try

  • • "A retro 8-bit coin collection sound"
  • • "A soft notification chime with 3 harmonious tones"
  • • "A laser gun sound effect for a sci-fi game"
  • • "A gentle wave crashing sound using filtered noise"
  • • "An error sound that's not too harsh"
3

Learn the Format

Understand how to construct SPA files from basic building blocks. Every sound starts with these fundamentals.

Basic Structure

Every SPA file follows this structure:

<?xml version="1.0" encoding="UTF-8"?>
<spa xmlns="https://spa.audio/ns" version="1.0">
  <!-- Your sound elements go here -->
  <tone wave="sine" freq="440" dur="1" />
</spa>

Core Elements

<tone> - Oscillator sounds

Create pure tones with different waveforms

<tone wave="sine" freq="440" dur="1" amp="0.5" />

<noise> - Noise generators

Generate different colors of noise

<noise color="white" dur="0.5" amp="0.3" />

<group> - Layer sounds

Play multiple sounds simultaneously

<group>
  <tone wave="sine" freq="261.63" dur="1" /> <!-- C -->
  <tone wave="sine" freq="329.63" dur="1" /> <!-- E -->
  <tone wave="sine" freq="392" dur="1" />    <!-- G -->
</group>

<sequence> - Time events

Play sounds in sequence with timing

<sequence>
  <tone wave="sine" freq="261.63" dur="0.25" at="0" />
  <tone wave="sine" freq="329.63" dur="0.25" at="0.25" />
  <tone wave="sine" freq="392" dur="0.25" at="0.5" />
</sequence>

Resources

📖 Full Documentation

Complete reference for all elements, attributes, and advanced features

🎵 Interactive Editor

Try SPA in your browser with instant playback and examples

Quick Tips

  • • All durations are in seconds
  • • Frequencies are in Hz (440 = A4)
  • • Amplitudes range from 0 to 1
  • • Pan values: -1 (left) to 1 (right)
  • • Use ADSR envelopes: "attack,decay,sustain,release"