Messaging and logging functions

Overview

Csound provides a flexible messaging system for displaying informational messages, warnings, and errors. You can customize message handling by setting callback functions or using the built-in message buffer.

Message attributes

Messages include attribute flags that indicate message type and severity:

CSOUNDMSG_ERROR - Error message
CSOUNDMSG_WARNING - Warning message
CSOUNDMSG_REALTIME - Real-time message
Other types defined in msg_attr.h

csoundMessage

void csoundMessage(CSOUND *csound, const char *format, ...);

Display an informational message using printf-style formatting.

csound

CSOUND*

required

The Csound instance

format

const char*

required

Printf-style format string

...

variadic

Format arguments

Example

MYFLT sr = csoundGetSr(csound);
csoundMessage(csound, "Sample rate: %.0f Hz\n", sr);
csoundMessage(csound, "Processing %d channels\n", csoundGetChannels(csound, 0));

csoundMessageS

void csoundMessageS(CSOUND *csound, int32_t attr, 
                    const char *format, ...);

Print a message with special attributes. With attr=0, this function is identical to csoundMessage().

csound

CSOUND*

required

The Csound instance

attr

int32_t

required

Message attribute flags (see msg_attr.h)

format

const char*

required

Printf-style format string

...

variadic

Format arguments

Example

csoundMessageS(csound, CSOUNDMSG_WARNING, 
               "Warning: Buffer size may be too small\n");
csoundMessageS(csound, CSOUNDMSG_ERROR, 
               "Error: Invalid parameter value: %d\n", param);

csoundMessageV

void csoundMessageV(CSOUND *csound, int32_t attr, 
                    const char *format, va_list args);

Print a message using a va_list for arguments. Useful when wrapping Csound messaging in your own variadic functions.

csound

CSOUND*

required

The Csound instance

attr

int32_t

required

Message attribute flags

format

const char*

required

Printf-style format string

args

va_list

required

Variable argument list

Example

void my_log(CSOUND *csound, const char *format, ...) {
    va_list args;
    va_start(args, format);
    csoundMessageV(csound, 0, format, args);
    va_end(args);
}

my_log(csound, "Custom log: value = %d\n", 42);

Message callbacks

csoundSetMessageCallback

void csoundSetMessageCallback(CSOUND *csound,
    void (*callback)(CSOUND *, int32_t attr, 
                     const char *format, va_list valist));

Set a function to be called by Csound to print messages. This callback is never called in --realtime mode.

csound

CSOUND*

required

The Csound instance

callback

function pointer

required

Callback function with signature:

csound - The Csound instance
attr - Message attributes
format - Printf format string
valist - Variable arguments

Example: Custom message callback

void my_message_callback(CSOUND *csound, int32_t attr, 
                        const char *format, va_list args) {
    // Filter out realtime messages
    if ((attr & CSOUNDMSG_TYPE_MASK) != CSOUNDMSG_REALTIME) {
        vfprintf(stderr, format, args);
        fflush(stderr);
    }
}

CSO UND *csound = csoundCreate(NULL, NULL);
csoundSetMessageCallback(csound, my_message_callback);

Example: Logging to file

static FILE *log_file = NULL;

void file_message_callback(CSOUND *csound, int32_t attr,
                          const char *format, va_list args) {
    if (log_file != NULL) {
        vfprintf(log_file, format, args);
        fflush(log_file);
    }
}

int main() {
    log_file = fopen("csound.log", "w");
    
    CSOUND *csound = csoundCreate(NULL, NULL);
    csoundSetMessageCallback(csound, file_message_callback);
    
    // Use Csound...
    
    csoundDestroy(csound);
    fclose(log_file);
}

csoundSetMessageStringCallback

void csoundSetMessageStringCallback(CSOUND *csound,
    void (*callback)(CSOUND *csound, int32_t attr, const char *str));

Set an alternative message callback with a simpler signature that receives the complete formatted string. This callback can be used in --realtime mode and is cleared after csoundReset().

csound

CSOUND*

required

The Csound instance

callback

function pointer

required

Callback function receiving the formatted message string

Example

void string_callback(CSOUND *csound, int32_t attr, const char *str) {
    printf("[Csound] %s", str);
}

csoundSetMessageStringCallback(csound, string_callback);

csoundSetDefaultMessageCallback

void csoundSetDefaultMessageCallback(
    void (*callback)(CSOUND *, int32_t attr, 
                     const char *format, va_list valist));

Set a default message callback for all Csound instances. This is a global setting.

callback

function pointer

required

Default callback function for all instances

Example

void global_message_callback(CSOUND *csound, int32_t attr,
                            const char *format, va_list args) {
    fprintf(stderr, "[CSOUND] ");
    vfprintf(stderr, format, args);
}

int main() {
    // Set before creating any instances
    csoundSetDefaultMessageCallback(global_message_callback);
    
    CSOUND *csound = csoundCreate(NULL, NULL);
    // ... use csound
}

Message buffer

csoundCreateMessageBuffer

