7. Guitar Hero

Download Project Zip | Submit to TigerFile

Goals

• To create user-defined data types in Java.
• To model and implement digital audio. Specifically to compute sound waveforms using a mathematical model of a musical instrument.
• To learn about efficient data structures that are crucial for application performance.

Getting Started

• Download and expand the project zip file for this assignment, which contains the files you will need for this assignment.

• This is a partner assignment. Instructions for help finding a partner and creating a TigerFile group can be found on Ed.

• The rules for partnering:

  • Choose a partner whose skill level is close to your own - only two partners per group.
  • Your partner does not have to be in your precept.
  • The rules for partnering are specified on the course syllabus. Make sure you read and understand these rules, and please post on Ed if you have questions. In your acknowledgments.txt file, you must indicate that you adhered to the COS 126 partnering rules.

Background

For this assignment, you will write a program to simulate plucking a guitar string using the Karplus–Strong algorithm. This algorithm played a seminal role in the emergence of physically modeled sound synthesis (where a physical description of a musical instrument is used to synthesize sound electronically).

Approach / Design

When a guitar string is plucked, the string vibrates and creates sound. The length of the string determines its fundamental frequency of vibration. We model a guitar string by sampling its displacement (a real number between –½ and +½) at \(n\) equally spaced points in time. The integer \(n\) equals the sampling rate (44,100 Hz) divided by the desired fundamental frequency, rounded up to the nearest integer.

• Plucking the string. The excitation of the string can contain energy at any frequency. We simulate the excitation with white noise: set each of the \(n\) displacements to a random real number between –½ and +½.

• The resulting vibrations. After the string is plucked, the string vibrates. The pluck causes a displacement that spreads wave-like over time. The Karplus–Strong algorithm simulates this vibration by maintaining a ring buffer of the \(n\) samples: the algorithm repeatedly deletes 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 of 0.996. For example:

Why does it work? The two primary components that make the Karplus–Strong algorithm work are the ring buffer feedback mechanism and the averaging operation. (From a mathematical physics viewpoint, the Karplus–Strong algorithm approximately solves the 1D wave equation, which describes the transverse motion of the string as a function of time.)

1. The ring buffer feedback mechanism. The ring buffer models the medium (a string tied down at both ends) in which the energy travels back and forth. The length of the ring buffer determines the fundamental frequency of the resulting sound. Sonically, the feedback mechanism reinforces only the fundamental frequency and its harmonics (frequencies at integer multiples of the fundamental). The energy decay factor (0.996 in this case) models the slight dissipation in energy as the wave makes a round trip through the string.
2. The averaging operation. The averaging operation serves as a gentle low-pass filter (which removes higher frequencies while allowing lower frequencies to pass). Because it is in the path of the feedback, this has the effect of gradually attenuating the higher harmonics while keeping the lower ones, which corresponds closely to the sound that a guitar string makes when plucked.

Implementation Tasks

Overall Requirements

• Implement three classes:
  • RingBuffer.java
  • GuitarString.java
  • GuitarHero.java
• We provide two other classes:
  • GuitarHeroLite.java
  • Keyboard.java
• You must follow the prescribed API for each class. 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 must 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).

RingBuffer

Your first task is to create a data type to model the ring buffer. Write a class named RingBuffer that implements the following API:

public class RingBuffer {

     // Creates an empty ring buffer with the specified capacity.
     public RingBuffer(int capacity)

     // Returns the capacity of this ring buffer.
     public int capacity()

     // Returns the number of items currently in this ring buffer.
     public int size()

     // Is this ring buffer empty (size equals zero)?
     public boolean isEmpty()

     // Is this ring buffer full (size equals capacity)?
     public boolean isFull()

     // Adds item x to the end of this ring buffer.
     public void enqueue(double x)

     // Deletes and returns the item at the front of this ring buffer.
     public double dequeue()

     // Returns the item at the front of this ring buffer.
     public double peek()

     // Tests this class by directly calling all instance methods.
     public static void main(String[] args)
}

Since the ring buffer has a known maximum capacity, you can implement it using a double array of that length. For efficiency, use cyclic wrap-around: maintain an integer instance variable first that stores the index of the least recently inserted item and a second integer instance variable last that stores the index one beyond the most recently inserted item. For example, this is a ring buffer of size 4 with a capacity 10:

To insert an item, put it at index last and increment last. To remove an item, take it from index first and increment first. When the value of either index (last, first) equals capacity, make it wrap-around by changing the index to 0. To determine the current number of valid entries in the ring buffer (and whether it is full or empty), you will also need a third integer instance variable size. To determine the size of the ring buffer (and whether it is full or empty), you will also need a third integer instance variable size that stores the number of items currently in the ring buffer.

Requirements

1. Corner cases: RingBuffer must throw a IllegalStateException with a custom message if a client calls either dequeue() or peek() when the ring buffer is empty, or calls enqueue() when the ring buffer is full.
2. Performance: The constructor must take time at most proportional to the capacity. Every other method MUST take constant time.

GuitarString

