fout, foutk, fouti, foutir, fiopen

          fout      "ifilename", iformat, aout1[, aout2, aout3,...,aoutN]
          foutk     "ifilename", iformat, kout1[, kout2, kout3,....,koutN]
          fouti     ihandle, iformat, iflag, iout1[, iout2, iout3,....,ioutN]
          foutir    ihandle, iformat, iflag, iout1[, iout2, iout3,....,ioutN]
  ihandle fiopen    "ifilename",imode

Description

fout, foutk, fouti and foutir output N a-, k-, or i-rate signals to a specified file of N channels. fiopen can be used to open a file in one of the specified modes.

Initialization

ifilename - a double-quote delimited string file name

iformat - a flag to choose output file format:

• for fout and foutk only:
  • 0 - 32-bit floating point samples without header (binary PCM multichannel file)
  • 1 - 16-bit integers without header (binary PCM multichannel file)
  • 2 - 16-bit integers with .wav type header (Microsoft WAV mono or stereo file)
• for fouti and foutir only:
  • 0 - floating point in text format
  • 1 - 32-bit floating point in binary format

iflag - choose the mode of writing to the ASCII file (valid only in ASCII mode; in binary mode iflag has no meaning, but it must be present anyway). iflag can be a value chosen among the following:

• 0 - line of text without instrument prefix
• 1 - line of text with instrument prefix (see below)
• 2 - reset the time of instrument prefixes to zero (to be used only in some particular cases. See below)

iout,..., ioutN - values to be written to the file

imode - choose the mode of opening the file. imode can be a value chosen among the following:

• 0 - open a text file for writing
• 1 - open a text file for reading
• 2 - open a binary file for writing
• 3 - open a binary file for reading

Performance

aout1,... aoutN - signals to be written to the file

kout1,...koutN - signals to be written to the file

fout (file output) writes samples of audio signals to a file with any number of channels. Channel number depends by the number of aoutN variables (i.e. a mono signal with only an a-rate argument, a stereo signal with two a-rate arguments etc.) Maximum number of channels is fixed to 64. Multiple fout opcodes can be present in the same instrument, referring to different files.

Notice that, unlike out, outs and outq, fout does not zero the audio variable, so you must zero it after calling fout, if polyphony is to be used. You can use incr and clear opcodes for this task.

foutk operates in the same way as fout, but with k-rate signals. iformat can be set only to 0 or 1.

fouti and foutir write i-rate values to a file. The main use of these opcodes is to generate a score file during a realtime session. For this purpose, the user should set iformat to 0 (text file output) and iflag to 1, which enable the output of a prefix consisting of the strings inum, actiontime, and duration, before the values of iout1...ioutN arguments. The arguments in the prefix refer to instrument number, action time and duration of current note.

The difference between fouti and foutir is that, in the case of fouti, when iflag is set to 1, the duration of the first opcode is undefined (so it is replaced by a dot). Whereas, foutir is defined at the end of note, so the corresponding text line is written only at the end of the current note (in order to recognize its duration). The corresponding file is linked by the ihandle value generated by the fiopen opcode (see below). So fouti and foutir can be used to generate a Csound score while playing a realtime session.

fiopen opens a file to be used by the fout family of opcodes. It must be defined in the header section, external to any instruments. It returns a number, ihandle, which is unequivocally referring to the opened file.

Notice that fout and foutk can use either a string containing a file pathname, or a handle-number generated by fiopen. Whereas, with fouti and foutir, the target file can be only specified by means of a handle-number.

Author

Gabriel Maldonado
Italy
1999
New in Csound version 3.56