PerformanceAPI: Low-level Csound API functions

In statisfactions/csound: Accessing Csound functionality through R

Low-level Csound API functions

Description

These functions provide a low-level interface to Csound functionality, and are often called for their side effects on a running instance of Csound. createPerformance() is the recommended interface to this functionality, however.

Usage

  .csoundCreate()

  .csoundCompile(csInstance, args)

  .csoundCleanup(csInstance)

  .csoundDestroy(csInstance)

  .csoundPerform(csInstance)

  .csoundPerformKsmps(csInstance)

  .csoundPreCompile(csInstance)

  .csoundScoreEvent(csInstance,
    type = c("a", "i", "q", "f", "e"), pfields)

  .csoundPerform(csInstance)

Arguments

csInstance	an instance of Csound created by .csoundCreate
args	A character vector of command-line arguments to pass to csound. See The Csound Manual's page on the Csound command-line options.
type	The type of score event; only a, i, q, f, and e are supported in the API: ‘a’: Advance score time by a specified amount. ‘i’: Makes an instrument active at a specific time and for a certain duration ‘q’: Used to quiet an instrument ‘f’: Causes a GEN subroutine to place values in a stored function table ‘e’: Marks the end of the last section of the score. (In practice I've had trouble making ‘e’ statements work as I've expected they would.)
pfields	The pfields (Parameter Fields) for the given score event. See the Csound manual links for parameter type for more information on the parameters that each of these objects take

Details

Order is important (see note!). These should be called in roughly the following order.

1. .csoundCreate() is where it all starts, returning a pointer to a running instance of Csound that the others can then manipulate.

2. .csoundPreCompile() performs a few steps to prepare Csound for compiling the instruments

3. .csoundCompile() compiles the orchestra (and the score if provided) and processes any command-line arguments.

4. Performance (.csoundPerformKsmps()) can be intermingled with sending score events to the instance (.csoundScoreEvent().

Alternatively, you can use .csoundPerform() which does not return control until the score is complete (so is not suitible for truly real-time performance).

5. After performance completes, use .csoundCleanup() to do exactly that.

6. You need to explicitly destroy the Csound instance with .csoundDestroy().

Value

.csoundCreate returns a Csound instance that is an argument to most of the other API functions.

.csoundPerform returns an integer, which is positive number if it reaches the end of the score, or zero if it is stopped by another thread.

Note

Using these functions in the wrong order can cause a crash! createPerformance() provides a safer interface and is recommended for most users.

statisfactions/csound documentation built on Jan. 27, 2024, 1:33 p.m.