Csound API  6.18
Performance

Functions

PUBLIC TREEcsoundParseOrc (CSOUND *csound, const char *str)
 Parse the given orchestra from an ASCII string into a TREE. More...
 
PUBLIC int csoundCompileTree (CSOUND *csound, TREE *root)
 Compile the given TREE node into structs for Csound to use this can be called during performance to compile a new TREE. More...
 
PUBLIC int csoundCompileTreeAsync (CSOUND *csound, TREE *root)
 Asynchronous version of csoundCompileTree() More...
 
PUBLIC void csoundDeleteTree (CSOUND *csound, TREE *tree)
 Free the resources associated with the TREE *tree This function should be called whenever the TREE was created with csoundParseOrc and memory can be deallocated. More...
 
PUBLIC int csoundCompileOrc (CSOUND *csound, const char *str)
 Parse, and compile the given orchestra from an ASCII string, also evaluating any global space code (i-time only) this can be called during performance to compile a new orchestra. More...
 
PUBLIC int csoundCompileOrcAsync (CSOUND *csound, const char *str)
 Async version of csoundCompileOrc(). More...
 
PUBLIC MYFLT csoundEvalCode (CSOUND *csound, const char *str)
 Parse and compile an orchestra given on an string, evaluating any global space code (i-time only). More...
 