void csoundCreateMessageBuffer(CSOUND *csound, int32_t toStdOut);

Create a buffer for storing messages printed by Csound. Should be called after creating a Csound instance and destroyed before deleting the instance.

csound

CSOUND*

required

The Csound instance

toStdOut

int32_t

required

If non-zero, messages are also printed to stdout/stderr in addition to being buffered

Using the message buffer sets the internal message callback, so csoundSetMessageCallback() should not be called after creating the message buffer.

csoundGetFirstMessage

const char* csoundGetFirstMessage(CSOUND *csound);

Returns the first message from the buffer.

csound

CSOUND*

required

The Csound instance

return

const char*

Pointer to the message string, or NULL if buffer is empty

csoundGetFirstMessageAttr

int32_t csoundGetFirstMessageAttr(CSOUND *csound);

Returns the attribute parameter of the first message in the buffer.

csound

CSOUND*

required

The Csound instance

return

int32_t

Message attributes (see msg_attr.h)

csoundPopFirstMessage

void csoundPopFirstMessage(CSOUND *csound);

Remove the first message from the buffer.

csound

CSOUND*

required

The Csound instance

csoundGetMessageCnt

int32_t csoundGetMessageCnt(CSOUND *csound);

Returns the number of pending messages in the buffer.

csound

CSOUND*

required

The Csound instance

return

int32_t

Number of messages in the buffer

csoundDestroyMessageBuffer

void csoundDestroyMessageBuffer(CSOUND *csound);

Release all memory used by the message buffer.

csound

CSOUND*

required

The Csound instance

Example: Using message buffer

CSO UND *csound = csoundCreate(NULL, NULL);

// Create message buffer (don't print to stdout)
csoundCreateMessageBuffer(csound, 0);

// Compile and run
csoundCompile(csound, argc, argv);
csoundStart(csound);

for (int i = 0; i < 10; i++) {
    csoundPerformKsmps(csound);
    
    // Process all buffered messages
    while (csoundGetMessageCnt(csound) > 0) {
        const char *msg = csoundGetFirstMessage(csound);
        int32_t attr = csoundGetFirstMessageAttr(csound);
        
        printf("Message [attr=%d]: %s", attr, msg);
        csoundPopFirstMessage(csound);
    }
}

csoundDestroyMessageBuffer(csound);
csoundDestroy(csound);

Message level control

csoundGetMessageLevel

int32_t csoundGetMessageLevel(CSOUND *csound);

Returns the current message level (from 0 to 231).

csound

CSOUND*

required

The Csound instance

return

int32_t

Current message level

csoundSetMessageLevel

void csoundSetMessageLevel(CSOUND *csound, int32_t messageLevel);

Set the message level (from 0 to 231). Higher values produce more verbose output.

csound

CSOUND*

required

The Csound instance

messageLevel

int32_t

required

New message level (0-231)

Example

// Suppress most messages
csoundSetMessageLevel(csound, 0);

// Enable verbose output
csoundSetMessageLevel(csound, 7);

Error counting

csoundErrCnt

int32_t csoundErrCnt(CSOUND *csound);

Returns the total error count of the current performance.

csound

CSOUND*

required

The Csound instance

return

int32_t

Number of errors encountered

Example

int result = csoundCompile(csound, argc, argv);
if (!result) {
    result = csoundStart(csound);
    while (!result) {
        result = csoundPerformKsmps(csound);
    }
}

int32_t errors = csoundErrCnt(csound);
if (errors > 0) {
    printf("Performance completed with %d errors\n", errors);
}

csoundDestroy(csound);
return (result >= 0 ? errors : -result);

​Overview

​Message attributes

​csoundMessage

​Example

​csoundMessageS

​Example

​csoundMessageV

​Example

​Message callbacks

​csoundSetMessageCallback

​Example: Custom message callback

​Example: Logging to file

​csoundSetMessageStringCallback

​Example

​csoundSetDefaultMessageCallback

​Example

​Message buffer

​csoundCreateMessageBuffer

​csoundGetFirstMessage

​csoundGetFirstMessageAttr

​csoundPopFirstMessage

​csoundGetMessageCnt

​csoundDestroyMessageBuffer

​Example: Using message buffer

​Message level control

​csoundGetMessageLevel

​csoundSetMessageLevel

​Example

​Error counting

​csoundErrCnt

​Example

Overview

Message attributes

csoundMessage

Example

csoundMessageS

Example

csoundMessageV

Example

Message callbacks

csoundSetMessageCallback

Example: Custom message callback

Example: Logging to file

csoundSetMessageStringCallback

Example

csoundSetDefaultMessageCallback

Example

Message buffer

csoundCreateMessageBuffer

csoundGetFirstMessage

csoundGetFirstMessageAttr

csoundPopFirstMessage

csoundGetMessageCnt

csoundDestroyMessageBuffer

Example: Using message buffer

Message level control

csoundGetMessageLevel

csoundSetMessageLevel

Example

Error counting

csoundErrCnt

Example