Guitar Hero

Start: 11/20/2018
Due: 12/5/2018, by the beginning of class
Collaboration: individual
Important links: style guidelines, Checklist, guitar.zip, gradesheet

This assignment was developed by Andrew Appel, Jeff Bernstein, Maia Ginsburg, Ken Steiglitz, Ge Wang, and Kevin Wayne, at Princeton University. Original language was Java.

Goal

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

Background

We’ll first discuss the theory behind guitar synthesizer.

Digital audio

Before reading the rest of this assignment, please review the lecture note on digital audio.

Simulate the plucking of a guitar string

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 –1/2 and +1/2) 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.

Sampling from Karplus-Strong

• 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 –1/2 and +1/2.

  

  White noise

• 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 it works?

The two primary components that make the Karplus–Strong algorithm work are the ring buffer feedback mechanism and the averaging operation.

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

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.

Tasks

Starting from the skeleton files we’re providing, you are to write two Kotlin classes and a program to play guitar interactively. We’ll describe the specifications for the classes and program in detail below.

Files for this assignment

The file guitar.zip contains GuitarHeroLite.kt; API templates for RingBuffer and GuitarString; and this project's readme.txt template.

Ring buffer

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

class RingBuffer(val capacity: Int) {
    // PROPERTIES (All are read-only properties.):
    //   size // number of items currently in this ring buffer
    //   capacity // largest possible value of size
    //   isEmpty // is this ring buffer empty (size equals zero)?
    //   isFull // is this ring buffer full (size equals capacity)?
    fun enqueue(x: Double) // adds item x to the end of this ring buffer
    fun dequeue(): Double // deletes and returns the item at the front of this ring buffer
    fun peek(): Double // returns (but do not delete) the item at the front of this ring buffer
}

• Corner cases. Throw a RuntimeException with a custom message if the client calls either dequeue() or peek() when the ring buffer is empty or enqueue() when the ring buffer is full.
• Performance requirements. The constructor must take time at most proportional to the capacity. Every other operation must take constant time.

• Possible implementation. Since the ring buffer has a known maximum capacity, you can implement it using a DoubleArray of that length. For efficiency, use cyclic wrap-around: maintain a private integer variable first that stores the index of the last recently inserted item and maintain a second private integer variable last that stores the index one beyond the most recently inserted item.

  

  Ring buffer

  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 either index equals capacity, make it wrap-around by changing the index to 0. To determine the size of the ring buffer (and whether it is full or empty), you will also need an integer property size that stores the number of items currently in the ring buffer.

Guitar string

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

class GuitarString (/* argument of your main constructor goes here */) {
    // You need to define the val property
    //      length
    // that is of type Int and it returns the number of samples
    // in the ring buffer.
    //
    // YOU NEED ONE PRIMARY CONSTRCUTOR AND ONE SECONDARY CONSTRUCTOR.
    //
    // One constructor takes a Double parameter named frequency and
    // creates a guitar string of the specified frequency,
    // using a sampling rate of 44,100.
    //
    // The other constructor takes a DoubleArray parameter and
    // creates a guitar string whose size is to be derived from,
    // and its initial values are given by the array parameter.
    //
    fun pluck() // plucks the guitar string (by replacing the buffer with white noise)
    fun tic() // advances the Karplus-Strong simulation one time step
    fun sample(): Double // returns the current sample
}

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.

Length. Return the number of samples n in the RingBuffer.

Pluck. Replace the n items in the ring buffer with n random values between −0.5 and +0.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.

Sample. Return the value of the item at the front of the ring buffer.

Interactive guitar player

This file GuitarHeroLite.kt is a sample GuitarString client that plays the guitar in real time, using the keyboard to input notes. When the user types the lowercase letter 'a' or 'c', the program plucks the corresponding string. 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.

// file name: GuitarHeroLite.kt
import kotlin.math.pow

fun main(args: Array<String>) {
    // Create two guitar strings, for concert A and C
    val CONCERT_A = 440.0
    val CONCERT_C = CONCERT_A * 2.0.pow(3.0 / 12.0)
    val stringA = GuitarString(CONCERT_A)
    val stringC = GuitarString(CONCERT_C)
    // the main input loop
    while (true) {
        // check if the user has typed a key, and, if so, process it
        if (StdDraw.hasNextKeyTyped()) {
            // the user types this character
            val key = StdDraw.nextKeyTyped()
            // pluck the corresponding string
            if (key == 'a') stringA.pluck()
            if (key == 'c') stringC.pluck()
        }
        // compute the superposition of the samples
        val sample = stringA.sample() + stringC.sample()
        // send the result to the sound card
        StdAudio.play(sample)
        // advance the simulation of each guitar string by one step
        stringA.tic()
        stringC.tic()
    }
}

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

val keyboard: String = “q2we4r5ty7u8i9op-[=zxdcfvgbnjmk,.;/’”

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

The ith character of the string keyboard corresponds to a frequency of 440 × 2 ^{(i − 24) / 12}, so that the character 'q' is 110 Hz, 'i' is 220 Hz, 'v' is 440 Hz, and ' ' is 880 Hz.

Don't even think of including 37 individual GuitarString variables or a 37-way if statement! Instead, create and initialize an array of 37 GuitarString objects and use keyboard.indexOf(key) to figure out which key was typed.

If a keystroke does not correspond to one of the 37 possible notes, ignore it.

Extra credit

Write a program AutoGuitar.kt that will automatically play music using GuitarString objects. A few ground rules:

• Your program may not accept command-line arguments. Your program may not use standard input, standard output, or standard drawing. You may, however, submit an accompanying .txt file. Your program should read the data from that file.
• 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(). No infinite loops.
• Your program must behave consistently on different machines.

You may create chords, repetition, and phrase structure using loops, conditionals, arrays, and functions. Also, feel free to incorporate randomness. 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 the checklist for some concrete ideas.

Gradesheet

We will use this gradesheet when grading your lab.

Submission

Zip up your RingBuffer.kt, GuitarString.kt, GuitarHero.kt, and a completed readme.txt, and submit the zip file via Moodle. You may submit additional .kt and .txt files for extra credit, so long as you do not modify the files RingBuffer.kt, GuitarString.kt, or GuitarHero.kt to accommodate your extra credit work.