Csound API  6.07
csound.h File Reference

Declares the public Csound application programming interface (API). More...

#include "sysdep.h"
#include "text.h"
#include <stdarg.h>
#include "cfgvar.h"
#include "msg_attr.h"
#include "version.h"

Data Structures

struct  CSOUND_PARAMS
 csound configuration structure, mirrors part of OPARMS, uses more meaningful names More...
 
struct  CS_AUDIODEVICE
 Device information. More...
 
struct  CS_MIDIDEVICE
 
struct  csRtAudioParams
 Real-time audio parameters structure. More...
 
struct  RTCLOCK_S
 
struct  opcodeListEntry
 
struct  CsoundRandMTState_
 
struct  pvsdat_ext
 
struct  ORCTOKEN
 
struct  TREE
 
struct  controlChannelHints_s
 This structure holds the parameter hints for control channels. More...
 
struct  controlChannelInfo_s
 

Macros

#define PUBLIC
 
#define PUBLIC_DATA
 
#define CSOUND_EXITJMP_SUCCESS   (256)
 
#define CSOUNDINIT_NO_SIGNAL_HANDLER   1
 Flags for csoundInitialize(). More...
 
#define CSOUNDINIT_NO_ATEXIT   2
 
#define CSOUND_CALLBACK_KBD_EVENT   (0x00000001U)
 Types for keyboard callbacks set in csoundRegisterKeyboardCallback() More...
 
#define CSOUND_CALLBACK_KBD_TEXT   (0x00000002U)
 
#define csoundSpinLock(spinlock)
 If the spinlock is not locked, lock it and return; if is is locked, wait until it is unlocked, then lock it and return. More...
 
#define csoundSpinUnLock(spinlock)
 
#define CSOUND_SPIN_LOCK
 
#define CSOUND_SPIN_UNLOCK
 

Typedefs

typedef struct CSOUND_ CSOUND
 
typedef struct windat_ WINDAT
 
typedef struct xyindat_ XYINDAT
 
typedef struct RTCLOCK_S RTCLOCK
 
typedef struct CsoundRandMTState_ CsoundRandMTState
 
typedef struct pvsdat_ext PVSDATEXT
 
typedef struct ORCTOKEN ORCTOKEN
 
typedef struct TREE TREE
 
typedef struct controlChannelHints_s controlChannelHints_t
 This structure holds the parameter hints for control channels. More...
 
typedef struct controlChannelInfo_s controlChannelInfo_t
 
typedef void(* channelCallback_t) (CSOUND *csound, const char *channelName, void *channelValuePtr, const void *channelType)
 

Enumerations

enum  CSOUND_STATUS {
  CSOUND_SUCCESS = 0, CSOUND_ERROR = -1, CSOUND_INITIALIZATION = -2, CSOUND_PERFORMANCE = -3,
  CSOUND_MEMORY = -4, CSOUND_SIGNAL = -5
}
 Enables Python interface. More...
 
enum  CSOUND_FILETYPES {
  CSFTYPE_UNIFIED_CSD = 1, CSFTYPE_ORCHESTRA, CSFTYPE_SCORE, CSFTYPE_ORC_INCLUDE,
  CSFTYPE_SCO_INCLUDE, CSFTYPE_SCORE_OUT, CSFTYPE_SCOT, CSFTYPE_OPTIONS,
  CSFTYPE_EXTRACT_PARMS, CSFTYPE_RAW_AUDIO, CSFTYPE_IRCAM, CSFTYPE_AIFF,
  CSFTYPE_AIFC, CSFTYPE_WAVE, CSFTYPE_AU, CSFTYPE_SD2,
  CSFTYPE_W64, CSFTYPE_WAVEX, CSFTYPE_FLAC, CSFTYPE_CAF,
  CSFTYPE_WVE, CSFTYPE_OGG, CSFTYPE_MPC2K, CSFTYPE_RF64,
  CSFTYPE_AVR, CSFTYPE_HTK, CSFTYPE_MAT4, CSFTYPE_MAT5,
  CSFTYPE_NIST, CSFTYPE_PAF, CSFTYPE_PVF, CSFTYPE_SDS,
  CSFTYPE_SVX, CSFTYPE_VOC, CSFTYPE_XI, CSFTYPE_UNKNOWN_AUDIO,
  CSFTYPE_SOUNDFONT, CSFTYPE_STD_MIDI, CSFTYPE_MIDI_SYSEX, CSFTYPE_HETRO,
  CSFTYPE_HETROT, CSFTYPE_PVC, CSFTYPE_PVCEX, CSFTYPE_CVANAL,
  CSFTYPE_LPC, CSFTYPE_ATS, CSFTYPE_LORIS, CSFTYPE_SDIF,
  CSFTYPE_HRTF, CSFTYPE_VST_PLUGIN, CSFTYPE_LADSPA_PLUGIN, CSFTYPE_SNAPSHOT,
  CSFTYPE_FTABLES_TEXT, CSFTYPE_FTABLES_BINARY, CSFTYPE_XSCANU_MATRIX, CSFTYPE_FLOATS_TEXT,
  CSFTYPE_FLOATS_BINARY, CSFTYPE_INTEGER_TEXT, CSFTYPE_INTEGER_BINARY, CSFTYPE_IMAGE_PNG,
  CSFTYPE_POSTSCRIPT, CSFTYPE_SCRIPT_TEXT, CSFTYPE_OTHER_TEXT, CSFTYPE_OTHER_BINARY,
  CSFTYPE_UNKNOWN = 0
}
 The following constants are used with csound->FileOpen2() and csound->ldmemfile2() to specify the format of a file that is being opened. More...
 
