Programming Assignment Checklist: Plucking a Guitar String

Frequently Asked Questions (general)

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).

Frequently Asked Questions (RingBuffer)

Which instance variables should I use to represent a RingBuffer? There are many viable approaches, including one suggested in the assignment specification. Be sure that your representation allows you to implement each operation efficiently (because the GuitarHero client will call the methods 44,100 times per second).

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 its capacity? No. The size of a RingBuffer is the number of elements currently in it; the capacity of a RingBuffer is its maximum possible size.

Is the size of a RingBuffer equal to the number of its nonzeros elements? No. Some of the elements in the buffer can be zero.

How do I throw a RuntimeException with a custom message? Read the Exceptions paragraph on pp. 465–466 of the textbook.

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

I get the following error message on OS X. How can I fix it?

This application, or a library it uses, is using the deprecated Carbon Component Manager
for hosting Audio Units. Support for this will be removed in a future release.

You can ignore it. It is a warning intended for the authors of the Mac OS X Java sound library.

Frequently Asked Questions (GuitarString)

When generating random values between −0.5 and +0.5, should I include the two endpoints? The assignment specification does not specify, so you are free to choose whichever convention you find most convenient. In Java, we typically include the left endpoint of an interval and exclude the right endpoint. For example, StdRandom.uniform(-0.5, 0.5) generates a uniformly random value in the interval [−0.5, 0.5) and s.substring(i, j) returns the substring of the string s beginning at index i and ending at index j-1.

How do I round a double up to the nearest int? Use Math.ceil() and cast the result to an integer.

Frequently Asked Questions (GuitarHero)

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

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

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. This is fine and can happen when you play chords.

I get a RuntimeException or an ArrayIndexOutOfBoundsException 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 the values of sample() and check that they become nonzero after you type the lowercase 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, 440.0, and 37 in my program? As usual, we may deduct style points for using an unnamed constant, especially if you use it more than once. We recommend using the name SAMPLING_RATE for 44,100 and CONCERT_A for 440.0 and the expression keyboard.length() for 37. You do not need to name all of the constants in the formula 2^{(i − 24) / 12}.

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 main(). 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 main():


  public static void main(String[] args) {
      double[] samples = { 0.2, 0.4, 0.5, 0.3, -0.2, 0.4, 0.3, 0.0, -0.1, -0.3 };  
      GuitarString testString = new GuitarString(samples);
      int m = 25; // 25 tics
      for (int i = 0; i < m; i++) {
          double sample = testString.sample();
          System.out.printf("%6d %8.4f\n", i, sample);
          testString.tic();
      }
  }

% java-introcs GuitarString
     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

Next, using your implementations of RingBuffer and GuitarString, compile and execute 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 (RingBuffer)

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.
Review the material in the textbook on digital audio (pp. 147–151, 202–206).
Start with the RingBuffer.java template. You will need to fill in the instance variables, constructors, and instance methods.

As indicated in the assignment specification, we recommend defining the instance variables as follows:

    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

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) because you don't know the length of the array until the constructor is called.
Develop RingBuffer in an incremental and iterative manner: implement one method at a time, together with a corresponding test in main(). Test using some small examples, perhaps a RingBuffer of capacity 4. You 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, test it using the test client in the testing section. Do not proceed until you have throughly tested your RingBuffer data type.

Possible Progress Steps (GuitarString)

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

Start with the GuitarString.java template. You will need to fill in the instance variables, constructors, and instance methods.
The constructors should initialize the instance variables. You can call the enqueue() method to do so.
Implement the GuitarString(double frequency) constructor.
Implement the length() method.
Implement the sample() method. Use peek().
Test: In main, test the GuitarString(double frequency) constructor:
1. Instantiate a few different GuitarString objects.
2. Invoke length() on each object. Is the value returned by length what you expect?
3. Invoke sample() on each object. Is the value returned by sample what you expect?
Implement the GuitarString(double[]) constructor.
Test: In main, test the GuitarString(double[]) constructor:
1. Instantiate a few different GuitarString objects.
2. Invoke length() on each object. Is the value returned by length what you expect?
3. Invoke sample() on each object. Is the value returned by sample what you expect?
Implement pluck(). Use a combination of RingBuffer methods including dequeue() and enqueue() to replace the buffer with values between −0.5 and 0.5.
Test: In main:
1. Instantiate a GuitarString object.
2. Invoke length() and sample() on this object.
3. Next invoke pluck() on this object.
4. Next invoke length() and sample() again on each object. Are the values returned what you expect?
5. Try this with a few GuitarString objects.
Implement tic(). Use a combination of enqueue(), dequeue(), and peek().
Test: In main:
1. Instantiate a GuitarString object.
2. Invoke length() and sample() on this object.
3. Next invoke tic() on this object.
4. Next invoke length() and sample() again on each object. Are the values returned what you expect?
5. Try this with a few GuitarString objects.
After you implement the methods for GuitarString, run GuitarString using the test client in the testing section.
Now test using GuitarHeroLite. Which additional constructor and method does that test?

Possible Progress Steps (GuitarHero)

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

To develop GuitarHero.java, use GuitarHeroLite.java as a starting point.
Create an array of GuitarString objects. Remember, to create an array of objects, you need to create the array, then you need to create each individual object.
Can you play individual notes? Do the notes have the correct frequencies? Can you play a chord?

Enrichment

Here are some concrete ideas for synthesizing other instruments. Some come from the paper of Karplus and Strong.

Harp strings: Flipping the sign of the new value before enqueueing it in tic() will change the sound from guitar-like to harp-like. You may want to play with the decay factors to improve the realism, and adjust the buffer sizes by a factor of two since the natural resonance frequency is cut in half by the tic() change.
Drums: Flipping the sign of a new value with probability 0.5 before enqueueing it in tic() will produce a drum sound. A decay factor of 1.0 (no decay) will yield a better sound, and you will need to adjust the set of frequencies used.
Guitars play each note on one of six physical strings. To simulate this you can divide your GuitarString instances into 6 groups, and when a string is plucked, zero out all other strings in that group.
Pianos come with a damper pedal which can be used to make the strings stationary. You can implement this by, on iterations where a certain key (such as Shift) is held down, changing the decay factor.
While we have used equal temperament, the ear finds it more pleasing when musical intervals follow the small fractions in the just intonation system. For example, when a musician uses a brass instrument to play a perfect fifth harmonically, the ratio of frequencies is 3/2 = 1.5 rather than 2^7/12 ∼ 1.498. Write a program where each successive pair of notes has just intonation.

Here is some cool stuff that is closely related.

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.