7. Guitar Hero

Implementing RingBuffer.java

1. You will need to define the instance variables, constructors, and instance methods.

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

3. Your constructor for RingBuffer will need to allocate and initialize an array of doubles using the new operator. Observe that you have to do this in the constructor (and not when you declare the instance variables) because you do not know the length of the array until the constructor is called.

4. Implement RingBuffer in an incremental and iterative manner: implement one method at a time, together with a corresponding test in main().

   • In main(), write some tests using small examples, for example, using a RingBuffer of capacity four (4) based on the worksheet.
   • You can 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!

5. After you implement all the methods for RingBuffer, test RingBuffer using the test client in the Testing section. Do not proceed until you have thoroughly tested your RingBuffer data type.

Is the size of a RingBuffer equal to its capacity? The size is the number of elements currently in it; the capacity is its maximum possible size.

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

How do I throw a IllegalStateException with a custom message? Read the Exceptions paragraph on pages 465–466 of the textbook. Also, see the precept exercises for examples.

I get an ArrayIndexOutOfBoundsException 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?

Testing Your RingBuffer.java Implementation

These provided tests only test the functionality of your code. The final main() that you submit should test all the public methods of that data type’s API.

You can test your RingBuffer abstract data type using the following main(). Note - this test is not exhaustive, but it should help you debug.

int n = Integer.parseInt(args[0]);
RingBuffer buffer = new RingBuffer(n);

StdOut.printf("Test #1 - check capacity - should be %d\n", n);
StdOut.printf("**** Capacity is %d\n", buffer.capacity());

StdOut.printf("Test #2 - check size - should be %d\n", 0);
StdOut.printf("**** Size is %d\n", buffer.size());

for (int i = 1; i <= n; i++) {
    buffer.enqueue(i);
    StdOut.printf("Test #3.%d - check size after %d enqueues- should be %d\n",
                  i, i, i);
    StdOut.printf("**** Size is %d\n", buffer.size());
}

double val1 = buffer.peek();
StdOut.printf("Test #4 - check peek value == %.1f\n", 1.0);
StdOut.printf("**** Value is %.1f\n", val1);

double val2 = buffer.dequeue();
StdOut.printf("Test #5 - dequeue a value, then check value == %.1f and "
                      + "size == %d after a dequeue\n", 1.0, n - 1);
StdOut.printf("**** Value is %.1f\n", val2);
StdOut.printf("**** Size is %d\n", buffer.size());

buffer.enqueue(val2);
while (buffer.size() >= 2) {
    double x = buffer.dequeue();
    double y = buffer.dequeue();
    buffer.enqueue(x + y);
}
StdOut.printf("Test #6 - enqueues + dequeues, then check size == %d and"
                      + " peek == %.1f\n",
              1, (double) (n + 1) * n / 2);
StdOut.printf("**** Size is %d\n", buffer.size());
StdOut.printf("**** Peek value is %.1f\n", buffer.peek());

You can run this test by trying various RingBuffer sizes, for example, from the command line:

> java-introcs RingBuffer 1
> java-introcs RingBuffer 2
> java-introcs RingBuffer 3
> java-introcs RingBuffer 4
...

Implementing GuitarString.java

1. You will need to define the instance variables, constructors, and instance methods.
2. Implement the GuitarString(double frequency) constructor, which creates a RingBuffer of the desired capacity n (the sampling rate 44,100 divided by the frequency, rounded up to the nearest integer), and initializes it to represent a guitar string at rest by enqueuing n zeros. (Use Math.ceil and cast the result to an integer.)
3. Implement the length() method, which returns the number of samples in the ring buffer.
4. Implement the sample() method, which returns the value of the item at the front of the ring buffer. Use peek().

How can I test the constructor and these methods?

• In main(), instantiate a few different GuitarString objects using the GuitarString(double frequency) constructor.
• Invoke length() on each GuitarString object. Is the value returned by length() what you expect?
• Invoke sample() on each GuitarString object. Is the value returned by sample() what you expect?

5. Implement the GuitarString(double[]) constructor, which creates a RingBuffer of capacity equal to the length n of the array, and initializes the contents of the ring buffer to the corresponding values in the array. In this assignment, this constructor’s primary purpose is to facilitate testing and debugging.

