Csound

OPCODE GUIDE: DATA

  • BUFFER / FUNCTION TABLES

    See the chapter about function tables for more detailed information. 

    • Creating Function Tables (Buffers)

      ftgen can generates function tables from within the orchestra. The function table will exist until the end of the current Csound performance. Different GEN Routines are used to fill a function table with different kinds of data. This could be waveforms, sound files, envelopes, window functions and so on.

    • Writing To Tables

      tableiw / tablew: Write values to a function table at i-rate (tableiw), k-rate and a-rate (tablew). These opcodes provide many options and are robust in use as they check for user error in defining table reading index values. They may however experience problems with non-power-of-two table sizes.

      tabw_i / tabw: Write values to a function table at i-rate (tabw_i), k-rate or a-rate (tabw). These opcodes offer fewer options than tableiw and tablew but will work consistently with non-power-of-two table sizes. They do not provide a boundary check on index values given to them which makes them fast but also then demands user responsibility in protecting against invalid index values.

    • Reading From Tables 

      table / tablei / table3: Read values from a function table at any rate, either by direct indexing (table), or by linear interpolation (tablei) or cubic interpolation (table3). These opcodes provide many options and are robust in use as they check for user error in defining table reading index values. They may however experience problems with non-power-of-two table sizes.

      tab_i / tab: Read values from a function table at i-rate (tab_i), k-rate or a-rate (tab). They offer no interpolation and fewer options than the table opcodes but they will also work with non-power-of-two table sizes. They do not provide a boundary check which makes them fast but also give the user the responsibility not to read any value beyond the table boundaries.

    • Saving Tables to Files

      ftsave / ftsavek: Save a function table as a file, at i-time (ftsave) or at k-rate (ftsavek). These files can be text files or binary files but not sound files. To save a table as a sound file you can use the user defined opcode TableToSF

    • Reading Tables From Files

      ftload / ftloadk: Load a function table which has previously been saved using ftsave/ftsavek.

      GEN23 transfers the contents of a text file into a function table. 

  • SIGNAL INPUT/OUTPUT, SAMPLE AND LOOP PLAYBACK, SOUNDFONTS

    • Signal Input And Output

      inch read the audio input from any channel of your audio device. Make sure you have the nchnls value in the orchestra header set properly.

      outch writes any audio signal(s) to any output channel(s). If Csound is in realtime mode (by the flag '-o dac' or by the 'Render in Realtime' mode of a frontend like QuteCsound), the output channels are the channels of your output device. If Csound is in 'Render to file' mode (by the flag '-o mysoundfile.wav' or the the frontend's choice), the output channels are the channels of the soundfile which is being written. Make sure you have the nchnls value in the orchestra header set properly to get the number of channels you wish to have.

      out and outs are frequently used for mono and stereo output. They always write to channel 1 (out) or channels 1 and 2 (outs).

      monitor can be used (in an instrument with the highest number) to gather the sum of all audio on all output channels.

    • Sample Playback With Optional Looping

      flooper2 is a function table based crossfading looper.

      sndloop records input audio and plays it back in a loop with user-defined duration and crossfade time.

      Note that there are additional user defined opcodes for the playback of samples stored in buffers / function tables.

    • Soundfonts And Fluid Opcodes

      fluidEngine instantiates a FluidSynth engine.

      fluidSetInterpMethod sets an interpolation method for a channel in a FluidSynth engine.

      fluidLoad loads SoundFonts.

      fluidProgramSelect assigns presets from a SoundFont to a FluidSynth engine's MIDI channel.

      fluidNote plays a note on a FluidSynth engine's MIDI channel.

      fluidCCi sends a controller message at i-time to a FluidSynth engine's MIDI channel.

      fluidCCk sends a controller message at k-rate to a FluidSynth engine's MIDI channel.

      fluidControl plays and controls loaded Soundfonts (using 'raw' MIDI messages).

      fluidOut receives audio from a single FluidSynth engine.

      fluidAllOut receives audio from all FluidSynth engines.

  • FILE INPUT AND OUTPUT

    • Sound File Input 

      soundin reads from a sound file (up to 24 channels). It is important to ensure that the sr value in the orchestra header matches the sample rate of your sound file otherwise the sound file will play back at a different speed and pitch.

      diskin is like soundin, but can also alter the speed of reading also resulting in higher or lower pitches. There is also the option to loop the file.

      diskin2 is similar to diskin, but it automatically converts the sample rate of the sound file if it does not match the sample rate of the orchestra. It also offers different interpolation methods to implement different levels of sound quality when sound files are read at altered speeds.

      GEN01 loads a sound file into a function table (buffer).

      mp3in facilitates the playing of mp3 sound files.
    • Sound File Queries 

      filelen returns the length of a sound file in seconds.

      filesr returns the sample rate of a sound file.

      filenchnls returns the number of channels of a sound file.

      filepeak returns the peak absolute value of a sound file, either of one specified channel, or from all channels. Make sure you have set 0dbfs to 1; otherwise you will get values relative to Csound's default 0dbfs value of 32768.

      filebit returns the bit depth of a sound file.

    • Sound File Output 

      Keep in mind that Csound always writes output to a file if you have set the '-o' flag to the name of a sound file (or if you choose 'render to file' in a front-end like QuteCound).

      fout writes any audio signal(s) to a file, regardless of whether Csound is in realtime or non-realtime mode. This opcode is recommended for rendering a realtime performance as a sound file on disc.

    • Non-Soundfile Input And Output 

      readk can read data from external files (for instance a text file) and transform them to k-rate values.

      GEN23 transfers a text file into a function table.

      dumpk writes k-rate signals to a text file.

      fprints / fprintks write any formatted string to a file. If you call this opcode several times during one performance, the strings are appended. If you write to an pre-existing file, the file will be overwritten.

      ftsave / ftsavek: Save a function table as a binary or text file, in a specific format.

      ftload / ftloadk: Load a function table which has been written by ftsave/ftsavek.

  • CONVERTERS OF DATA TYPES

    • i <- k 

      i(k) returns the value of a k-variable at init-time. This can be useful to get the value of GUI controllers, or when using the reinit feature.

    • k <- a 

      downsamp converts an a-rate signal to a k-rate signal, with optional averaging.

      max_k returns the maximum of an k-rate signal in a certain time span, with different options of calculation
    • a <- k

      upsamp converts a k-rate signal to an a-rate signal by simple repetitions. It is the same as the statement asig=ksig.

      interp converts a k-rate signal to an a-rate signal by interpolation.

  • PRINTING AND STRINGS

    • Simple Printing 

      print is a simple opcode for printing i-variables. Note that the printed numbers are rounded to 3 decimal places.

      printk is its counterpart for k-variables. The itime argument specifies the time in seconds between printings (itime=0 means one printout in each k-cycle which is usually some thousand printings per second).

      printk2 prints a k-variable whenever it changes.

      puts prints S-variables. The ktrig argument lets you print either at i-time or at k-rate.

    • Formatted Printing 

      prints lets you print a format string at i-time. The format is similar to the C-style syntax but there is no %s format, therefore string variables cannot can be printed.

      printf_i is very similar to prints. It also works at init-time. The advantage in comparision to prints is the ability of printing string variables. On the other hand,  you need a trigger and at least one input argument.

      printks is like prints, but takes k-variables, and like printk, you must specify a time between printing.

      printf is like printf_i, but works at k-rate.

    • String Variables 

      sprintf works like printf_i, but stores the output in a string variable, instead of printing it out.

      sprintfk is the same for k-rate arguments.

      strset links any string with a numeric value.

      strget transforms a strset number back to a string.

    • String Manipulation And Conversion

      There are many opcodes for analysing, manipulating and converting strings. There is a good overview in the Canonical Csound Manual on this and that page.