p-fields and p-values

When Csound prepares to play an event in the score, it stores the data in the score line for the event in a series of variables. The values in the score can be accessed within the instrument using the symbols p1, p2, p3, and so forth. These symbols are unique and local to each event.

It’s legal to use these symbols directly in arguments to opcodes, like this:

  kampenv linen p4, 0.01, p3, 0.1

However, your code will be more readable, especially as you add more p-fields to your events, if you initialize named variables with the values in the p-fields, like this:

  idur = p3
  iamp = p4
  kampenv linen iamp, 0.01, idur, 0.1

If you accidentally use too many or too few p-fields in a score event, Csound will issue a warning message during playback. If you use a symbol, such as p5, for which no p-field exists in the score, Csound will initialize the value to 0.

Note Unlike an error message, a warning message from the Csound compiler will not prevent playback from starting and continuing. Warning messages can, however, tell you why you’re getting unexpected results from your score, so it’s a good idea to keep an eye on the Output Console while developing a piece.

The meanings of p1, p2, and p3 are fixed. p1 is the number of the instrument, p2 is the start time of the event (with reference to the current section of the score), and p3 is the duration of the event. Any subsequent p-fields have meanings that will be determined by your code.

The symbols beginning with p are variables, so their values can be changed by your instrument code while the instrument is playing. For most p-fields, this is a fairly trivial feature. However, changing the value of p3 in an instrument is meaningful: If you change p3, Csound will change the length of the event when it is being initialized.

This feature has a couple of possible uses. First, if you set a value for p3 in the instrument, the number you use will be an actual number of seconds, irrespective of the tempo defined by the score. Thus you can override the tempo within the instrument if you need an instrument to always play an event of a given length, irrespective of the current tempo. Second, the lengths of notes can be controlled interactively in performance (with a MIDI slider, for instance). Here’s a simple example that uses a global variable to set note length interactively:

  giSine ftgen 0, 0, 8192, 10, 1
  gkLength init 0.2

  instr 1
  gkLength line 0.2, p3, 2
  endin

  instr 11
  p3 = i(gkLength)
  asig oscil p4, p5, giSine
  outs asig, asig
  endin

  </CsInstruments>
  <CsScore>

  i1 0 5
  i11 0 1 0.2 220
  i11 +.. 330
  i11 +.. 440
  i11 +.. 550
  i11 +.. 660

Although the five notes to be played by instr 11 are all the same length in the score, each note will be longer than the preceding note when the score is played, because the value of p3 is being read from the variable gkLength, which is being ramped upward in instr 1.

A text string (surrounded by double-quotes) can be used in a p-field in the score. This feature can be used, for instance, to tell an instrument which sample to load from your hard drive into its own internal table. As of Csound 5.13, only one p-field can contain a string.