TypeScript audio engine

Audio control plane for TypeScript.

Playback, synthesis, routing, and device management. sonic-core owns the control plane while a NativeAOT sidecar handles the actual audio through OpenAL Soft.

Get started Read the Handbook

Install

git clone https://github.com/mcp-tool-shop-org/sonic-core cd sonic-core && npm install && npm run build

Play

import { SonicEngine } from '@sonic-core/engine'; const engine = new SonicEngine(backend); await engine.play('file:///path/to/sound.wav', { loop: true, initial_volume: 0.7 });

MCP

SONIC_RUNTIME_PATH=./runtime \ npx @sonic-core/service

Features

Everything you need to build audio-powered applications.

SidecarBackend

Spawns and manages the native runtime binary. Auto-restart on crash, protocol negotiation, consecutive timeout detection, and handle mapping.

Per-Playback Device Routing

Route individual playbacks to specific audio devices. Enumerate available outputs and switch on the fly.

Gain, Pan, Fade

Per-playback volume, stereo panning, and timed fades. All control happens in TypeScript — the runtime executes.

13 MCP Tools

FastMCP server exposes play, pause, resume, stop, seek, volume, pan, spatial, devices, leases, and more over stdio.

Strict Protocol Boundary

ndjson-stdio-v1 wire format with versioned handshake. TypeScript never touches audio buffers — the runtime owns the DSP.

Event System

playback_ended, device changes, and runtime lifecycle events flow from runtime to engine via structured event envelopes.

Quick Start

Build

# Clone and build
git clone https://github.com/mcp-tool-shop-org/sonic-core
cd sonic-core
npm install
npm run build
npm test

Use the Engine

import { SonicEngine, SidecarBackend } from '@sonic-core/engine';

const sidecar = new SidecarBackend({
  executablePath: process.env.SONIC_RUNTIME_PATH,
});
await sidecar.start();

const engine = new SonicEngine(sidecar);
const { playbackId } = await engine.play(source, {
  loop: true,
  initial_volume: 0.5,
});

MCP Service

# Start the MCP service (stdio mode)
SONIC_RUNTIME_PATH=./sonic-runtime \
  npx @sonic-core/service

# Available tools:
# play, pause, resume, stop, seek,
# set_volume, set_pan, get_devices,
# set_output_device, renew_lease,
# get_playback_state, replace_playback,
# set_spatial_position