enum  controlChannelType {
  CSOUND_CONTROL_CHANNEL = 1, CSOUND_AUDIO_CHANNEL = 2, CSOUND_STRING_CHANNEL = 3, CSOUND_PVS_CHANNEL = 4,
  CSOUND_VAR_CHANNEL = 5, CSOUND_CHANNEL_TYPE_MASK = 15, CSOUND_INPUT_CHANNEL = 16, CSOUND_OUTPUT_CHANNEL = 32
}
 Constants used by the bus interface (csoundGetChannelPtr() etc.). More...
 
enum  controlChannelBehavior { CSOUND_CONTROL_CHANNEL_NO_HINTS = 0, CSOUND_CONTROL_CHANNEL_INT = 1, CSOUND_CONTROL_CHANNEL_LIN = 2, CSOUND_CONTROL_CHANNEL_EXP = 3 }
 

Functions

PUBLIC int csoundInitialize (int flags)
 Initialise Csound library with specific flags. More...
 
PUBLIC CSOUNDcsoundCreate (void *hostData)
 Creates an instance of Csound. More...
 
PUBLIC void csoundDestroy (CSOUND *)
 Destroys an instance of Csound. More...
 
PUBLIC int csoundGetVersion (void)
 Returns the version number times 1000 (5.00.0 = 5000). More...
 
PUBLIC int csoundGetAPIVersion (void)
 Returns the API version number times 100 (1.00 = 100). More...
 
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 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 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, 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 after compilation using one or more of the above functions. More...
 
PUBLIC int csoundCompile (CSOUND *, int argc, 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, char *str)
 Compiles a Csound input file (CSD, .csd file) which includes command-line arguments, but does not perform the file. More...
 
PUBLIC int csoundCompileCsdText (CSOUND *csound, const char *csd_text)
 Compiles a Csound input file contained in a string of text, which includes command-line arguments, orchestra, score, etc., but does not perform the 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...
 
PUBLIC MYFLT csoundGetSr (CSOUND *)
 Returns the number of audio sample frames per second. More...
 
PUBLIC MYFLT csoundGetKr (CSOUND *)
 Returns the number of control samples per second. More...
 
PUBLIC uint32_t csoundGetKsmps (CSOUND *)
 Returns the number of audio sample frames per control sample. More...
 
PUBLIC uint32_t csoundGetNchnls (CSOUND *)
 Returns the number of audio output channels. More...
 
PUBLIC uint32_t csoundGetNchnlsInput (CSOUND *csound)
 Returns the number of audio input channels. More...
 
PUBLIC MYFLT csoundGet0dBFS (CSOUND *)
 Returns the 0dBFS level of the spin/spout buffers. More...
 
PUBLIC int64_t csoundGetCurrentTimeSamples (CSOUND *csound)
 Return the current performance time in samples. More...
 
PUBLIC int csoundGetSizeOfMYFLT (void)
 Return the size of MYFLT in bytes. More...
 
PUBLIC void * csoundGetHostData (CSOUND *)
 Returns host data. More...
 
PUBLIC void csoundSetHostData (CSOUND *, void *hostData)
 Sets host data. More...
 
PUBLIC int csoundSetOption (CSOUND *csound, char *option)
 Set a single csound option (flag). More...
 
PUBLIC void csoundSetParams (CSOUND *csound, CSOUND_PARAMS *p)
 Configure Csound with a given set of parameters defined in the CSOUND_PARAMS structure. More...
 
PUBLIC void csoundGetParams (CSOUND *csound, CSOUND_PARAMS *p)
 Get the current set of parameters from a CSOUND instance in a CSOUND_PARAMS structure. More...
 
PUBLIC int csoundGetDebug (CSOUND *)
 Returns whether Csound is set to print debug messages sent through the DebugMsg() internal API function. More...
 
PUBLIC void csoundSetDebug (CSOUND *, int debug)
 Sets whether Csound prints debug messages from the DebugMsg() internal API function. More...
 
PUBLIC const char * csoundGetOutputName (CSOUND *)
 Returns the output audio output name (-o). More...
 
PUBLIC void csoundSetOutput (CSOUND *csound, char *name, char *type, char *format)
 Set output destination, type and format type can be one of "wav","aiff", "au","raw", "paf", "svx", "nist", "voc", "ircam","w64","mat4", "mat5", "pvf","xi", "htk","sds","avr","wavex","sd2", "flac", "caf","wve","ogg","mpc2k","rf64", or NULL (use default or realtime IO). More...
 
PUBLIC void csoundSetInput (CSOUND *csound, char *name)
 Set input source. More...
 
PUBLIC void csoundSetMIDIInput (CSOUND *csound, char *name)
 Set MIDI input device name/number. More...
 
PUBLIC void csoundSetMIDIFileInput (CSOUND *csound, char *name)
 Set MIDI file input name. More...
 
PUBLIC void csoundSetMIDIOutput (CSOUND *csound, char *name)
 Set MIDI output device name/number. More...
 
PUBLIC void csoundSetMIDIFileOutput (CSOUND *csound, char *name)
 Set MIDI file utput name. More...
 
PUBLIC void csoundSetFileOpenCallback (CSOUND *p, void(*func)(CSOUND *, const char *, int, int, int))
 Sets an external callback for receiving notices whenever Csound opens a file. More...
 
PUBLIC void csoundSetRTAudioModule (CSOUND *csound, char *module)
 Sets the current RT audio module. More...
 