How can I test the constructor and these methods?

• Instantiate a few different GuitarString objects using the GuitarString(double frequency) constructor.
• Invoke length() on each GuitarString object. Is the value returned by length() what you expect?
• Invoke sample() on each GuitarString object. Is the value returned by sample() what you expect?

6. Implement pluck(), which replaces the n items in the ring buffer with n random values between −0.5 and +0.5. Use a combination of RingBuffer methods including dequeue() and enqueue() to replace the buffer with values between −0.5 and 0.5. Hint: StdRandom

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.uniformDouble(-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 can I test the constructor and these methods?

• Instantiate a GuitarString object.
• Invoke length() and sample() on this object.
• Next invoke pluck() on this object. Next invoke length() and sample() again on each object. Are the values returned what you expect? Try this with a few GuitarString objects.

7. Implement tic(). Use the enqueue(), dequeue(), and peek() methods. This method applies the Karplus–Strong update: delete the first sample from the ring buffer and adds to the end of the ring buffer the average of the deleted sample and the first sample, scaled by an energy decay factor.

How can I test the constructor and these methods?

• Instantiate a GuitarString object.
• Invoke length() and sample() on this object.
• Next invoke tic() on this object.
• Next invoke length() and sample() again on each object. Are the values returned what you expect?
• Try this with a few GuitarString objects.

8. After you have implemented and tested each of the methods for GuitarString, run GuitarString using the test client in the Testing section.

Testing Your GuitarString.java Implementation

You can test your GuitarString abstract data type using the following main(). Note - this test is not exhaustive, but it should help you debug.

int n = Integer.parseInt(args[0]);
GuitarString gs1 = new GuitarString(n);
StdOut.printf("Test #1 - check length based on given n == %d\n", n);
StdOut.printf("**** Length is %d\n", gs1.length());

StdOut.printf("Test #2 - check sample is %.1f\n", 0.0);
StdOut.printf("**** Sample is %.1f\n", gs1.sample());

double[] samples = { -0.7, +0.8, -0.9, +0.6 };
GuitarString gs2 = new GuitarString(samples);
int len = samples.length;
StdOut.printf("Test #3 - check length based on given samples == %d\n",
              len);
StdOut.printf("**** Length is %d\n", gs2.length());

StdOut.printf("Test #4 - check sample is %.2f\n", samples[0]);
StdOut.printf("**** Sample is %.2f\n", gs2.sample());

gs2.pluck();
StdOut.printf("Test #5 - check length after pluck is still == %d\n",
              len);
StdOut.printf("**** Length is %d\n", gs2.length());

StdOut.printf("Test #6 - check sample is range [-0.5..+0.5)\n");
StdOut.printf("**** Sample is %.2f\n", gs2.sample());

GuitarString gs3 = new GuitarString(samples);
StdOut.printf("Test #7 - check sample is %.2f\n", samples[0]);
StdOut.printf("**** Sample is %.1f\n", gs3.sample());
gs3.tic();
StdOut.printf("Test #8 - check sample is %.2f\n", samples[1]);
StdOut.printf("**** Sample is %.2f\n", gs3.sample());

int m = 25; // number of tics
double[] moreSamples = { 0.2, 0.4, 0.5, 0.3, -0.2, 0.4, 0.3, 0.0, -0.1, -0.3 };
StdOut.printf("Test #9 - test %d tics\n", m);
GuitarString gs4 = new GuitarString(moreSamples);
for (int i = 0; i < m; i++) {
    double sample = gs4.sample();
    StdOut.printf("%6d %8.4f\n", i, sample);
    gs4.tic();
}

Run this test from the command line with some input n:

> java-introcs GuitarString 4
(Test #1 - Test #8 not shown)...

Test #9 - test 25 tics
     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

Implementing GuitarHero.java

1. Test GuitarString and RingBuffer using GuitarHeroLite. Which additional constructor and method does GuitarHeroLite test?
2. To implement GuitarHero.java, use the code in GuitarHeroLite.java as a starting point.
3. 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.
4. Can you play individual notes? Do the notes have the correct frequencies? Can you play a chord?

Where do I play notes in GuitarHeroLite and GuitarHero? Be sure that the interactive Keyboard window has focus by clicking it. Then, either click the piano keys or type the keystrokes.

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.

Why do I get a RuntimeException or an ArrayIndexOutOfBoundsException in GuitarHeroLite before I type any keystrokes? 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, there 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 keystrokes '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 keyboardString.indexOf(key)? If keyboard is a String and key is a character, then keyboardString.indexOf(key) returns the integer index of the first occurrence of the character key in the String keyboardString, or –1 if it does not occur. You can read about it in the String Javadoc page.

Can I hardwire the constants 44,100, 0.996, 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 SAMPLING_RATE for 44100, DECAY_FACTOR for 0.996, CONCERT_A for 440.0, and the expression keyboardString.length() for 37. You do not need to name all of the constants in the formula: $$ 2^{(i − 24)/12} $$.

Requirements

1. You may use a .txt file and read it using the In data type.
2. The duration of your composition must be between 10 and 120 seconds. Since the sampling rate is 44,100 Hz, this translates to between 441,000 and 5,292,000 calls to StdAudio.play().
3. You may create chords, repetition, and phrase structure using loops, conditionals, arrays, and functions. Also, feel free to incorporate randomness.
4. You may also create a new music instrument by modifying the Karplus–Strong algorithm; consider changing the excitation of the string (from white noise to something more structured) or changing the averaging formula (from the average of the first two samples to a more complicated rule) or anything else you might imagine. See below for some ideas.

Background

You will write a program MidiGuitarHero.java that is similar to GuitarHero.java, but works with a MIDI keyboard controller keyboard or a MIDI keyboard controller app (running on your smartphone or tablet connected to your laptop). MIDI (Musical Instrument Digital Interface) is a technical standard for digital music. More details can be found on the Wikepedia page.

Approach

The MidiSource.java class, provided in the assignment project folder, maintains a queue of short MIDI messages. See javax.sound.midi.ShortMessage for details. The basic steps are:

1. Connect a MIDI controller keyboard or app to a computer using USB. See the figure below.
2. Implement a client, MidiGuitarHero, that uses the MidiSource and GuitarString classes.
3. Create an array of GuitarString objects, where each GuitarString object corresponds to a key on a MIDI controller keyboard or app.
4. Create a MidiSource object (with connectToSynth set to false).
5. Start the MidiSource object so it can generate short MIDI messages each time a key is pressed/tapped. A MIDI message contains an integer code that corresponds to a pressed key. Access and interpret each short MIDI message generated. Similarly to GuitarHero, pluck the appropriate string, then sum all the samples, play the resulting sample, then tic all the strings

MidiSource.java API

public class MidiSource {

   // Creates a MidiSource object that listens to the first found connected 
   // Midi input device.  Set verbose to true for verbose output (standard out).
   // Set  connectToSynth to true use Java’s MIDI player; false to use the
   // GuitarString sound
   public MidiSource(boolean verbose, boolean connectToSynth) 
                                                                                            
  
   // Starts the MidiSource object so it can produce messages.
   public void start()               
                                          
   // Closes the MidiSource object.
   public void close()     
                                                     
   // Does the MidiSource have more messages (keys pressed)?
   public boolean isEmpty()    
                                                 
   // Returns  code of the MIDI Controller key pressed
   public int nextKeyPressed()

   // Demonstrates the MidiSource class - playing from a
   // keyboard or a Midi file - using the default Java synthesizer
   public static void main(String[] args)   
                                    
}

Implementation Tasks

MidiGuitarHero.java

1. Connect your Midi keyboard controller (via USB) to your laptop - see below for using a smartphone or tablet.
2. On the command line terminal, enter the command:

   java-introcs MidiSource -p
   

3. Press some keys on your MIDI keyboard controller. You should see output similar to:

   MidiSource version .2
   DEVICE 0: Gervill, OpenJDK, Software MIDI Synthesizer, Midi device available, Not a MIDI keyboard controller, trying next...
   DEVICE 1: Port1, YAMAHA, YAMAHA PSR-1100 Port1, Midi device available, Valid MIDI controller connected.
   ShortMessage:  Command: NOTE_ON (144)  Channel: 0 Number:   77 Velocity: 21
   ShortMessage:  Command: NOTE_ON (144)  Channel: 0 Number:   77 Velocity: 0
   

4. Each time you press a key on the MIDI keyboard controller, a MIDI message is produced. The message contains:
   • the command type
   • the channel
   • the data1 value
   • the date2 value
   • (For details, see javax.sound.midi.ShortMessage)
5. For the most part, you will want to capture messages whose command type is NOTE_ON. The data1 value corresponds to the key number (similarly to the index in the String keyboard in GuitarHero.java) and the data2 value corresponds to the velocity of the pressed key. (Some MIDI controllers generate a NOTE_ON and a velocity value of 0 when releasing a key - you will want to ignore those messages.)
6. The general structure of your code should look like this:
   • Create an array of GuitarString objects. The size of the array depends on how many notes you want to be able to produce.
   • You need to generalize the formula for the frequency of each GuitarString object, i.e., \(440 \times 2^{(k − 24) / 12}\). One way to do this is to determine the key number of A4 (concert A or 440 Hz).
   • For example, here’s an 88-key piano keyboard with A4 (and C4) labeled:

     

   • Create and start the MidiSource object.
   • Similarly to GuitarHero, write a loop that gets the next short Midi message. Interpret the message, and if it’s a NOTE_ON with a velocity greater than zero (0), pluck the appropriate GuitarString object. Then compute the sum of the samples, play the sum and tic the GuitarString objects.

Additional Challenges!

1. When you execute the following command, try pressing other buttons on your Midi keyboard controller. By understanding other MIDI codes (e.g., CONTROL_CHANGE), you can use your Midi keyboard controller to change instruments. Of course, you need to create new music instruments by modifying the Karplus–Strong algorithm.

   java-introcs MidiSource -p
   

2. The MidiSource class can also generate MIDI messages from MIDI files. You can experiment by downloading chopstik.mid and executing the command:

   java-introcs MidiSource -p chopstik.mid
   

   As you can see, different channels correspond to different instruments. If you have implemented multiple instruments, you can write an MidiAutoGuitar.java that plays your instruments from an existing MIDI file.

MIDI Controllers

MIDI Controller Keyboard and USB

1. Almost any MIDI keyboard controller with a USB interface will suffice (for example, a 25-key MIDI keyboard controller can be purchased on Amazon for about $40).
2. Connect the MIDI keyboard to your laptop.
3. In the terminal window, execute the command:

   java-introcs MidiSource
   

4. Press the keys on the keyboard to see the MIDI messages (numbers) generated by each key.

   

iPhone with iOS 11, Mac OS and USB

1. Download/install the MIDI controller app from the Apple App Store.
2. Connect your iPhone/iPad to your Mac laptop using the USB connector.
3. On your Mac:
   • Start the Audio Midi Setup application (in the Applications/Utilities folder)
   • Under Window/Show Audio Devices and enable your iPhone
   • In the terminal window on your Mac laptop, execute the command:

   java-introcs MidiSource
   

4. Start the MIDI controller app.
5. Press the keys on the MIDI Controller app to see the MIDI messages (numbers) generated by each key.

Android and USB

1. Download/install/start the MIDI controller app from the Google Play Store.
2. Connect your Android device to your laptop using the USB connector.
3. On your Android device:
   • Show the notification screen by dragging down from the top of the display.
   • Tap Use device MIDI. (Different versions of Android may require different settings.)
   • In the terminal window on your laptop, execute the command:

   java-introcs MidiSource
   

4. On the MIDI Controller app, tap Receivers for Keys and select Android USB Peripheral Port.
5. Press the keys on the MIDI Controller app to see the MIDI messages (numbers) generated by each key.

Here are some approaches for synthesizing additional 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 six 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 changing the decay factor on iterations where a certain key (such as Shift) is held down.
• 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.

• ChucK. ChucK is a 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/MUS 315 Transforming Reality by Computer, 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 Star Spangled Banner.