Some Style Rules for Methods and Classes

• A method should have a clear, single, identifiable task.
• An individual method definition should not be too long. In general, a function should not be longer than one printed page (and that is stretching it).
• Methods can access the global variables that represent the state of an object or of a class, but you should avoid using global variables simply to pass information from one method to another — for that, you should use parameters and return values.
• A class should represent a clear, single, identifiable concept.
• Use the modifiers public, protected, and private to control access to the variables and methods in a class.
• Most instance variables should be declared to be private. Getter and setter methods can be provided to access and manipulate the private instance variables.
• Use Javadoc-style comments to document any variable, method, or class that is not private. (They can also be used for private things, but other styles of commenting are also OK in that case.) A Javadoc comment always comes immediately before the thing it is commenting. Ideally, use the Javadoc tags @param, @return, @throws to document the parameters, return value, and exceptions used by a method.

https://xkcd.org/1513

The Program

You should create a class named MidiPlayer to hold the main() routine of the program, plus any static methods that it needs. The program will run in a loop where it presents a text menu to the user, reads the user's response, and carries out the user's command. Here is the menu that you should use:

What do you want to do?

    1.  Read a tune from a file.
    2.  Make up a random tune.
    3.  Select an instrument for the tune.
    4.  Select a volume for the tune.
    5.  Play the tune.
    6.  EXIT  
    
Enter the number for your choice:

The user should respond with a number from 1 to 6. The program should carry out the requested action before returning to the start of the loop and printing the menu again. If you would like to see a working program, you can run MidiPlayerComplete.jar, which you can find in /classes/cs124. To run that program on the commmand line, use:  java -jar MidiPlayerComplete.jar

Note that you can write the main program first, and code the non-trivial actions as subroutine "stubs." A subroutine stub is an empty subroutine that you can call but that doesn't yet do anything useful. You would then go on to complete the program by filling in the subroutine stubs. (This is top-down design.) Alternatively, you could write the Note and Tune classes first, and then write the main program that uses them. (That would be more of a bottom-up design process.)

The program will use input from the user, but you should not use TextIO to do that input. Instead, you should use an object of type Scanner. As discussed in class and in Section 2.4.6, you can create the Scanner that you need using the statement

in = new Scanner( System.in );

Since you will probably need to use the variable in in other subroutines, you can declare it as a static global variable

private static Scanner in;

The Scanner methods that you might want to use in your program include:

• in.next() — Read the next item in input and return it as a String. The Scanner will skip any spaces and end-of-lines. Then the next item will consist of a string of characters, with no spaces.
• in.hasNext() — Tests whether there is any non-blank item left to read in the input. The return value is a boolean. This is really only useful when you are reading from a file.
• in.nextInt() — Read the next item in input as an int. (If the next item is not an integer or if there is no next item, this throws an exception.)
• in.hasNextInt() — Tests if there is an integer as the next item in input.
• in.nextLine() — Reads up to the next end-of-line [or end-of-file] and returns everything on the line as a String. (The end-of-line is read, but is not part of the String that is returned.) The return value can include spaces, and it can be the empty string. Will throw an exception if there is nothing left to read in the input.
• in.hasNextLine() — Tests if there is anything left to read in the input.

You can get full credit fo this assignment as long as your program can handle valid inputs. However, you might want to make your program more robust by handling some possible errors. Note that there are two ways to deal with an error in input: You can let the exception occur, and catch it. Or you can use a test, such as calling in.hasNextInt() before trying to read an int, to avoid any possibility of an exception. In either case, before continuing with the program, you might need to call in.nextLine() to clear out the line of input that contains the error.

Note and Tune

You need to create two new classes to use in the program. In Eclipse, you can use the "New" / "Class" command to create a class. You will have to type in the name of the class (without the .java at the end). You should also make sure that the class is going into the right package. (If you right-click the package name in the Package Explorer, and select "New" / "Class" from the pop-up menu, then the correct package should already be filled in in the dialog box.)

Create a class named Note in package midi. A Note object should have a Midi note number and a duration. The duration should be specified in milliseconds. The values for these instance variables should be specified as parameters to the constructor subroutine for the Note class.

The class should also include an instance method for playing the note. That method needs a parameter of type SimpleSynth, so that it can use the SimpleSynth to turn the note on and off. Between turning the note on and turning it off, you need to insert a delay of duration milliseconds. There is a method Thread.sleep for doing that, but that method can throw a funny exception that must be caught. So, the code for delaying for duration milliseconds looks like this:

try {
    Thread.sleep( duration );
} 
catch (InterruptedException e) {
}

You will probably need to work on the design of the Note class as you continue writing the program.

You also need to create a class named Tune. A Tune represents a list of Notes that can be played in sequence. To store the list of notes, you should use an instance variable of type ArrayList<Note>. It will be easy to add notes to the list and to traverse the list and play the notes that it contains. The class should have an instance method named add for adding a note to the list, and an instance method named play for playing the tune. The play method will need a parameter of type SimpleSynth for playing the individual notes in the tune.