PUBLIC int csoundGetModule (CSOUND *csound, int number, char **name, char **type)
 retrieves a module name and type ("audio" or "midi") given a number Modules are added to list as csound loads them returns CSOUND_SUCCESS on success and CSOUND_ERROR if module number was not found More...
 
PUBLIC long csoundGetInputBufferSize (CSOUND *)
 Returns the number of samples in Csound's input buffer. More...
 
PUBLIC long csoundGetOutputBufferSize (CSOUND *)
 Returns the number of samples in Csound's output buffer. More...
 
PUBLIC MYFLT * csoundGetInputBuffer (CSOUND *)
 Returns the address of the Csound audio input buffer. More...
 
PUBLIC MYFLT * csoundGetOutputBuffer (CSOUND *)
 Returns the address of the Csound audio output buffer. More...
 
PUBLIC MYFLT * csoundGetSpin (CSOUND *)
 Returns the address of the Csound audio input working buffer (spin). More...
 
PUBLIC void csoundAddSpinSample (CSOUND *csound, int frame, int channel, MYFLT sample)
 Adds the indicated sample into the audio input woriing buffer (spin); this only ever makes sense before calling csoundPerformKsmps(). More...
 
PUBLIC MYFLT * csoundGetSpout (CSOUND *csound)
 Returns the address of the Csound audio output working buffer (spout). More...
 
PUBLIC MYFLT csoundGetSpoutSample (CSOUND *csound, int frame, int channel)
 Returns the indicated sample from the Csound audio output working buffer (spout); only ever makes sense after calling csoundPerformKsmps(). More...
 
PUBLIC void ** csoundGetRtRecordUserData (CSOUND *)
 Return pointer to user data pointer for real time audio input. More...
 
PUBLIC void ** csoundGetRtPlayUserData (CSOUND *)
 Return pointer to user data pointer for real time audio output. More...
 
PUBLIC void csoundSetHostImplementedAudioIO (CSOUND *, int state, int bufSize)
 Calling this function with a non-zero 'state' value between csoundCreate() and the start of performance will disable all default handling of sound I/O by the Csound library, allowing the host application to use the spin/spout/input/output buffers directly. More...
 
PUBLIC int csoundGetAudioDevList (CSOUND *csound, CS_AUDIODEVICE *list, int isOutput)
 This function can be called to obtain a list of available input or output audio devices. More...
 
PUBLIC void csoundSetPlayopenCallback (CSOUND *, int(*playopen__)(CSOUND *, const csRtAudioParams *parm))
 Sets a function to be called by Csound for opening real-time audio playback. More...
 
PUBLIC void csoundSetRtplayCallback (CSOUND *, void(*rtplay__)(CSOUND *, const MYFLT *outBuf, int nbytes))
 Sets a function to be called by Csound for performing real-time audio playback. More...
 
PUBLIC void csoundSetRecopenCallback (CSOUND *, int(*recopen_)(CSOUND *, const csRtAudioParams *parm))
 Sets a function to be called by Csound for opening real-time audio recording. More...
 
PUBLIC void csoundSetRtrecordCallback (CSOUND *, int(*rtrecord__)(CSOUND *, MYFLT *inBuf, int nbytes))
 Sets a function to be called by Csound for performing real-time audio recording. More...
 
PUBLIC void csoundSetRtcloseCallback (CSOUND *, void(*rtclose__)(CSOUND *))
 Sets a function to be called by Csound for closing real-time audio playback and recording. More...
 
PUBLIC void csoundSetAudioDeviceListCallback (CSOUND *csound, int(*audiodevlist__)(CSOUND *, CS_AUDIODEVICE *list, int isOutput))
 Sets a function that is called to obtain a list of audio devices. More...
 
PUBLIC void csoundSetMIDIModule (CSOUND *csound, char *module)
 Sets the current MIDI IO module. More...
 
PUBLIC void csoundSetHostImplementedMIDIIO (CSOUND *csound, int state)
 call this function with state 1 if the host is implementing MIDI via the callbacks below. More...
 
PUBLIC int csoundGetMIDIDevList (CSOUND *csound, CS_MIDIDEVICE *list, int isOutput)
 This function can be called to obtain a list of available input or output midi devices. More...
 
PUBLIC void csoundSetExternalMidiInOpenCallback (CSOUND *, int(*func)(CSOUND *, void **userData, const char *devName))
 Sets callback for opening real time MIDI input. More...
 
PUBLIC void csoundSetExternalMidiReadCallback (CSOUND *, int(*func)(CSOUND *, void *userData, unsigned char *buf, int nBytes))
 Sets callback for reading from real time MIDI input. More...
 
PUBLIC void csoundSetExternalMidiInCloseCallback (CSOUND *, int(*func)(CSOUND *, void *userData))
 Sets callback for closing real time MIDI input. More...
 
PUBLIC void csoundSetExternalMidiOutOpenCallback (CSOUND *, int(*func)(CSOUND *, void **userData, const char *devName))
 Sets callback for opening real time MIDI output. More...
 
PUBLIC void csoundSetExternalMidiWriteCallback (CSOUND *, int(*func)(CSOUND *, void *userData, const unsigned char *buf, int nBytes))
 Sets callback for writing to real time MIDI output. More...
 
PUBLIC void csoundSetExternalMidiOutCloseCallback (CSOUND *, int(*func)(CSOUND *, void *userData))
 Sets callback for closing real time MIDI output. More...
 
PUBLIC void csoundSetExternalMidiErrorStringCallback (CSOUND *, const char *(*func)(int))
 Sets callback for converting MIDI error codes to strings. More...
 
