Testing Out a New STK Project

In the preceding section, we built the STK library and all the demos, and we tried out one of them (Physical.bat). In this section, we will create a new STK project and go through the steps of compiling, linking, and trying it out. Debugging programs using gdb is introduced in Appendix B.

The file myproj/README briefly describes the simple examples in its subdirectories. Let's focus for now on the echo example:

$ cd ~/stk/stk/myproj/echo
$ ls -F
Makefile  echo.cpp  test.wav
$ make echo
echo g++ -g -Wall -I../../include/  ...
g++ -g -Wall -I../../include/ ...
g++ -g -Wall -I../../include/ ... \\
    echo.cpp  ../../src/libstk.a -lpthread -lm  -o echo
$ \echo 2

Creating WAV file: echo.wav
8.009705 Seconds Computed

$ play echo.wav

(Since ``echo'' is a built-in command in the shell, our program echo must be quoted with back-slash, as shown above, or invoked as ./echo.) The command make test is equivalent to the last three commands above. Also, make test is the default ``make target'', so simply saying make will compile (if necessary) and test the program.

Figure A.2 lists the complete makefile for this example. As we see, most of the actual work is done in Makefile.proj in the parent directory. All we need in this makefile is the program name, any program arguments (the number 2 in this case), and the names of any additional object files to be compiled and linked with the main program (including the .o extension in each filename, separating filenames with space).

Figure A.2: Contents of the file echo/Makefile.

 

MAIN = echo
ARGS = 2
OFILES = 
include ../Makefile.proj

Figure A.3: Contents of the file echo/echo.cpp.

 

/* echo.cpp - simple test program for echo simulation. 
   Compatible with STK version 4.2.1.

   Usage:

     echo 2

   Plays the input soundfile (hard wired to test.wav) summed 
   with itself delayed by 2 seconds. You thus hear two 
   instances of the input sound separated by the echo delay.
   If not specified, the echo delay defaults to 1 second.  
   It can be any nonnegative real value.
*/
   
#include "FileWvIn.h"
#include "FileWvOut.h"
#include "Delay.h"
#include <stdlib.h> // for atof()
#include <math.h> // for floor()

int main(int argc,char *argv[])
{
  Delay *delayLine;    
  FileWvIn input("test.wav"); 
  FileWvOut output(argv[0]); // Writes main.wav
  double del = 1.0;
  if (argc>1) { del = atof(argv[1]); }
  long delsamps = (long)floor(del*sample_rate+0.5);
  delayLine = new Delay(delsamps,delsamps);
  long nsamps = input.getSize();
  for (long i=0;i<nsamps;i++)   {
    StkFloat insamp = input.tick();
    output.tick(0.5*insamp + 0.5*delayLine->tick(insamp));
  }
  for (long i=0;i<delsamps;i++)   {
    output.tick(0.5*delayLine->tick(0));
  }
  return(0);
}

Figure A.3 lists our example program, echo.cpp. Below is a description of how the program works:

• The first three lines include header files for three STK modules:
  • FileWvIn, which reads sound files,
  • FileWvOut, which writes sound files, and
  • Delay, which implements a digital delay line.
  In general, any time you want to use a class from the STK library, you need to include the header-file for that class so that its messages become defined in your program.
• Including standard C header files such as stdlib.h and math,h is routine C programming. To find out which C header file needs to be included for some C run-time utility such as floor or atof, check its man page near the top.
• Inside the main routine, we declare a Delay pointer, and instantiate the input/output soundfile reader/writer.
• The echo delay defaults to 1 second; otherwise it is set on the command line in typical C-programming fashion. Note the trick for implementing a rounding to the nearest integer using the floor function. (Your C compiler may have lround() defined, which would be more direct.)
• Now that we know the delay-line length, we can instantiate our Delay object at the desired size.
• Finally, we loop over the input samples, summing each input sample with the delay-line output, divided by 2.
• When the input file is exhausted, we loop again until the delay line is emptied.

Note that StkFloat is an STK typedef which is normally bound to type double. Also, every STK library class which processes or synthesizes sound has a method named tick, which computes one sample of sound per call. (It is also possible to operate on more than one sample at a time, as illustrated in the myproj/cla example. Additionally, several STK programming examples illustrate the handling of multiple channels, such as for stereo or quad (grep for tickFrame in projects/examples/*.cpp.)

The makefile in the myproj directory forwards the specified make target to all subdirectories listed in the makefile. For example, all of the examples in myproj can be compiled, linked, and tried out as follows:

$ cd ~/stk/stk/myproj
$ make

Similarly, all subdirectories can be ``cleaned up'' by typing make clean in the myproj directory.