Skip to main content
The Csound JavaScript API provides a complete interface to Csound running in WebAssembly. This allows you to run Csound directly in web browsers and Node.js environments with full access to all Csound features.

​
Installation

​
Browser

npm install @csound/browser

​
Node.js

npm install @csound/nodejs

​
Quick start

​
Browser example

import { Csound } from '@csound/browser';

// Initialize Csound
const csound = await Csound();

// Compile and run a CSD file
const csd = `
<CsoundSynthesizer>
<CsOptions>
  -odac
</CsOptions>
<CsInstruments>
  instr 1
    out poscil(0dbfs/3, 440)
  endin
</CsInstruments>
<CsScore>
  i 1 0 2
</CsScore>
</CsoundSynthesizer>
`;

await csound.compileCSD(csd, 1); // mode 1 = text
await csound.start();
await csound.perform();

​
Node.js example

import { Csound } from '@csound/nodejs';

const csound = await Csound();

// Load and compile a CSD file
await csound.fs.writeFile('test.csd', csdContent);
await csound.compileCSD('test.csd');
await csound.start();
await csound.perform();

​
Core concepts

​
Asynchronous API

All Csound methods return Promises, making the API fully asynchronous: 
const sampleRate = await csound.getSr();
const controlRate = await csound.getKr();
const ksmps = await csound.getKsmps();

​
Event system

Csound uses an event-based architecture built on EventEmitter3: 
csound.on('play', () => {
  console.log('Performance started');
});

csound.on('stop', () => {
  console.log('Performance stopped');
});

csound.on('message', (msg) => {
  console.log('Csound message:', msg);
});

​
Virtual filesystem

Access files through the in-memory filesystem: 
// Write a file
const audioData = new Uint8Array(...);
await csound.fs.writeFile('sound.wav', audioData);

// Read a file
const data = await csound.fs.readFile('output.wav');

// Check if file exists
const exists = await csound.fs.pathExists('test.csd');

​
Performance modes

​
Realtime performance

For live audio output with Web Audio API: 
const csound = await Csound({
  audioContext: new AudioContext(),
  autoConnect: true,
  outputChannelCount: 2
});

await csound.compileCSD(csd, 1);
await csound.start();
await csound.perform();

​
Offline rendering

For rendering to disk: 
const csound = await Csound({
  audioContext: new OfflineAudioContext(2, 44100 * 10, 44100)
});

await csound.compileCSD(csd, 1);
await csound.start();
await csound.perform();

​
Manual control

For frame-by-frame control: 
await csound.start();

// Process one k-period at a time
while (await csound.performKsmps() === 0) {
  // Update controls, check state, etc.
  const scoreTime = await csound.getScoreTime();
}

​
Communication with Csound

​
Control channels

// Set a control channel value
await csound.setControlChannel('volume', 0.5);

// Get a control channel value
const volume = await csound.getControlChannel('volume');

​
String channels

// Set a string channel
await csound.setStringChannel('filename', 'audio.wav');

// Get a string channel
const filename = await csound.getStringChannel('filename');

​
Score events

// Send score events
await csound.inputMessage('i 1 0 2 440 0.5');
await csound.inputMessageAsync('i 2 0.5 1');

// Read score from string
await csound.readScore('i 1 0 5\ni 1 1 3\n');

​
Tables

// Get table length
const length = await csound.tableLength('1');

// Get table value
const value = await csound.tableGet('1', '100');

// Set table value
await csound.tableSet('1', '100', '0.5');

// Copy array into table
await csound.tableCopyIn('1', [0.1, 0.2, 0.3, 0.4]);

// Copy table to array
const tableData = await csound.tableCopyOut('1');

​
Advanced features

​
Web Workers

Run Csound in a separate thread: 
const csound = await Csound({
  useWorker: true,
  useSAB: true // Use SharedArrayBuffer if available
});

​
Plugins

Load WebAssembly plugin libraries: 
const plugin = await fetch('plugin.wasm').then(r => r.arrayBuffer());

const csound = await Csound({
  withPlugins: [plugin]
});

​
MIDI

// Send MIDI messages
await csound.midiMessage(144, 60, 100); // Note on

// Get MIDI device list
const devices = await csound.getMIDIDevList();

​
Audio input

// Enable microphone input
await csound.enableAudioInput();

​
Cleanup

Always clean up resources when done: 
await csound.stop();
await csound.cleanup();
await csound.destroy();

​
Next steps