PUBLIC void csoundSetMIDIDeviceListCallback (CSOUND *csound, int(*mididevlist__)(CSOUND *, CS_MIDIDEVICE *list, int isOutput))
 Sets a function that is called to obtain a list of MIDI devices. More...
 
PUBLIC int csoundReadScore (CSOUND *csound, const char *str)
 Read, preprocess, and load a score from an ASCII string It can be called repeatedly, with the new score events being added to the currently scheduled ones. More...
 
PUBLIC double csoundGetScoreTime (CSOUND *)
 Returns the current score time in seconds since the beginning of performance. More...
 
PUBLIC int csoundIsScorePending (CSOUND *)
 Sets whether Csound score events are performed or not, independently of real-time MIDI events (see csoundSetScorePending()). More...
 
PUBLIC void csoundSetScorePending (CSOUND *, int pending)
 Sets whether Csound score events are performed or not (real-time events will continue to be performed). More...
 
PUBLIC MYFLT csoundGetScoreOffsetSeconds (CSOUND *)
 Returns the score time beginning at which score events will actually immediately be performed (see csoundSetScoreOffsetSeconds()). More...
 
PUBLIC void csoundSetScoreOffsetSeconds (CSOUND *, MYFLT time)
 Csound score events prior to the specified time are not performed, and performance begins immediately at the specified time (real-time events will continue to be performed as they are received). More...
 
PUBLIC void csoundRewindScore (CSOUND *)
 Rewinds a compiled Csound score to the time specified with csoundSetScoreOffsetSeconds(). More...
 
PUBLIC void csoundSetCscoreCallback (CSOUND *, void(*cscoreCallback_)(CSOUND *))
 Sets an external callback for Cscore processing. More...
 
PUBLIC int csoundScoreSort (CSOUND *, FILE *inFile, FILE *outFile)
 Sorts score file 'inFile' and writes the result to 'outFile'. More...
 
PUBLIC int csoundScoreExtract (CSOUND *, FILE *inFile, FILE *outFile, FILE *extractFile)
 Extracts from 'inFile', controlled by 'extractFile', and writes the result to 'outFile'. More...
 
PUBLIC CS_PRINTF2 void csoundMessage (CSOUND *, const char *format,...)
 Displays an informational message. More...
 
PUBLIC CS_PRINTF3 void csoundMessageS (CSOUND *, int attr, const char *format,...)
 Print message with special attributes (see msg_attr.h for the list of available attributes). More...
 
PUBLIC void csoundMessageV (CSOUND *, int attr, const char *format, va_list args)
 
PUBLIC void csoundSetDefaultMessageCallback (void(*csoundMessageCallback_)(CSOUND *, int attr, const char *format, va_list valist))
 
PUBLIC void csoundSetMessageCallback (CSOUND *, void(*csoundMessageCallback_)(CSOUND *, int attr, const char *format, va_list valist))
 Sets a function to be called by Csound to print an informational message. More...
 
PUBLIC int csoundGetMessageLevel (CSOUND *)
 Returns the Csound message level (from 0 to 231). More...
 
PUBLIC void csoundSetMessageLevel (CSOUND *, int messageLevel)
 Sets the Csound message level (from 0 to 231). More...
 
PUBLIC void csoundCreateMessageBuffer (CSOUND *csound, int toStdOut)
 Creates a buffer for storing messages printed by Csound. More...
 
PUBLIC const char * csoundGetFirstMessage (CSOUND *csound)
 Returns the first message from the buffer. More...
 
PUBLIC int csoundGetFirstMessageAttr (CSOUND *csound)
 Returns the attribute parameter (see msg_attr.h) of the first message in the buffer. More...
 
PUBLIC void csoundPopFirstMessage (CSOUND *csound)
 Removes the first message from the buffer. More...
 
PUBLIC int csoundGetMessageCnt (CSOUND *csound)
 Returns the number of pending messages in the buffer. More...
 
void PUBLIC csoundDestroyMessageBuffer (CSOUND *csound)
 Releases all memory used by the message buffer. More...
 
PUBLIC int csoundGetChannelPtr (CSOUND *, MYFLT **p, const char *name, int type)
 Stores a pointer to the specified channel of the bus in *p, creating the channel first if it does not exist yet. More...
 
PUBLIC int csoundListChannels (CSOUND *, controlChannelInfo_t **lst)
 Returns a list of allocated channels in *lst. More...
 
PUBLIC void csoundDeleteChannelList (CSOUND *, controlChannelInfo_t *lst)
 Releases a channel list previously returned by csoundListChannels(). More...
 
PUBLIC int csoundSetControlChannelHints (CSOUND *, const char *name, controlChannelHints_t hints)
 Set parameters hints for a control channel. More...
 
PUBLIC int csoundGetControlChannelHints (CSOUND *, const char *name, controlChannelHints_t *hints)
 Returns special parameters (assuming there are any) of a control channel, previously set with csoundSetControlChannelHints() or the chnparams opcode. More...
 
PUBLIC int * csoundGetChannelLock (CSOUND *, const char *name)
 Recovers a pointer to a lock for the specified channel called 'name'. More...
 
PUBLIC MYFLT csoundGetControlChannel (CSOUND *csound, const char *name, int *err)
 retrieves the value of control channel identified by *name. More...
 
PUBLIC void csoundSetControlChannel (CSOUND *csound, const char *name, MYFLT val)
 sets the value of control channel identified by *name More...
 
