Print Statements
It sometimes happens, as you’re developing a Csound orchestra and score, that your code doesn’t behave the way you expect it to. Diagnosing the problem may take only a few seconds, or you may be tearing your hair out for an hour. (If the problem persists for longer than an hour, post a message to the email list asking for help, and then go take a long walk.)
To make the debugging process easier, Csound provides several printing opcodes. By inserting one or more of these in your code, you can inspect the values of variables as an instrument runs. This information will often reveal the source of the problem.
In CsoundQt, the print opcodes send their output to the Output Console pane, which can be displayed across the bottom of the main window. If you’re running Csound from the command line, the text output will normally appear in the Command Prompt (in Windows) or Terminal (in Mac OS) window.
The trick is to know which of the print opcodes to use. I’ve found that this can sometimes be a bit of a challenge. In addition, some of the print opcodes have specific formatting requirements. In the next few pages we’ll take a look at all of the options and requirements.
The print opcode runs at i-time, so it’s useful only for printing out the values of i-time variables. Here’s a not terribly useful example:
instr 1 idur = p3 iamp = p4 ifreq = p5 iresult = idur^iamp * ifreq print idur, iamp, ifreq, iresult endin </CsInstruments> <CsScore> i11 0 2 0.5 440
The print opcode prints the name of each variable along with its value, so you can string together any number of arguments to print and easily read the output. The output of the code above should look like this:
instr 1: idur = 2.000 iamp = 0.500 ifreq = 440.000 iresult = 622.254
If you ever need to use Csound as a pocket calculator, the print opcode will let you view the results of your calculations.
printf
The printf opcode prints a formatted string. It can run either in each k-period or at i-time; the i-time version is called printf_i. To see this opcode in action, return to the example above in the section on print, and substitute this line for the print line:
printf_i “iresult is %f ”, 1, iresult
Now the output will be:
iresult is 622.253967
The functionality of printf and printf_i is more complex than with print, so let’s look at the above code in detail. The first argument to these opcodes is a text string, in double-quotes. The second argument is a trigger. The trigger will cause printing whenever it’s not zero. The third and any following arguments to printf are the values that we want to print.
When using printf_i, there’s no harm in making the trigger 1, because an i-time opcode will run only once per score event (unless reinit is used to produce another initialization pass, or unless printf_i is being used within a loop). With printf, we need to create a trigger signal that is non-zero only when we want to see a new printout. This can be done in several ways. For instance, we could use a metro to issue triggers periodically, like this:
ktrig metro 5 printf “kresult is %f ”, ktrig, kresult
This code will cause printf to send a message to the console five times per second. This may not be the most efficient way to work; we can do the same thing using printks (see below) and skip the metro. But if a metro is already running, producing an output of 1 at periodic intervals, using its output with printf will cause a print operation to occur each time metro outputs a value of 1.
Conversion Specifiers and Output Formatting
The string argument above contains some mysterious characters: %f . The time has come to explain what those mean.
There are, in fact, two things going on here. %f is one thing; is a different thing. These symbols are borrowed from the C programming language. In C, they’re used in conjunction with the printf() command. As in Csound, printf() is used to output text to the console.
When used in a text string, the percent sign followed by a single character is called a conversion specifier. To learn more, you can do a web search for “printf() conversion specifier”. Various letters can follow the percent sign, and each of the allowed letters has a specific meaning. When a conversion specifier is used with one of the printing opcodes that accepts a text string as an argument, the string must be followed by one or more arguments containing numerical values. The conversion specifier tells the opcode to look at one of those arguments, incorporate its numerical value in the string, and format it in a specific way.
The most useful conversion specifiers in Csound coding are probably %f and %d. When printf sees %f, it prints the numerical argument as a floating-point number. When it sees a %d, it prints the argument as an integer. Conversion specifiers for exponential number display (%e) and hexadecimal (%x) are also available, among others.
The number of conversion specifiers in a string must match the number of numerical arguments that follow the string (ignoring any other arguments, such as trigger inputs, that the opcode may require). If there are too many arguments or too few, Csound will issue an error message.
Note If you want to print an actual percent sign in a string, use a percent sign followed by another one: %%.
The backslash () is an escape character. Like the percent sign, the backslash gives a special meaning to the next character, but in this case the meanings have to do with how the text output is formatted. prints an invisible newline character, which causes the output to jump down to the next line (and also return to the left margin, which is not quite the same thing). prints a tab character (a fixed-width space). A backslash followed by a double-quote character prints a double-quote character, and a backslash followed by another backslash prints a backslash.
printk
If you want to observe the changing values of a k-rate variable but you don’t need to print a string (presumably because you know what variable you’re watching), you can do it with printk. The prototype is:
printk itime, kval [, ispace]
The first argument is the time in seconds between printings. kval is the value to be printed. The optional ispace argument is supposed to control the number of spaces between outputs, but in fact this seems not to be useful. Even without a value for ispace, printk formats its output nicely, with a column of times at which the printing occurs followed by a column of output values.
printk2
According to the manual, printk2 is useful “for monitoring MIDI control changes when using sliders.” This makes sense, as printk2 produces a new printout each time the value you’re printing changes. If you use it to monitor a signal that is changing continuously at k-rate, you’ll see a whole lot of messages!
printk2 takes two arguments—the variable to be printed and the number of spaces between printouts. Again, the output seems (in my tests, at any rate) to be formatted with one print statement per line, so specifying the number of spaces is not very useful.
printks
printks uses the same string-formatting conventions as printf (see above). The main difference between the two is that in place of a trigger argument, printks lets you specify the amount of time (in seconds) between printings. For example:
kramp line 1, p3, 2 printks “The ramp value is %f ”, 0.1, kramp
The value 0.1 will cause a printing every 1/10 second. Csound will not format the output for you, so a is highly useful for getting each printout onto a line by itself.
prints
prints is functionally identical to printf_i, except that it has no argument for a trigger. It runs at init-time and prints out a string that can include C-style conversion specifiers for numerical arguments.
sprintf
The syntax of sprintf is similar to that of printf, but sprintf doesn’t output anything to the console. Its output is, instead, a string variable (prefix S-), which can then be used for various purposes, such as sending text strings to widgets using the outvalue opcode.