Create a data type to model a vibrating guitar string. Write a class named GuitarString that implements the following API:

public class GuitarString {

    // Creates a guitar string of the specified frequency,
    // using a sampling rate of 44,100, where all samples are
    // initially set to 0.0. 
    public GuitarString(double frequency)

    // Creates a guitar string whose length and initial values
    // are given by the specified array.
    public GuitarString(double[] init)

    // Returns the number of samples in the ring buffer.
    public int length()

    // Returns the current sample.
    public double sample()

    // Plucks this guitar string by replacing the ring buffer with white noise.
    public void pluck()

    // Advances the Karplus-Strong simulation one time step.
    public void tic()

    // Tests this class by directly calling both constructors
    // and all instance methods.
    public static void main(String[] args)
}

Requirements

1. Your GuitarString must be implemented using the RingBuffer data type. You should not use Stack, Queue, Set or other data types to represent a guitar string.
2. Constructors. There are two ways to create a GuitarString object.
   • The first constructor 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.
   • The second constructor 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 main purpose is to facilitate testing and debugging.
3. length(). Return the number of samples $n$ in the ring buffer.
4. pluck(). Replace the $n$ items in the ring buffer with $n$ random values between $−0.5$ and $+0.5$.
5. tic(). Apply the Karplus–Strong update: delete the sample at the front of the ring buffer and add to the end of the ring buffer the average of the first two samples, multiplied by the energy decay factor.
6. sample(). Return the value of the item at the front of the ring buffer.

GuitarHero client

Implement an interactive guitar player. GuitarHeroLite.java is a GuitarString client that plays the guitar in real time. It relies on a helper class Keyboard.java that provides a graphical user interface (GUI) to play notes using the keyboard. When a user types the lowercase letter p or v, the program plucks the guitar string corresponding to middle C or concert A, respectively. Since the combined result of several sound waves is the superposition of the individual sound waves, it plays the sum of the two string samples.

Requirements

1. Write a program GuitarHero that is similar to GuitarHeroLite. GuitarHero must support a total of 37 notes on the chromatic scale from 110 Hz to 880 Hz.
2. Use the following 37 keys to represent the keyboard, from lowest to highest note:
   

String keyboardString = "q2we4r5ty7u8i9op-[=zxdcfvgbnjmk,.;/' ";

1. This keyboard arrangement imitates a piano keyboard: The white keys are on the qwerty and zxcv rows and the black keys are on the 12345 and asdf rows of the keyboard.
   

   

2. Each character i of keyboardString corresponds to a frequency of $$ 440 \times 2^{(i − 24) / 12} $$ Hz, so that the character 'q' is 110 Hz, 'i' is 220 Hz, 'v' is 440 Hz, and the space character is 880 Hz.
3. You must not declare 37 individual GuitarString variables and/or utilize 37-way if statements! Instead, create and initialize an array of 37 GuitarString objects and call keyboardString.indexOf(key) to determine which key was played.

Possible Progress Steps

We provide some additional instructions below. Click on the ► icon to expand some possible progress steps or you may try to code/test without them. It is up to you!

    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

   StdOut.printf("Test #0 - create a RingBuffer object with %d\n", n);
   int n = Integer.parseInt(args[0]); // get the size of n from the command-line
   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());

   StdOut.printf("Test #3 - perform %d enqueues: 1.0, 2.0, ...\n", n);
   StdOut.printf("**** isFull() should be false- is %b\n", buffer.isFull());
   for (int i = 1; i <= n; i++) { // enqueue n values:  1.0, 2.0, ...
       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());
   }
   StdOut.printf("**** isFull() should be true- is %b\n", buffer.isFull());

   StdOut.printf("Test #4 - check peek value == %.1f\n", 1.0);
   StdOut.printf("**** isEmpty() should be false- is %b\n", buffer.isEmpty());
   double val1 = buffer.peek();
   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());
   for (int i = 0; i < n - 1; i++) buffer.dequeue(); // dequeue everything left
   StdOut.printf("**** remove %d items and isEmpty() should be true- is %b\n",
                      n - 1, buffer.isEmpty());

int n = Integer.parseInt(args[0]);
StdOut.printf("Test #0 - create a Guitar String object with %d\n", n);
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();
}

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

Rock on! Play your GuitarHero

Here are some example tunes you can play on your GuitarHero. Try these below, and then compose some of your own:

1. An A major chord.

    i - z    i
             -
             z
   

2. An A major scale.

   i o - [ z d f v   v f d z [ - o i
   

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

4. What is this familiar melody? (S == space)

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

Submission

Submit to TigerFile : RingBuffer.java, GuitarString.java, GuitarHero.java, completed readme.txt and acknowledgments.txt.

Grading

Challenge

Write a program AutoGuitar.java that will automatically play music using GuitarString objects.

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.

Enrichment

This assignment was developed by Andrew Appel, Jeff Bernstein, Alan Kaplan, Maia Ginsburg, Ken Steiglitz, Ge Wang, and Kevin Wayne.

Copyright © 2005–2025