PUBLIC void csoundGetAudioChannel (CSOUND *csound, const char *name, MYFLT *samples)
 copies the audio channel identified by *name into array *samples which should contain enough memory for ksmps MYFLTs More...
 
PUBLIC void csoundSetAudioChannel (CSOUND *csound, const char *name, MYFLT *samples)
 sets the audio channel identified by *name with data from array *samples which should contain at least ksmps MYFLTs More...
 
PUBLIC void csoundGetStringChannel (CSOUND *csound, const char *name, char *string)
 copies the string channel identified by *name into *string which should contain enough memory for the string (see csoundGetChannelDatasize() below) More...
 
PUBLIC void csoundSetStringChannel (CSOUND *csound, const char *name, char *string)
 sets the string channel identified by *name with *string More...
 
PUBLIC int csoundGetChannelDatasize (CSOUND *csound, const char *name)
 returns the size of data stored in a channel; for string channels this might change if the channel space gets reallocated Since string variables use dynamic memory allocation in Csound6, this function can be called to get the space required for csoundGetStringChannel() More...
 
PUBLIC void csoundSetInputChannelCallback (CSOUND *csound, channelCallback_t inputChannelCalback)
 Sets the function which will be called whenever the invalue opcode is used. More...
 
PUBLIC void csoundSetOutputChannelCallback (CSOUND *csound, channelCallback_t outputChannelCalback)
 Sets the function which will be called whenever the outvalue opcode is used. More...
 
PUBLIC int csoundSetPvsChannel (CSOUND *, const PVSDATEXT *fin, const char *name)
 Sends a PVSDATEX fin to the pvsin opcode (f-rate) for channel 'name'. More...
 
PUBLIC int csoundGetPvsChannel (CSOUND *csound, PVSDATEXT *fout, const char *name)
 Receives a PVSDAT fout from the pvsout opcode (f-rate) at channel 'name' Returns zero on success, CSOUND_ERROR if the index is invalid or if fsig framesizes are incompatible. More...
 
PUBLIC int csoundScoreEvent (CSOUND *, char type, const MYFLT *pFields, long numFields)
 Send a new score event. More...
 
PUBLIC int csoundScoreEventAbsolute (CSOUND *, char type, const MYFLT *pfields, long numFields, double time_ofs)
 Like csoundScoreEvent(), this function inserts a score event, but at absolute time with respect to the start of performance, or from an offset set with time_ofs. More...
 
PUBLIC void csoundInputMessage (CSOUND *, const char *message)
 Input a NULL-terminated string (as if from a console), used for line events. More...
 
PUBLIC int csoundKillInstance (CSOUND *csound, MYFLT instr, char *instrName, int mode, int allow_release)
 Kills off one or more running instances of an instrument identified by instr (number) or instrName (name). More...
 
PUBLIC int csoundRegisterSenseEventCallback (CSOUND *, void(*func)(CSOUND *, void *), void *userData)
 Register a function to be called once in every control period by sensevents(). More...
 
PUBLIC void csoundKeyPress (CSOUND *, char c)
 Set the ASCII code of the most recent key pressed. More...
 
PUBLIC int csoundRegisterKeyboardCallback (CSOUND *, int(*func)(void *userData, void *p, unsigned int type), void *userData, unsigned int type)
 Registers general purpose callback functions that will be called to query keyboard events. More...
 
PUBLIC void csoundRemoveKeyboardCallback (CSOUND *csound, int(*func)(void *, void *, unsigned int))
 Removes a callback previously set with csoundRegisterKeyboardCallback(). More...
 
PUBLIC int csoundTableLength (CSOUND *, int table)
 Returns the length of a function table (not including the guard point), or -1 if the table does not exist. More...
 
PUBLIC MYFLT csoundTableGet (CSOUND *, int table, int index)
 Returns the value of a slot in a function table. More...
 
PUBLIC void csoundTableSet (CSOUND *, int table, int index, MYFLT value)
 Sets the value of a slot in a function table. More...
 
PUBLIC void csoundTableCopyOut (CSOUND *csound, int table, MYFLT *dest)
 Copy the contents of a function table into a supplied array *dest The table number is assumed to be valid, and the destination needs to have sufficient space to receive all the function table contents. More...
 
PUBLIC void csoundTableCopyIn (CSOUND *csound, int table, MYFLT *src)
 Copy the contents of an array *src into a given function table The table number is assumed to be valid, and the table needs to have sufficient space to receive all the array contents. More...
 
PUBLIC int csoundGetTable (CSOUND *, MYFLT **tablePtr, int tableNum)
 Stores pointer to function table 'tableNum' in *tablePtr, and returns the table length (not including the guard point). More...
 
PUBLIC int csoundGetTableArgs (CSOUND *csound, MYFLT **argsPtr, int tableNum)
 Stores pointer to the arguments used to generate function table 'tableNum' in *argsPtr, and returns the number of arguments used. More...
 
PUBLIC int csoundIsNamedGEN (CSOUND *csound, int num)
 Checks if a given GEN number num is a named GEN if so, it returns the string length (excluding terminating NULL char) Otherwise it returns 0. More...
 
PUBLIC void csoundGetNamedGEN (CSOUND *csound, int num, char *name, int len)
 Gets the GEN name from a number num, if this is a named GEN The final parameter is the max len of the string (excluding termination) More...
 
PUBLIC int csoundSetIsGraphable (CSOUND *, int isGraphable)
 Tells Csound whether external graphic table display is supported. More...
 
PUBLIC void csoundSetMakeGraphCallback (CSOUND *, void(*makeGraphCallback_)(CSOUND *, WINDAT *windat, const char *name))
 Called by external software to set Csound's MakeGraph function. More...
 