The Tune class should also have two instance variables to store the Midi instrument number that will be used to play the tune and the volume at which it will be played. (It will not be possible to change the instrument or volume in the middle of the tune.) The class should have (at least) setter methods for these two instance variables. The variables should be given reasonable initial values, so that the user can play the tune without explicitly setting the instrument and volume first.

If you want a simple test of your classes, they should work with the following main routine:

import midi.*;  // (if this is in another package)
public static void main(String[] args) {
    Tune tune = new Tune();
    tune.setVolume(50);      // not too loud
    tune.setInstrument(20);  // Reed Organ
    tune.add( new Note(1, 1000) );  // inaudible
    tune.add( new Note(48, 500) );
    tune.add( new Note(48, 500) );
    tune.add( new Note(48, 500) );
    tune.add( new Note(44, 2000) );
    SimpleSynth midi = new SimpleSynth();
    tune.play(midi);
}

About Creating a Random Tune

One part of the assignment is to create random tunes. Now, you could make a random tune simply by adding a bunch of notes with randomly selected note numbers to a Tune, but that would probably sound bad. My idea for making a random tune was that the change from one note to the next should ordinarily be very small, but that sometimes there should be larger jumps. That is, I select a random change in the note number from one note to the next. So, the notes do a kind of random walk along the keyboard. The results sound better to me when the probability of a large jump is much smaller than the probability of a small jump. (If you think about it, this is kind of like the problem of selecting a random number of runs scored in an inning in our baseball simulation.) You could also play with the idea of random durations for the notes.

When selecting random values or doing a random walk, you should make sure that the note numbers lie in a reasonable range. Although there are 128 possible note numbers, many of the notes are actually inaudible to human hearing. My program makes sure that the note numbers remain in the range from 36 to 84.

Note that when the user selects the command "Make up a random tune," the program should just create the Tune object, and save it in a variable. It shouldn't play the tune. When the user wants to play the tune, they will select the command "Play the tune."

About Reading from a File

Your program will also have to read a tune from a file. You can use a scanner to read from a file, using the same commands that are used to read data from user input. The only problem is creating the Scanner object. You will need the name of the file, which you can ask the user to input. If the user specifies a file that can't be read, there will be an exception, and the exception has to be caught. Here is some code that you might use. It uses the Scanner named in to read the file name from the user.

System.out.print("Enter the path to the file: ");
String filepath = in.next();
Scanner filein;  // A scanner for reading from the file
try {
    filein = new Scanner( new File(filepath) );
}
catch (Exception e) {
    System.out.println("Can't read a file named " + filepath);
    return null;  // Give up on reading the file!
}
// Now, filein can be use for reading from the file.

Your goal is to read the specified file and construct the Tune that it represents. (You shouldn't play the tune until the user chooses the "Play the tune" command.) Of course, you need to know the file format...

Each line of a tune file starts with a word (which can be read with filein.next()). The word is followed by one or two integers, depending on the word. Here are the legal words and their meanings:

• instrument — There is one integer on the line, in the range 0 to 127. The number is a Midi instrument number. You should set the tune to use that instrument.
• volume — There is one integer on the line, in the range 0 to 127. The number is a Midi volume level. You should set the tune to use that volume.
• beat — There is one positive integer on the line. It specifies the number of milliseconds per "beat". The duration of a note will be specified as the number of beats, not the number of milliseconds. The actual duration is the number of beats specified for the note times the number of milliseconds per beat. In case this is not specified in the file, your program should have a reasonable default value for this variable.
• note — This command generates a Note to be added to the tune. There are two integers on the line. The first is a Midi note number in the range 0 to 127. The second is a positive number giving the number of beats for the note.
• pause — This inserts a silence or "rest" into the tune. There is one number on the line, specifying the number of beats for the pause. You should implement a pause by inserting some special kind of note into the tune. For example, you could play an inaudible note, or you could use a special note number, like -1, for a note that is actually a pause.

Note that instrument, volume, and beat are optional in a file.

Your program should be able to handle any legal tune file. I have made three short examples, which you can find in the following files:

• /classes/cs124/tunes/scale.txt
• /classes/cs124/tunes/row-your-boat.txt
• /classes/cs124/tunes/random-song.txt

There is no need to copy these files anywhere. When the program asks for a path to a file, you can enter one of these three strings exactly as shown.

The same directory also contains three invalid tune files which contain various errors. You can get full credit for the assignment as long as your program can correctly handle valid files, but if you want to make a more robust program, you can test it on these files:

• /classes/cs124/tunes/error1.txt
• /classes/cs124/tunes/error2.txt
• /classes/cs124/tunes/error3.txt

A really robust program would detect the errors in these files and report them to the user, without crashing. But testing for all possible errors can be difficult.