A declarative XML format for procedural sound effects on the web.
This is a monorepo managed with pnpm workspaces containing all SPA packages:
spa/
├── packages/
│ ├── core/ # @spa-audio/core - Core JS library (parser + renderer)
│ └── react/ # @spa-audio/react - React component integration
├── apps/
│ └── web/ # @spa-audio/web - Website with visual designer
├── docs/ # Documentation
│ ├── SPEC.md # Technical specification
│ ├── QUICKSTART.md # 5-minute tutorial
│ └── ROADMAP.md # Implementation roadmap
├── examples/ # Example .spa files
│ ├── ui/ # UI sounds
│ ├── forms/ # Form validation
│ ├── game/ # Game effects
│ └── ambient/ # Atmospheric sounds
└── schema/ # JSON Schema for validation
- Node.js 18+
- pnpm 8+ (
npm install -g pnpm)
# Clone the repository
git clone https://github.com/yourusername/spa.git
cd spa
# Install dependencies
pnpm install
# Build all packages
pnpm build# Run all packages in dev mode
pnpm dev
# Run specific package
pnpm web:dev # Website with visual designer
pnpm core:test # Run core library testsCore JavaScript library for parsing and rendering SPA files.
- Zero dependencies - Uses native Web Audio API
- < 20KB gzipped
- TypeScript support
- Renders sounds in < 10ms
import { renderSPA, playSPA } from '@spa-audio/core';
// Play a simple click sound
await playSPA(`
<spa xmlns="https://spa.audio/ns" version="1.0">
<tone wave="sine" freq="800" dur="0.05"
envelope="0,0.02,0,0.03"/>
</spa>
`);React component for easy SPA integration.
import { SPASound } from '@spa-audio/react';
function Button() {
return (
<button>
Click Me
<SPASound autoPlay>
{`<spa xmlns="https://spa.audio/ns" version="1.0">
<tone wave="sine" freq="800" dur="0.05"/>
</spa>`}
</SPASound>
</button>
);
}Visual designer and documentation website.
- Visual Sound Designer - Build sounds with a GUI
- Live Playground - Write and test SPA code
- Example Library - 50+ ready-to-use sounds
- Documentation - Complete reference
Problem: Web developers need sound effects but WAV/MP3 files are huge, static, and non-parametric.
Solution: SPA - a tiny XML format that describes sounds procedurally, just like SVG describes graphics.
Example:
<spa xmlns="https://spa.audio/ns" version="1.0">
<tone wave="sine" freq="800" dur="0.05" envelope="0,0.02,0,0.03"/>
</spa>- File size: 80 bytes
- Equivalent WAV: 9.6 KB
- Savings: 120x smaller
50-100x smaller than WAV/MP3 for simple sounds
// Dynamic pitch based on user score
const freq = 400 + (score * 10);
playSPA(`<tone wave="sine" freq="${freq}" dur="0.1"/>`);Inline sounds directly in your HTML/JS
LLMs can generate SPA syntax easily
Here is a comprehensive guide to composing audio in SPA:
<paste (docs/SPA_LLM_PROMPT.md)>
Can you compose a sound effect that sounds like a tidal wave?
- Technical Specification - Complete format reference
- Quick Start Guide - Learn SPA in 5 minutes
- Roadmap - Development timeline
- Build Instructions - Detailed implementation guide
<!-- Button Click -->
<spa xmlns="https://spa.audio/ns" version="1.0">
<tone wave="sine" freq="800" dur="0.05"
envelope="0,0.02,0,0.03"/>
</spa>
<!-- Laser Effect -->
<spa xmlns="https://spa.audio/ns" version="1.0">
<group>
<tone wave="saw" dur="0.3"
freq.start="1200" freq.end="200" freq.curve="exp"
envelope="0,0.1,0,0.2"/>
<noise color="white" dur="0.1" amp="0.3"/>
</group>
</spa>
<!-- Success Chime -->
<spa xmlns="https://spa.audio/ns" version="1.0">
<group>
<tone wave="sine" freq="523" dur="0.15"/>
<tone wave="sine" freq="659" dur="0.3"/>
</group>
</spa>
<!-- Heartbeat (NEW: Using repeat!) -->
<spa xmlns="https://spa.audio/ns" version="1.0">
<tone wave="sine" freq="60" dur="0.1"
repeat="100" repeat.interval="0.8"
envelope="0.01,0.05,0.3,0.1"/>
</spa>
<!-- Echo Effect (NEW: With decay and pitch shift!) -->
<spa xmlns="https://spa.audio/ns" version="1.0">
<tone wave="sine" freq="440" dur="0.2"
repeat="8" repeat.interval="0.15"
repeat.decay="0.3" repeat.pitchShift="-2"
envelope="0.01,0.05,0.5,0.1"/>
</spa>
<!-- Musical Melody (NEW: Using sequence!) -->
<spa xmlns="https://spa.audio/ns" version="1.0">
<sequence>
<tone wave="sine" freq="261.63" dur="0.2" at="0"/>
<tone wave="sine" freq="329.63" dur="0.2" at="0.25"/>
<tone wave="sine" freq="392" dur="0.2" at="0.5"/>
<tone wave="sine" freq="523.25" dur="0.4" at="0.75"/>
</sequence>
</spa>pnpm dev # Run all packages in dev mode
pnpm build # Build all packages
pnpm test # Run all tests
pnpm lint # Lint all packages
pnpm typecheck # Type check all packagespnpm --filter @spa-audio/core test # Test core library
pnpm --filter @spa-audio/web dev # Run website locally
pnpm --filter @spa-audio/react build # Build React component- ✅ Core library (parser + renderer)
- ✅ Basic website with visual designer
- ✅ 20+ example sounds
- ⬜ npm package published
- ⬜ VS Code extension
- ⬜ Vue integration
- ⬜ CLI tools
- ⬜ 50+ example sounds
- ⬜ Community sound library
- ⬜ AI integration
- ⬜ Browser DevTools support
- ⬜ W3C proposal
Contributions are welcome! Please read our contributing guidelines (coming soon).
MIT
- Website (coming soon)
- NPM Package (coming soon)
- Discord Community (coming soon)
Let's make web audio better. 🔊