PUBLIC void csoundSetDrawGraphCallback (CSOUND *, void(*drawGraphCallback_)(CSOUND *, WINDAT *windat))
 Called by external software to set Csound's DrawGraph function. More...
 
PUBLIC void csoundSetKillGraphCallback (CSOUND *, void(*killGraphCallback_)(CSOUND *, WINDAT *windat))
 Called by external software to set Csound's KillGraph function. More...
 
PUBLIC void csoundSetExitGraphCallback (CSOUND *, int(*exitGraphCallback_)(CSOUND *))
 Called by external software to set Csound's ExitGraph function. More...
 
PUBLIC void * csoundGetNamedGens (CSOUND *)
 Finds the list of named gens. More...
 
PUBLIC int csoundNewOpcodeList (CSOUND *, opcodeListEntry **opcodelist)
 Gets an alphabetically sorted list of all opcodes. More...
 
PUBLIC void csoundDisposeOpcodeList (CSOUND *, opcodeListEntry *opcodelist)
 Releases an opcode list. More...
 
PUBLIC int csoundAppendOpcode (CSOUND *, const char *opname, int dsblksiz, int flags, int thread, const char *outypes, const char *intypes, int(*iopadr)(CSOUND *, void *), int(*kopadr)(CSOUND *, void *), int(*aopadr)(CSOUND *, void *))
 Appends an opcode implemented by external software to Csound's internal opcode list. More...
 
PUBLIC void csoundSetYieldCallback (CSOUND *, int(*yieldCallback_)(CSOUND *))
 Called by external software to set a function for checking system events, yielding cpu time for coopertative multitasking, etc. More...
 
PUBLIC void * csoundCreateThread (uintptr_t(*threadRoutine)(void *), void *userdata)
 Creates and starts a new thread of execution. More...
 
PUBLIC void * csoundGetCurrentThreadId (void)
 Returns the ID of the currently executing thread, or NULL for failure. More...
 
PUBLIC uintptr_t csoundJoinThread (void *thread)
 Waits until the indicated thread's routine has finished. More...
 
PUBLIC void * csoundCreateThreadLock (void)
 Creates and returns a monitor object, or NULL if not successful. More...
 
PUBLIC int csoundWaitThreadLock (void *lock, size_t milliseconds)
 Waits on the indicated monitor object for the indicated period. More...
 
PUBLIC void csoundWaitThreadLockNoTimeout (void *lock)
 Waits on the indicated monitor object until it is notified. More...
 
PUBLIC void csoundNotifyThreadLock (void *lock)
 Notifies the indicated monitor object. More...
 
PUBLIC void csoundDestroyThreadLock (void *lock)
 Destroys the indicated monitor object. More...
 
PUBLIC void * csoundCreateMutex (int isRecursive)
 Creates and returns a mutex object, or NULL if not successful. More...
 
PUBLIC void csoundLockMutex (void *mutex_)
 Acquires the indicated mutex object; if it is already in use by another thread, the function waits until the mutex is released by the other thread. More...
 
PUBLIC int csoundLockMutexNoWait (void *mutex_)
 Acquires the indicated mutex object and returns zero, unless it is already in use by another thread, in which case a non-zero value is returned immediately, rather than waiting until the mutex becomes available. More...
 
PUBLIC void csoundUnlockMutex (void *mutex_)
 Releases the indicated mutex object, which should be owned by the current thread, otherwise the operation of this function is undefined. More...
 
PUBLIC void csoundDestroyMutex (void *mutex_)
 Destroys the indicated mutex object. More...
 
PUBLIC void * csoundCreateBarrier (unsigned int max)
 Create a Thread Barrier. More...
 
PUBLIC int csoundDestroyBarrier (void *barrier)
 Destroy a Thread Barrier. More...
 
PUBLIC int csoundWaitBarrier (void *barrier)
 Wait on the thread barrier. More...
 
PUBLIC void csoundSleep (size_t milliseconds)
 Waits for at least the specified number of milliseconds, yielding the CPU to other threads. More...
 
PUBLIC long csoundRunCommand (const char *const *argv, int noWait)
 Runs an external command with the arguments specified in 'argv'. More...
 
PUBLIC void csoundInitTimerStruct (RTCLOCK *)
 Initialise a timer structure. More...
 
PUBLIC double csoundGetRealTime (RTCLOCK *)
 Return the elapsed real time (in seconds) since the specified timer structure was initialised. More...
 
PUBLIC double csoundGetCPUTime (RTCLOCK *)
 Return the elapsed CPU time (in seconds) since the specified timer structure was initialised. More...
 
PUBLIC uint32_t csoundGetRandomSeedFromTime (void)
 Return a 32-bit unsigned integer to be used as seed from current time. More...
 
PUBLIC void csoundSetLanguage (cslanguage_t lang_code)
 Set language to 'lang_code' (lang_code can be for example CSLANGUAGE_ENGLISH_UK or CSLANGUAGE_FRENCH or many others, see n_getstr.h for the list of languages). More...
 
PUBLIC const char * csoundGetEnv (CSOUND *csound, const char *name)
 Get pointer to the value of environment variable 'name', searching in this order: local environment of 'csound' (if not NULL), variables set with csoundSetGlobalEnv(), and system environment variables. More...
 
PUBLIC int csoundSetGlobalEnv (const char *name, const char *value)
 Set the global value of environment variable 'name' to 'value', or delete variable if 'value' is NULL. More...
 
