Package Exports

@spa-audio/core
@spa-audio/core/dist/spa.cjs.js
@spa-audio/core/dist/spa.esm.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@spa-audio/core) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

spa-audio

Core JavaScript library for parsing and rendering SPA (Synthetic Parametric Audio) files.

Features

Tiny: < 20KB gzipped
Fast: Renders sounds in < 10ms
Zero Dependencies: Uses native Web Audio API
TypeScript Support: Full type definitions included
Universal: Works in browsers and Node.js

Installation

npm install spa-audio

Quick Start

import { renderSPA, playSPA } from 'spa-audio';

// 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>
`);

// Render to AudioBuffer for reuse
const buffer = await renderSPA(`
  <spa xmlns="https://spa.audio/ns" version="1.0">
    <tone wave="sine" freq="440" dur="1.0"/>
  </spa>
`);

// Play the buffer multiple times
const ctx = new AudioContext();
const source = ctx.createBufferSource();
source.buffer = buffer;
source.connect(ctx.destination);
source.start();

API Reference

`renderSPA(xml, options?)`

Renders SPA XML to an AudioBuffer.

const buffer = await renderSPA(spaXML, {
  sampleRate: 48000,  // default: 48000
  channels: 2         // default: 2 (stereo)
});

`playSPA(xml, options?)`

Plays SPA XML directly through the default audio output.

await playSPA(spaXML);

`parseSPA(xml)`

Parses SPA XML into a JavaScript object (AST).

const ast = parseSPA(spaXML);
console.log(ast);
// { version: '1.0', sounds: [...] }

`validate(xml)`

Validates SPA XML against the schema.

const errors = validate(spaXML);
if (errors.length === 0) {
  console.log('Valid SPA!');
} else {
  console.error('Validation errors:', errors);
}

Dynamic Sound Generation

Generate sounds parametrically:

function createNotification(frequency, duration) {
  return `
    <spa xmlns="https://spa.audio/ns" version="1.0">
      <tone wave="sine" freq="${frequency}" dur="${duration}"
            envelope="0,0.05,0.6,0.15"/>
    </spa>
  `;
}

// Higher pitch for success
await playSPA(createNotification(880, 0.2));

// Lower pitch for error
await playSPA(createNotification(400, 0.3));

Layering Sounds

Create complex effects with groups:

const laserSound = `
  <spa xmlns="https://spa.audio/ns" version="1.0">
    <group>
      <tone wave="saw" dur="0.3"
            freq.start="1000" freq.end="200" freq.curve="exp"
            envelope="0,0.1,0,0.2"/>
      <noise color="white" dur="0.1" amp="0.3"
             envelope="0,0.05,0,0.05"/>
    </group>
  </spa>
`;

await playSPA(laserSound);

Browser Support

Chrome/Edge 66+
Firefox 61+
Safari 14.1+
Opera 53+

Requires Web Audio API support.

Node.js Usage

For server-side rendering or testing:

// Node.js environment will use a Web Audio API polyfill
const { renderSPA } = require('spa-audio');

const buffer = await renderSPA(spaXML);
// Returns a Float32Array in Node.js

Performance

Typical render times:

Simple tone: < 1ms
Complex layered sound: < 10ms
10 layered tones: < 15ms

Examples

See the spa-spec repository for a complete library of example sounds.

spa-spec - Official specification
spa-web - Visual designer and playground
spa-react - React integration
spa-vscode - VS Code extension

License

MIT

@spa-audio/core