Language bindings overview

Overview of Csound language bindings and host APIs

Csound provides comprehensive language bindings that allow you to integrate Csound into applications written in various programming languages. These bindings give you programmatic control over Csound instances, compilation, performance, and audio I/O.

Available bindings

Csound offers official bindings for multiple languages:

• C API - The core C API that all other bindings wrap
• C++ - Object-oriented C++ interface with RAII semantics
• Python - ctcsound Python bindings using ctypes
• JavaScript - WebAssembly bindings for browser and Node.js
• Java - JNI-based Java bindings

Architecture

All language bindings wrap the core C API defined in csound.h. The typical architecture is:

┌─────────────────────────────────────┐
│   Your Application (Any Language)   │
└─────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────┐
│     Language Binding (FFI Layer)    │
│  (ctypes, SWIG, JNI, WebAssembly)   │
└─────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────┐
│       Csound C API (csound.h)       │
└─────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────┐
│          Csound Engine              │
└─────────────────────────────────────┘

Common operations

All bindings support these core operations:

Instantiation

Creating and destroying Csound instances:

C

CSOUND *csound = csoundCreate(NULL, NULL);
// Use csound...
csoundDestroy(csound);

C++

Csound csound;
// Use csound...
// Automatic cleanup via destructor

Python

from ctcsound import Csound
cs = Csound()
# Use cs...
del cs  # Automatic cleanup

JavaScript

const csound = await Csound();
// Use csound...
await csound.terminateInstance();

Compilation and performance

Compiling Csound code and running performance:

C

csoundCompileCSD(csound, "myfile.csd", 0, 0);
csoundStart(csound);
while (csoundPerformKsmps(csound) == 0) {
    // Process audio buffer
}

C++

csound.CompileCSD("myfile.csd");
csound.Start();
while (csound.PerformKsmps() == 0) {
    // Process audio buffer
}

Python

cs.compileCSD('myfile.csd')
cs.start()
while cs.performKsmps() == 0:
    # Process audio buffer
    pass

JavaScript

await csound.compileCSD('myfile.csd');
await csound.start();
await csound.perform();

Channel communication

Sending and receiving values via software channels:

C

csoundSetControlChannel(csound, "volume", 0.8);
MYFLT value = csoundGetControlChannel(csound, "output", NULL);

C++

csound.SetControlChannel("volume", 0.8);
MYFLT value = csound.GetControlChannel("output");

Python

cs.setControlChannel('volume', 0.8)
value = cs.controlChannel('output')

JavaScript

await csound.setControlChannel('volume', 0.8);
const value = await csound.getControlChannel('output');

Return values and error handling

Most Csound API functions return status codes:

• CSOUND_SUCCESS (0) - Operation completed successfully
• CSOUND_ERROR (-1) - Unspecified failure
• CSOUND_INITIALIZATION (-2) - Failed during initialization
• CSOUND_PERFORMANCE (-3) - Failed during performance
• CSOUND_MEMORY (-4) - Failed to allocate requested memory
• CSOUND_SIGNAL (-5) - Termination requested by signal

Thread safety

The Csound API is generally not thread-safe except for specific functions documented as thread-safe. When using Csound in multi-threaded applications:

• Use separate Csound instances for different threads
• Use the circular buffer API for thread-safe audio data exchange
• Consider using CsoundPerformanceThread (C++) for threaded performance

Performance considerations

Buffer sizes

Set appropriate buffer sizes for your use case:

csoundSetOption(csound, "-b512");  // Software buffer
csoundSetOption(csound, "-B2048"); // Hardware buffer

Sample rate and ksmps

Configure audio settings before compilation:

csoundSetOption(csound, "--sample-rate=48000");
csoundSetOption(csound, "--ksmps=64");

Next steps

C API

Explore the core C API reference

C++ bindings

Learn about the C++ object-oriented interface

Python bindings

Use Csound from Python with ctcsound

JavaScript bindings

Run Csound in the browser or Node.js