PUBLIC int csoundCreateGlobalVariable (CSOUND *, const char *name, size_t nbytes)
 Allocate nbytes bytes of memory that can be accessed later by calling csoundQueryGlobalVariable() with the specified name; the space is cleared to zero. More...
 
PUBLIC void * csoundQueryGlobalVariable (CSOUND *, const char *name)
 Get pointer to space allocated with the name "name". More...
 
PUBLIC void * csoundQueryGlobalVariableNoCheck (CSOUND *, const char *name)
 This function is the same as csoundQueryGlobalVariable(), except the variable is assumed to exist and no error checking is done. More...
 
PUBLIC int csoundDestroyGlobalVariable (CSOUND *, const char *name)
 Free memory allocated for "name" and remove "name" from the database. More...
 
PUBLIC int csoundRunUtility (CSOUND *, const char *name, int argc, char **argv)
 Run utility with the specified name and command line arguments. More...
 
PUBLIC char ** csoundListUtilities (CSOUND *)
 Returns a NULL terminated list of registered utility names. More...
 
PUBLIC void csoundDeleteUtilityList (CSOUND *, char **lst)
 Releases an utility list previously returned by csoundListUtilities(). More...
 
PUBLIC const char * csoundGetUtilityDescription (CSOUND *, const char *utilName)
 Get utility description. More...
 
PUBLIC int csoundRand31 (int *seedVal)
 Simple linear congruential random number generator: (*seedVal) = (*seedVal) * 742938285 % 2147483647 the initial value of *seedVal must be in the range 1 to 2147483646. More...
 
PUBLIC void csoundSeedRandMT (CsoundRandMTState *p, const uint32_t *initKey, uint32_t keyLength)
 Initialise Mersenne Twister (MT19937) random number generator, using 'keyLength' unsigned 32 bit values from 'initKey' as seed. More...
 
PUBLIC uint32_t csoundRandMT (CsoundRandMTState *p)
 Returns next random number from MT19937 generator. More...
 
PUBLIC void * csoundCreateCircularBuffer (CSOUND *csound, int numelem, int elemsize)
 Create circular buffer with numelem number of elements. More...
 
PUBLIC int csoundReadCircularBuffer (CSOUND *csound, void *circular_buffer, void *out, int items)
 Read from circular buffer. More...
 
PUBLIC int csoundPeekCircularBuffer (CSOUND *csound, void *circular_buffer, void *out, int items)
 Read from circular buffer without removing them from the buffer. More...
 
PUBLIC int csoundWriteCircularBuffer (CSOUND *csound, void *p, const void *inp, int items)
 Write to circular buffer. More...
 
PUBLIC void csoundFlushCircularBuffer (CSOUND *csound, void *p)
 Empty circular buffer of any remaining data. More...
 
PUBLIC void csoundDestroyCircularBuffer (CSOUND *csound, void *circularbuffer)
 Free circular buffer. More...
 
PUBLIC int csoundOpenLibrary (void **library, const char *libraryPath)
 Platform-independent function to load a shared library. More...
 
PUBLIC int csoundCloseLibrary (void *library)
 Platform-independent function to unload a shared library. More...
 
PUBLIC void * csoundGetLibrarySymbol (void *library, const char *symbolName)
 Platform-independent function to get a symbol address in a shared library. More...
 

Detailed Description

Declares the public Csound application programming interface (API).

Cscore

Beginning with Csound 5, all of the Cscore functions described in the manual are now part of the Csound API, and they can be called from a program that calls the Csound library.

