Description

Macros are textual replacements which are made in the orchestra as it is being read. The orchestra macro system in Csound is a very simple one, and uses the characters # and $ to define and call macros. This can save typing, and can lead to a coherent structure and consistent style. This is similar to, but independent of, the macro system in the score language.

Includes an external file for processing.

Syntax

#include “filename”

#includestr “filename”

Performance

#includestr is similar to #include except that the file name must be delimited by a double quote character and the file name is subjected to macro expansion.

It is sometimes convenient to have the orchestra arranged in a number of files, for example with each instrument in a separate file. This style is supported by the #include facility which is part of the macro system. A line containing the text

#include "filename"

where the character " can be replaced by any suitable character in #include (but not in #includestr). For most uses the double quote symbol will probably be the most convenient. The file name can include a full path.

This takes input from the named file until it ends, when input reverts to the previous input. Note: Csound versions prior to 4.19 had a limit of 20 on the depth of included files and macros.

Another suggested use of #include would be to define a set of macros which are part of the composer's style.

An extreme form would be to have each instrument defines as a macro, with the instrument number as a parameter. Then an entire orchestra could be constructed from a number of #include statements followed by macro calls.

#include "clarinet"
#include "flute"
#include "bassoon"
$CLARINET(1)
$FLUTE(2)
$BASSOON(3)

It must be stressed that these changes are at the textual level and so take no cognizance of any meaning.

If the version of Csound is built with the CURL library the filename in an #include statement can be an URL, recognised by including the substring "://" in the name. This will include text via protocols such as http, https, and ftp.

Examples

Here is an example of the include opcode. It uses the file include.csd, and table1.inc.

/* table1.inc */
; Table #1, a sine wave.
f 1 0 16384 10 1
/* table1.inc */

<CsoundSynthesizer>
<CsOptions>
; Select audio/midi flags here according to platform
; Audio out   Audio in
-odac           -iadc    ;;;RT audio I/O
; For Non-realtime ouput leave only the line below:
; -o include.wav -W ;;; for file output any platform
</CsOptions>
<CsInstruments>

sr = 44100
kr = 4410
ksmps = 10
nchnls = 1

; Instrument #1 - a basic oscillator.
instr 1
  kamp = 10000
  kcps = 440
  ifn = 1

  a1 oscil kamp, kcps, ifn
  out a1
endin


</CsInstruments>
<CsScore>

; Include the file for Table #1.
#include "table1.inc"

; Play Instrument #1 for 2 seconds.
i 1 0 2
e


</CsScore>
</CsoundSynthesizer>

See Also

#define, $NAME, #ifdef, #ifndef, #undef

Credits

#includestr new in version 6.12

Example written by Kevin Conder.

New in Csound version 3.48

URLs available from Csound 6.02