Skip to main content
The Csound C API provides a comprehensive interface for embedding Csound into applications and extending its functionality. This API allows you to control all aspects of Csound’s operation programmatically.

​
Architecture

The Csound C API follows an instance-based design where you create and manage CSOUND instances: 
#include "csound.h"

int main() {
    CSOUND *csound;
    
    // Initialize the library
    csoundInitialize(CSOUNDINIT_NO_SIGNAL_HANDLER);
    
    // Create a Csound instance
    csound = csoundCreate(NULL, NULL);
    
    // Use the instance...
    
    // Clean up
    csoundDestroy(csound);
    return 0;
}

​
Core workflow

A typical Csound application follows this sequence:
  1. Initialize - Call csoundInitialize() and csoundCreate()
  2. Configure - Set options with csoundSetOption()
  3. Compile - Load instruments with csoundCompile() or csoundCompileOrc()
  4. Start - Prepare for performance with csoundStart()
  5. Perform - Process audio in a loop with csoundPerformKsmps()
  6. Cleanup - Call csoundReset() and csoundDestroy()

​
Example: Complete performance cycle

CSOUND *csound = csoundCreate(NULL, NULL);

// Compile from command-line arguments
int result = csoundCompile(csound, argc, argv);
if (!result) {
    result = csoundStart(csound);
    while (!result) {
        result = csoundPerformKsmps(csound);
    }
}

csoundDestroy(csound);

​
Return values and error handling

Most Csound API functions return status codes defined in the CSOUND_STATUS enum:
​
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 SIGINT or SIGTERM

​
Thread safety

Each CSOUND instance is independent and can be used in separate threads. However, operations on a single instance are generally not thread-safe. When accessing channels or shared data:
  • Use csoundLockChannel() and csoundUnlockChannel() for manual synchronization
  • Use atomic operations for control channels when available
  • Prefer the thread-safe channel get/set functions

​
Data types

​
CSOUND
struct
Opaque pointer to a Csound instance. All API functions require this pointer.
​
MYFLT
float or double
Audio sample type, either float or double depending on build configuration. Check with csoundGetSizeOfMYFLT().
​
OPARMS
struct
Configuration parameters structure. Access with csoundGetParams().

​
API categories

The C API is organized into functional groups:

​
Platform considerations

The API uses platform-specific visibility macros:
  • PUBLIC - Marks functions exported from the library
  • Functions are available on all platforms (Windows, macOS, Linux, WASI)
  • Header file: csound.h contains all public API declarations