All of the CScore functions are renamed in the Csound API. For example, createv() is now cscoreCreateEvent(), and lcopy() is now cscoreListCopy(). In addition, each function takes an additional first parameter that is a pointer to a CSOUND instance. You can find the details in the header file, cscore.h, which may be included with your Csound distribution, or if not, can be found in Csound CVS `on SourceForge.

Before you can use any of the Cscore API functions, you must create a CSOUND instance and initialize Cscore by calling csoundInitializeCscore() – see csound.h for an explanation. An example main program that does all of this Top/cscormai.c. You should add a function called cscore() with your own score-processing code. An example that does nothing except write the score back out unchanged can be found in the file Top/cscore_internal.c.

To create your own standalone Cscore program, you must compile cscormai.c (or your own main program) and the file containing your cscore() function, and link them with the Csound API library.

Author
John P. ffitch, Michael Gogins, Matt Ingalls, John D. Ramsdell, Istvan Varga, Victor Lazzarini, Andres Cabrera and Steven Yi.

Hosts using the Csound API must #include <csound.h>, and link with the Csound API library. Plugin libraries should #include <csdl.h> to get access to the API function pointers in the CSOUND structure, and do not need to link with the Csound API library. Only one of csound.h and csdl.h may be included by a compilation unit.

Hosts must first create an instance of Csound using the csoundCreate API function. When hosts are finished using Csound, they must destroy the instance of csound using the csoundDestroy API function. Most of the other Csound API functions take the Csound instance as their first argument. Hosts can only call the standalone API functions declared in csound.h.

Here is the complete code for the simplest possible Csound API host, a command-line Csound application:

#include <csound.h>
int main(int argc, char **argv)
{
CSOUND *csound = csoundCreate(NULL);
int result = csoundCompile(csound, argc, argv);
if (!result)
result = csoundPerform(csound);
csoundDestroy(csound);
return (result >= 0 ? 0 : result);
}

All opcodes, including plugins, receive a pointer to their host instance of Csound as the first argument. Therefore, plugins MUST NOT compile, perform, or destroy the host instance of Csound, and MUST call the Csound API function pointers off the Csound instance pointer.

MYFLT sr = csound->GetSr(csound);

In general, plugins should ONLY access Csound functionality through the API function pointers and public members of the CSOUND_ structure.

License

Csound

Copyright (C) 2001-2013 Michael Gogins, Matt Ingalls, John D. Ramsdell, John P. ffitch, Istvan Varga, Victor Lazzarini, Andres Cabrera and Steven Yi

This software is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this software; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Macro Definition Documentation

#define CSOUND_CALLBACK_KBD_EVENT   (0x00000001U)

Types for keyboard callbacks set in csoundRegisterKeyboardCallback()

#define CSOUND_CALLBACK_KBD_TEXT   (0x00000002U)
#define CSOUND_EXITJMP_SUCCESS   (256)
#define CSOUNDINIT_NO_ATEXIT   2
#define CSOUNDINIT_NO_SIGNAL_HANDLER   1

Flags for csoundInitialize().

#define PUBLIC
#define PUBLIC_DATA

Typedef Documentation

typedef void(* channelCallback_t) (CSOUND *csound, const char *channelName, void *channelValuePtr, const void *channelType)

This structure holds the parameter hints for control channels.

typedef struct CSOUND_ CSOUND
typedef struct ORCTOKEN ORCTOKEN
typedef struct pvsdat_ext PVSDATEXT
typedef struct RTCLOCK_S RTCLOCK
typedef struct TREE TREE
typedef struct windat_ WINDAT
typedef struct xyindat_ XYINDAT

Enumeration Type Documentation

Enumerator
CSOUND_CONTROL_CHANNEL_NO_HINTS 
CSOUND_CONTROL_CHANNEL_INT 
CSOUND_CONTROL_CHANNEL_LIN 
CSOUND_CONTROL_CHANNEL_EXP 

Constants used by the bus interface (csoundGetChannelPtr() etc.).

Enumerator
CSOUND_CONTROL_CHANNEL 
CSOUND_AUDIO_CHANNEL 
CSOUND_STRING_CHANNEL 
CSOUND_PVS_CHANNEL 
CSOUND_VAR_CHANNEL 
CSOUND_CHANNEL_TYPE_MASK 
CSOUND_INPUT_CHANNEL 
CSOUND_OUTPUT_CHANNEL 

The following constants are used with csound->FileOpen2() and csound->ldmemfile2() to specify the format of a file that is being opened.

This information is passed by Csound to a host's FileOpen callback and does not influence the opening operation in any other way. Conversion from Csound's TYP_XXX macros for audio formats to CSOUND_FILETYPES values can be done with csound->type2csfiletype().

Enumerator
CSFTYPE_UNIFIED_CSD 
CSFTYPE_ORCHESTRA 
CSFTYPE_SCORE 
CSFTYPE_ORC_INCLUDE 
CSFTYPE_SCO_INCLUDE 
CSFTYPE_SCORE_OUT 
CSFTYPE_SCOT 
CSFTYPE_OPTIONS 
CSFTYPE_EXTRACT_PARMS 
CSFTYPE_RAW_AUDIO 
CSFTYPE_IRCAM 
CSFTYPE_AIFF 
CSFTYPE_AIFC 
CSFTYPE_WAVE 
CSFTYPE_AU 
CSFTYPE_SD2 
CSFTYPE_W64 
CSFTYPE_WAVEX 
CSFTYPE_FLAC 
CSFTYPE_CAF 
CSFTYPE_WVE 
CSFTYPE_OGG 
CSFTYPE_MPC2K 
CSFTYPE_RF64 
CSFTYPE_AVR 
CSFTYPE_HTK 
CSFTYPE_MAT4 
CSFTYPE_MAT5 
CSFTYPE_NIST 
CSFTYPE_PAF 
CSFTYPE_PVF 
CSFTYPE_SDS 
CSFTYPE_SVX 
CSFTYPE_VOC 
CSFTYPE_XI 
CSFTYPE_UNKNOWN_AUDIO 
CSFTYPE_SOUNDFONT 
CSFTYPE_STD_MIDI 
CSFTYPE_MIDI_SYSEX 
CSFTYPE_HETRO 
CSFTYPE_HETROT 
CSFTYPE_PVC 
CSFTYPE_PVCEX 
CSFTYPE_CVANAL 
CSFTYPE_LPC 
CSFTYPE_ATS 
CSFTYPE_LORIS 
CSFTYPE_SDIF 
CSFTYPE_HRTF 
CSFTYPE_VST_PLUGIN 
CSFTYPE_LADSPA_PLUGIN 
CSFTYPE_SNAPSHOT 
CSFTYPE_FTABLES_TEXT 
CSFTYPE_FTABLES_BINARY 
CSFTYPE_XSCANU_MATRIX 
CSFTYPE_FLOATS_TEXT 
CSFTYPE_FLOATS_BINARY 
CSFTYPE_INTEGER_TEXT 
CSFTYPE_INTEGER_BINARY 
CSFTYPE_IMAGE_PNG 
CSFTYPE_POSTSCRIPT 
CSFTYPE_SCRIPT_TEXT 
CSFTYPE_OTHER_TEXT 
CSFTYPE_OTHER_BINARY 
CSFTYPE_UNKNOWN 

Enables Python interface.

ERROR DEFINITIONS

Enumerator
CSOUND_SUCCESS 
CSOUND_ERROR 
CSOUND_INITIALIZATION 
CSOUND_PERFORMANCE 
CSOUND_MEMORY 
CSOUND_SIGNAL