PUBLIC int csoundInitializeCscore (CSOUND *, FILE *insco, FILE *outsco)
 Prepares an instance of Csound for Cscore processing outside of running an orchestra (i.e. More...
 
PUBLIC int csoundCompileArgs (CSOUND *, int argc, const char **argv)
 Read arguments, parse and compile an orchestra, read, process and load a score. More...
 
PUBLIC int csoundStart (CSOUND *csound)
 Prepares Csound for performance. More...
 
PUBLIC int csoundCompile (CSOUND *, int argc, const char **argv)
 Compiles Csound input files (such as an orchestra and score, or CSD) as directed by the supplied command-line arguments, but does not perform them. More...
 
PUBLIC int csoundCompileCsd (CSOUND *csound, const char *csd_filename)
 Compiles a Csound input file (CSD, .csd file), but does not perform it. More...
 
PUBLIC int csoundCompileCsdText (CSOUND *csound, const char *csd_text)
 Behaves the same way as csoundCompileCsd, except that the content of the CSD is read from the csd_text string rather than from a file. More...
 
PUBLIC int csoundPerform (CSOUND *)
 Senses input events and performs audio output until the end of score is reached (positive return value), an error occurs (negative return value), or performance is stopped by calling csoundStop() from another thread (zero return value). More...
 
PUBLIC int csoundPerformKsmps (CSOUND *)
 Senses input events, and performs one control sample worth (ksmps) of audio output. More...
 
PUBLIC int csoundPerformBuffer (CSOUND *)
 Performs Csound, sensing real-time and score events and processing one buffer's worth (-b frames) of interleaved audio. More...
 
PUBLIC void csoundStop (CSOUND *)
 Stops a csoundPerform() running in another thread. More...
 
PUBLIC int csoundCleanup (CSOUND *)
 Prints information about the end of a performance, and closes audio and MIDI devices. More...
 
PUBLIC void csoundReset (CSOUND *)
 Resets all internal memory and state in preparation for a new performance. More...
 

Detailed Description

Function Documentation

◆ csoundCleanup()

PUBLIC int csoundCleanup ( CSOUND )

Prints information about the end of a performance, and closes audio and MIDI devices.

Note: after calling csoundCleanup(), the operation of the perform functions is undefined.

◆ csoundCompile()

PUBLIC int csoundCompile ( CSOUND ,
int  argc,
const char **  argv 
)

Compiles Csound input files (such as an orchestra and score, or CSD) as directed by the supplied command-line arguments, but does not perform them.

Returns a non-zero error code on failure. This function cannot be called during performance, and before a repeated call, csoundReset() needs to be called. In this (host-driven) mode, the sequence of calls should be as follows: /code csoundCompile(csound, argc, argv); while (!csoundPerformBuffer(csound)); csoundCleanup(csound); csoundReset(csound); /endcode Calls csoundStart() internally. Can only be called again after reset (see csoundReset())

◆ csoundCompileArgs()

PUBLIC int csoundCompileArgs ( CSOUND ,
int  argc,
const char **  argv 
)

Read arguments, parse and compile an orchestra, read, process and load a score.

◆ csoundCompileCsd()

PUBLIC int csoundCompileCsd ( CSOUND csound,
const char *  csd_filename 
)

Compiles a Csound input file (CSD, .csd file), but does not perform it.

Returns a non-zero error code on failure.

If csoundStart is called before csoundCompileCsd, the <CsOptions> element is ignored (but csoundSetOption can be called any number of times), the <CsScore> element is not pre-processed, but dispatched as real-time events; and performance continues indefinitely, or until ended by calling csoundStop or some other logic. In this "real-time" mode, the sequence of calls should be:

csoundSetOption("-an_option");
csoundSetOption("-another_option");
csoundStart(csound);
csoundCompileCsd(csound, csd_filename);
while (1) {
// Something to break out of the loop
// when finished here...
}
csoundCleanup(csound);
csoundReset(csound);

NB: this function can be called repeatedly during performance to replace or add new instruments and events.

But if csoundCompileCsd is called before csoundStart, the <CsOptions> element is used, the <CsScore> section is pre-processed and dispatched normally, and performance terminates when the score terminates, or csoundStop is called. In this "non-real-time" mode (which can still output real-time audio and handle real-time events), the sequence of calls should be:

csoundCompileCsd(csound, csd_filename);
csoundStart(csound);
while (1) {
int finished = csoundPerformBuffer(csound);
if (finished) break;
}
csoundCleanup(csound);
csoundReset(csound);

◆ csoundCompileCsdText()

PUBLIC int csoundCompileCsdText ( CSOUND csound,
const char *  csd_text 
)

Behaves the same way as csoundCompileCsd, except that the content of the CSD is read from the csd_text string rather than from a file.

This is convenient when it is desirable to package the csd as part of an application or a multi-language piece.

◆ csoundCompileOrc()

PUBLIC int csoundCompileOrc ( CSOUND csound,
const char *  str 
)

Parse, and compile the given orchestra from an ASCII string, also evaluating any global space code (i-time only) this can be called during performance to compile a new orchestra.

/code char *orc = "instr 1 \n a1 rand 0dbfs/4 \n out a1 \n"; csoundCompileOrc(csound, orc); /endcode

◆ csoundCompileOrcAsync()

PUBLIC int csoundCompileOrcAsync ( CSOUND csound,
const char *  str 
)

Async version of csoundCompileOrc().

The code is parsed and compiled, then placed on a queue for asynchronous merge into the running engine, and evaluation. The function returns following parsing and compilation.

◆ csoundCompileTree()

PUBLIC int csoundCompileTree ( CSOUND csound,
TREE root 
)

Compile the given TREE node into structs for Csound to use this can be called during performance to compile a new TREE.

◆ csoundCompileTreeAsync()

PUBLIC int csoundCompileTreeAsync ( CSOUND csound,
TREE root 
)

Asynchronous version of csoundCompileTree()

◆ csoundDeleteTree()

PUBLIC void csoundDeleteTree ( CSOUND csound,
TREE tree 
)

Free the resources associated with the TREE *tree This function should be called whenever the TREE was created with csoundParseOrc and memory can be deallocated.

◆ csoundEvalCode()

PUBLIC MYFLT csoundEvalCode ( CSOUND csound,
const char *  str 
)

Parse and compile an orchestra given on an string, evaluating any global space code (i-time only).

On SUCCESS it returns a value passed to the 'return' opcode in global space /code char *code = "i1 = 2 + 2 \n return i1 \n"; MYFLT retval = csoundEvalCode(csound, code); /endcode

◆ csoundInitializeCscore()

PUBLIC int csoundInitializeCscore ( CSOUND ,
FILE *  insco,
FILE *  outsco 
)

Prepares an instance of Csound for Cscore processing outside of running an orchestra (i.e.

"standalone Cscore"). It is an alternative to csoundCompile(), and csoundPerform*() and should not be used with these functions. You must call this function before using the interface in "cscore.h" when you do not wish to compile an orchestra. Pass it the already open FILE* pointers to the input and output score files. It returns CSOUND_SUCCESS on success and CSOUND_INITIALIZATION or other error code if it fails.

◆ csoundParseOrc()

PUBLIC TREE* csoundParseOrc ( CSOUND csound,
const char *  str 
)

Parse the given orchestra from an ASCII string into a TREE.

This can be called during performance to parse new code.

◆ csoundPerform()

PUBLIC int csoundPerform ( CSOUND )

Senses input events and performs audio output until the end of score is reached (positive return value), an error occurs (negative return value), or performance is stopped by calling csoundStop() from another thread (zero return value).

Note that csoundCompile() or csoundCompileOrc(), csoundReadScore(), csoundStart() must be called first. In the case of zero return value, csoundPerform() can be called again to continue the stopped performance. Otherwise, csoundReset() should be called to clean up after the finished or failed performance.

◆ csoundPerformBuffer()

PUBLIC int csoundPerformBuffer ( CSOUND )

Performs Csound, sensing real-time and score events and processing one buffer's worth (-b frames) of interleaved audio.

Note that csoundCompile must be called first, then call csoundGetOutputBuffer() and csoundGetInputBuffer() to get the pointer to csound's I/O buffers. Returns false during performance, and true when performance is finished.

◆ csoundPerformKsmps()

PUBLIC int csoundPerformKsmps ( CSOUND )

Senses input events, and performs one control sample worth (ksmps) of audio output.

Note that csoundCompile() or csoundCompileOrc(), csoundReadScore(), csoundStart() must be called first. Returns false during performance, and true when performance is finished. If called until it returns true, will perform an entire score. Enables external software to control the execution of Csound, and to synchronize performance with audio input and output.

◆ csoundReset()

PUBLIC void csoundReset ( CSOUND )

Resets all internal memory and state in preparation for a new performance.

Enables external software to run successive Csound performances without reloading Csound. Implies csoundCleanup(), unless already called.

◆ csoundStart()

PUBLIC int csoundStart ( CSOUND csound)

Prepares Csound for performance.

Normally called after compiling a csd file or an orc file, in which case score preprocessing is performed and performance terminates when the score terminates.

However, if called before compiling a csd file or an orc file, score preprocessing is not performed and "i" statements are dispatched as real-time events, the <CsOptions> tag is ignored, and performance continues indefinitely or until ended using the API.

◆ csoundStop()

PUBLIC void csoundStop ( CSOUND )

Stops a csoundPerform() running in another thread.

Note that it is not guaranteed that csoundPerform() has already stopped when this function returns.