Programming Assignment Checklist: Plucking a Guitar String

Frequently Asked Questions

What are the goals of this assignment? To learn how to create user-defined data types in Java and to learn about digital audio.

Do I need to follow the prescribed API? Yes, we will be testing the methods in the API directly. If your method has a different signature or does not behave as specified, you will lose a substantial number of points. You may not add public methods to the API; however, you may add private instance variables or methods (which are only accessible in the class in which they are declared).

Where do I enter keystrokes in GuitarHeroLite and GuitarHero? Be sure that the standard draw window has focus by clicking in it. Then, type the keystrokes.

How do I determine the length of an array? If you're asking this, you probably need to review Section 1.4.

Is the size of a RingBuffer equal to the number of nonzeros? No. Some of the elements in the buffer can be zero. To get an accurate count, increment the instance variable size each time you call enqueue() and decrement it each time you call dequeue().

How do I throw a RuntimeException? Read the Exceptions paragraph on page 446 and see the examples in Vector.java (but you'll need to pick your own short description string).

When generating random values between -0.5 and +0.5 in should I include the endpoints? You are free to choose whatever convention you find most convenient. The inclusion or exclusion of the endpoints makes no humanly discernable difference in the sound, but the inclusion of exactly one endpoint makes the implementation of the method very simple.

How do I round a double up to the nearest int? Why must we use this approach? Use the ceiling function static double Math.ceil(double x) and then cast the result to an integer. The reason for using this is that it causes the natural resonance frequency of your guitar string's ring buffer to be as close as possible to the desired one.

What happens if I call StdAudio.play(x) where x is greater than 1 or less than -1? The value is clipped—it is replaced by the value 1.0 or -1.0, respectively.

I get an ArrayOutOfBounds or NullPointerException error in RingBuffer. What could cause this? Does your constructor correctly initialize all of the instance variables? Did you allocate memory for your array? Did you inadvertently redeclare an instance variable in a method or constructor, thereby shadowing the instance variable with the same name?

I get a RuntimeException or an out-of-bounds error in GuitarHeroLite before I type any keystrokes. Why? Did you forget to initialize the ring buffer to contain N zeros in your GuitarString constructor?

When I run GuitarHeroLite for the first time, I hear no sound. What am I doing wrong? Make sure you have tested with the main() provided for GuitarString. If that works, it is likely something wrong with pluck() since the main() provided for GuitarString does not test that method. To diagnose the problem, print out the values of sample() and check that they become nonzero after you type lower case characters 'a' and 'c'.

When I run GuitarHeroLite, I hear static (either just one click, and then silence or continual static). What am I doing wrong? It's likely that pluck() is working, but tic() is not. The best test is to run the main() provided for GuitarString.

How do I use keyboard.indexOf(key)? If keyboard is a String and key is a character, then keyboard.indexOf(key) returns the integer index of the first occurrence of the character key in the string keyboard, or –1 if it does not occur. You can read about it in the String Javadoc page.

Can I hardwire the constants 44,100, 110.0, 440.0, 880.0, and 37 in my program? As usual, we will deduct style points if you use an unnamed constant (such as 37) in your program more than once. We recommend using the name SAMPLING_RATE for 44,100 and CONCERT_A for 440. But you need not name all of the constants in the formula 2^{(i - 24) / 12}.

When I run from DrJava, even though I have clicked in the StdDraw window, the program seems to ignore my keystrokes. What is wrong? Try clicking on DrJava, then clicking in the StdDraw window, again. If that does not work, close the StdDraw window and run from Terminal or Command Prompt.

Testing

Be sure to thoroughly test each piece of your code as you write it. We offer some suggestions below, but these are only partial tests. Write code to test each constructor and each method of each class, especially in RingBuffer.

Ring buffer. You can test your RingBuffer data type on the following toy client, using the main() provided. It enqueues the numbers 1 through N, and then repeatedly dequeues the first two, and enqueues their sum.


  public static void main(String[] args) {
      int N = Integer.parseInt(args[0]);
      RingBuffer buffer = new RingBuffer(N);  
      for (int i = 1; i <= N; i++) {
          buffer.enqueue(i);
      }
      double t = buffer.dequeue();
      buffer.enqueue(t);
      System.out.println("Size after wrap-around is " + buffer.size());
      while (buffer.size() >= 2) {
          double x = buffer.dequeue();
          double y = buffer.dequeue();
          buffer.enqueue(x + y);
      }
      System.out.println(buffer.peek());
  }

% java-introcs RingBuffer 10
Size after wrap-around is 10
55.0


% java-introcs RingBuffer 100
Size after wrap-around is 100
5050.0

Guitar string. You can test your GuitarString data type with the following toy client, using the main() provided.


  public static void main(String[] args) {
      int N = Integer.parseInt(args[0]);
      double[] samples = { .2, .4, .5, .3, -.2, .4, .3, .0, -.1, -.3 };  
      GuitarString testString = new GuitarString(samples);
      for (int i = 0; i < N; i++) {
          int t = testString.time();
          double sample = testString.sample();
          System.out.printf("%6d %8.4f\n", t, sample);
          testString.tic();
      }
  }

% java-introcs GuitarString 25
     0   0.2000
     1   0.4000
     2   0.5000
     3   0.3000
     4  -0.2000
     5   0.4000
     6   0.3000
     7   0.0000
     8  -0.1000
     9  -0.3000
    10   0.2988
    11   0.4482
    12   0.3984
    13   0.0498
    14   0.0996
    15   0.3486
    16   0.1494
    17  -0.0498
    18  -0.1992
    19  -0.0006
    20   0.3720
    21   0.4216
    22   0.2232
    23   0.0744
    24   0.2232

Using your implementations of the RingBuffer and GuitarString classes compile and run GuitarHeroLite.

Guitar Hero. Type the following into your guitar to get the beginning of Led Zeppelin's Stairway to Heaven. Multiple notes in a column are dyads and chords.

                                              w q q
        8       u       7       y             o p p
i p z v b z p b n z p n d [ i d z p i p z p i u i i

What is this familiar melody? (S = space)

nn//SS/ ..,,mmn //..,,m //..,,m nn//SS/ ..,,mmn

Here is a round that you can practice with 3 friends:

x c v x x c v x v g n   v g n   nmngv x nmngv x x p x   x p x
                x c v x x c v x v g n   v g n   nmngv x nmngv x x p x   x p x
                                x c v x x c v x v g n   v g n   nmngv x nmngv x x p x   x p x
                                                x c v x x c v x v g n   v g n   nmngv x nmngv x x p x   x p x

Possible Progress Steps

These are purely suggestions for how you might make progress. You do not have to follow these steps.

Download the files for this week, including the readme.txt and GuitarHeroLite.java from the assignment page. Additionally, we provide optional templates for RingBuffer.java and GuitarString.java. Like the LFSR assignment, use them in part or full if you see fit. You are not required to use the representations therein, but whatever representation you choose cannot be too inefficient, as it will be used 44100 times per second.
Review the material in the textbook on digital audio (pp. 147-151, 202-206).

We recommend defining the instance variables as follows:

public class RingBuffer {
    private double[] rb;          // items in the buffer
    private int first;            // index for the next dequeue or peek
    private int last;             // index for the next enqueue
    private int size;             // number of items in the buffer
}

The design of your program should look like the template for RingBuffer.java, except that you will need to fill in all of the constructors and methods.
Your constructor for RingBuffer will need to allocate and initialize an array of double using new. Observe that you have to do this in the constructor (and not when you declare the instance variables) since otherwise you wouldn't know how big to make the array.
Develop RingBuffer in an incremental and iterative manner: implement a contructor/method, and then test it in main(). Test using some small examples, perhaps a RingBuffer of size 4. Use might also want to implement a private helper method that prints a RingBuffer object, i.e., prints the current values for first, last and size. This can be very useful to help you debug!
After you implement all the methods for RingBuffer, your first test should be to run it using the given test code in main(), but that should not be your only test.
Start the guitar string class with the template for GuitarString.java. It contains one of the private instance variables that you will need, and all of the constructors and methods ready to be filled in. The constructors will both initialize the instance variables and use enqueue().
To implement pluck(), use a combination of RingBuffer methods including dequeue() and enqueue() to replace the buffer with values between -0.5 and 0.5.
To implement tic(), use a combination of enqueue(), dequeue(), and peek().
To implement sample(), use peek().
After you implement the methods for GuitarString, your first test should be to run GuitarString using the given test code in main(). Which constructor and methods does this test? Fix any problems.
Now test using GuitarHeroLite. Which additional constructor and method does that test?
When you have GuitarString.java working, change the program GuitarHeroLite.java to GuitarHero.java, by creating an array of notes.

Enrichment

ChucK. ChucK as specialized programming language for real-time synthesis, composition, and performance originated by Ge Wang and Perry Cook at Princeton University. Here's the Karplus-Strong algorithm in ChucK.
Slide flute. Here's a description of a physically modeled slide flute by Perry Cook.
Electric guitar synthesis. In COS 325, Charlie Sullivan '87 extended the Karplus-Strong algorithm to synthesize electric guitar timbres with distortion and feedback. Here's his Jimi Hendrix-ified version of the The Star Spangled Banner.