project 1b: wavMaker (CISC181, Fall 2005)

Introduction

Required Concepts

C++ concepts:

• control structures: if, if/else, switch, while, for
• functions
• Writing to external binary files with the open(), write() system calls

Additional concepts:

• Creating WAV files containing digital audio
• Using and modifying Makefiles
• Creating a tar file for submission

While the project is designed so that you can do it without using arrays and pointers, you may use them if you like. However, my solution did not use any.

Reminders

• Work independently on this programming project.
• Do not work with another student in the class. If you need help, see your instructor or TA during office hours, or make an appointment if those hours are not convenient.
• Don't wait until the day before the assignment is due to start working. If you wait until then, you'll have no time to go in for help if you get stuck. This assignment is designed so you can pace yourself over several days.

Assignment Description

This assignment involves further development to a library of C++ routines stored in files wavLibrary.h and wavLibrary.cpp. You started developing this library in lab04b. This project continues this development.

In this project you will add several capabilities to this library, and then use the library in several main programs.

The project is divided into several stages. At each stage, you add a bit more capability to either the library (wavLibrary.h/wavLibrary.cpp) or to one or more of the main programs. At each stage, the total amount of credit you can possibly earn increases.

If you find that you are not able to complete the entire project, the intermediate stages provide places where you can stop, for partial credit. If you do decide to stop part way through, skip down to the Stage marked "Submission: creating your TAR file and updating your web page".

As with lab04b, when you are finished, there will be a series of ".wav" files that will show your final work. The links below show an example "before" and "after" group of .png files.

The following table shows a summary of the various stages in the project, what each one involves, and the partial credit involved. Detailed instructions follow this chart:

The new sound idea

As part of the project, in Stage 4, you need to come up with your own creative idea for generating sounds. You should post your idea to the project 4 bulletin board on WebCT, making sure no-one else is doing a project 4b with exactly the same idea. Your instructor will announce the deadline for posting these ideas (it will be several days in advance of the final project deadline).

What could your new idea be? Here are some suggestions:

• Do your own tune (in the spirit of mary.cc). Some knowledge of music will help here.
  
• Do something with varying volume (e.g. a sound that fades away). You can vary the volume of a sound by changing the amplitude of the sine wave (i.e. multiplying by a value between 0 and 1.0)
  
• Experiment with adding harmonics to the sine wave. The basic harmonics are multiples of the fundamental frequency (e.g. if the fundamental is 220Hz, you add 440, 660, 880, 1100, 1320, 1540, etc. By adding a "weighted average" of harmonics, you can achieve interesting sounds that have the pitch of the fundamental frequency (e.e. in this case, they will all sound like the note "A" that is right below "middle C"), but that sound like different instruments. This is the principle behind the design of the Hammond Organ.
  
  A weighted average means that you multiply all the components of the average by varying amounts between 0.0 and 1.0; the sums of the amounts should add up to one. For example:
  
  sample = 0.6 * harm1 + 0.2 * harm2 + 0.1 * harm3 + 0.05 * harm4 + 0.05 * harm5;
  
• Experiment with making "ocean sounds" by varying the "noise wave" over time, perhaps using a very low frequency sine wave to adjust the volume (frequency of 1/5 Hz, e.g. 5 seconds per cycle, as opposed to 5 cycles per second).
  
• Experiment with generating waves other than sine (e.g. square waves or triangle (sawtooth) waves). You'll have to do some research to learn about the shapes of those waves, and some thinking to figure out how to write a mathematical function that will generate them.
  
• Experiment with writing a function that will convert from a string, e.g. char phoneNumber[] = "(302) 831-8622" into DTMF. You'll need to read ahead in the text a bit on processing C-style strings as character arrays. You should skip over non-digits (e.g. the '(', ')' and '-' characters.

There are many other possible ideas. Consult with your instructor for additional suggestions if you are stuck. If you are really really stuck, you might consider doing project1a instead!

The project is divided into stages

The project is divided into seven (7) stages. Except for stage 7, which is done when you are ready to submit—and you can "skip to" if you give up before the end (see "partial credit", below)—you should do the stages strictly in order.

On the other hand, it is probably best to read over the entire assignment before starting to code stage 1, so you have some idea of where you are going. Don't let the size or complexity overwhelm you; working step by step, one stage per day, you'll have no trouble finishing on time if you start NOW.

Partial Credit

If you decide not to complete all 6 stages, that's ok. I hope that all students will try to complete at least up through stage 5, but however far you get, be sure you at least submit what you have (for partial credit). Once you are ready to submit, skip to stage 7, where you will create a tar file of your project for submission.

Let's get started!

So, with that advice, let's begin,

Stage 0: Getting started
( 0% of total, 0% complete when done)

Copying files

Create a directory ~/cisc181/proj1. (This directory is where your C++ code goes, and should NOT be under ~/public_html)

Copy the files from ~pconrad/public_html/cisc181/05F/work/proj/proj1b to your ~/cisc181/proj1 directory.

Do a "make clean", "make all", "make install". You should see that you now have a directory ~/public_html/cisc181/proj1 that contains WAV files created by your code.

They will resemble the files in the "before" directory for project1b.

Understanding the Makefile

The Makefile in this directory has several rules in it that will help you complete the project efficiently.

First, try typing "make all".

This will compile all the routines, and then run commands that create the WAV files.

Then, try typing "make install". That will create your ~/public_html/cisc181/proj1 directory, copy all your .wav files into that web directory, and set the permissions correctly.

Look at the contents of the Makefile, and try to understand the "make install" rule. The -p flag on the mkdir command makes sure that in case the directory already exists, no error message is created. the "-m 755" option builds a "chmod" for the directory into the mkdir command. Make sure you are familiar with both of those Unix commands for the next exam (ask your TA and/or your instructor for help if you are not sure.)

You'll need to make a few modifications to this Makefile as part of this project, so try to understand all the steps in the Makefile and what they do. Ask your TA for help during lab, and your instructor for help during lecture if you have questions. Your Anderson textbook also has information about Makefiles.

Stage 1: morseCISC181.cc
( 40% of total: 10% for this stage, and 30% for final submission,
40% complete when done)

You mostly completed this Stage as part of lab04b. All that is necessary to get proj1 credit for this Stage is to convert your main program makeMorseCode.cc from lab04b into one called morseCISC181.cc that uses the wavLibrary.h/wavLibrary.cc/wavLibrary.o routines and the endian.h/endian.cc/endian.o routines.

I've done most of the work for you on that. Look at the file morseCISC181.cc. It resembles the "before" program from lab04b.cc; i.e. it only generates Morse Code for "CISC", not for "CISC181".

Your job is to add the code into morseCISC181.cc to generate the additional tones for 181.

Note that you'll also have to change the wavLibrary.cc and wavLibrary.h files to include routines to generate the Morse code symbols for 1 and 8 (following the example of the routines for the letters C, I, and S.)

The Makefile already has rules for compiling the morseCISC181.cc program; just type "make", and the files you've modified will be recompiled.

After you get a successful compile and link of the morseCISC181 binary, type "make install". This will run the program, and then copy the resulting WAV file to the appropriate web directory (your ~/public_html/cisc181/proj1 directory; if that directory doesn't already exist, the Makefile will create it for you using the command "mkdir -p ~/public_html/cisc181/proj1").

Step-by-step instructions for stage 1

1. Type "make clean" then "make" at the command line. Among other things, this should make the binary for morseCISC181.
2. Type "make install", and check your web page http://copland.udel.edu/~youruserid/cisc181/proj1, and look for the file CISC181.wav. Try opening it with whatever audio software works for you.
3. Now go into the files wavLibrary.cc and add function definitions for routines for the numbers 1 and 8. (These will be similar to or identical to the routines you added to the CISC181 Morse code problem in lab04b.) Add the function prototypes into wavLibrary.h
4. Modify morseCISC181.cc to use your new routines.
5. Type "make" again, and if you get a clean compile, do "make install", and check the web site again for CISC181.wav. Continue making changes and recompiling and reinstalling until the CISC181.wav file is correct.

Stage 2: DTMF tones.
( 10% of total, 50% complete when done)

This stage is similar to stage 1; you are just updating the code from lab04b to use the wavLibary.h and wavLibrary.cc files. In this case, our programs are called dtmf123.cc and cantGetThrough.cc. The dtmf123.cc program is just there for you as an example. The cantGetThrough.cc program is one that you have to write yourself from scratch; the cantGetThrough.cc program in the example directory is just a "shell" for you to use to get started.

Step-by-step instructions for stage 2

1. Type "make clean" then "make" at the command line. You don't normally need to type "make clean" before doing a "make" command—and in fact, you shouldn't do it routinely, because it defeats part of the whole reason for using Make. Here we are doing it so you can notice that the files dtmf123.cc and cantGetThrough.cc are being compiled.
2. Type "make install", and check your web page http://copland.udel.edu/~youruserid/cisc181/proj1, and look for the files dtmf123.wav and cantGetThrough.wav. Open them with your audio software. You should find that they are identical. This, of course, is not what we want.
3. Now revisit your code from lab04b for the program where you dialed a phone number and heard a busy signal. Figure out which routines should go into the wavLibrary.h and wavLibrary.cc files, and which code should go into cantGetThrough.wav. Add the code into the right places
4. Type "make" again, and if you get a clean compile, do "make install", and check the web site again for cantGetThrough.wav. Continue making changes and recompiling and reinstalling until the cantGetThrough.wav file is correct.

Stage 3: Repeated SOS in Morse Code.
( 10% of total, 60% complete when done)

In this stage, you'll start with the file morseSOS.cc, which currently generates only the letter S in Morse code, one time, with a fixed ditDuration, and places the result in the output file.

You'll turn this into a program that takes exactly three command line arguments:

1. the name of an output file
2. a number n, the number of times to send the message SOS
3. a number d, which is an floating point number (use a variable of type double) of seconds, which should be the duration of the entire broadcast.

You should figure out some way to determine the dit duration and dah duration from n and d. Remember to leave the inter-word spacing between the repetitions of SOS.

You'll need to modify the lines of code that

• print out the "usage" message
• that check argc for validity (current the program ignores argc so that the "make install" works, but you should enforce that exactly three command line parameters should be able to
• that convert the elements of argv into useful values

The make install routine runs the program several times with different parameters. Currently, each of those will result in a file that contains only the letter S, with a dit duration of 0.1. That, of course, is not what we want. After your modification, each of those files will have the proper length, and contain the correct number of SOS repetitions.

Step-by-step instructions

1. Modify wavLibrary.cc and wavLibrary.h to add support for the letter 'O'.
2. Modify morseSOS.cc as described above.
3. "make" and "make install" until everything works as described above.

Stage 4: Generating some music.
( 10% of total, 70% complete when done)

This is a really easy stage in terms of what you have to do. The main reason it is here it to give you some additional ideas about what you could do for stage 5, and some example code to build on.

Take a look at the mary.cc program. It generates a wave file with some music in it... the first few lines of "Mary Had a Little Lamb". Your task: add the rest of the song.

You don't really need to know much about music to do this (it helps, but it isn't necessary). A comment in the file indicates that the musical notes in the file (so far) are as follows:

// E D C D | E E E (rest)| D D D (rest) | E G G (rest) |

The full musical notes of Mary Had a Little Lamb, which are listed below. (The word "rest" indicates one beat of silence in the music):

// E D C D | E E E (rest)| D D D (rest) | E G G (rest) | E D C D | E E E E| D D E D | C (rest)(rest)(rest) 

Since the current file only contains the first four bars (each bar is four beats), you should be able to look at the pattern and figure out what to do to finish the song.

The writeNote() function

The writeNote() function is particularly interesting. By varying the way the writeNote() function is written, we can change the sound of the music. Currently, the writeNote() function writes a small amount of "white noise" (a random waveform) at the beginning of each note. This gives the sound a bit of the "whoosh" that you get when you blow across the mouthpiece of a flute (or a soda pop bottle.) You can also make the notes more "staccato" (really short) or "legato" (long and smooth) by varying the ratio between the sound and the silence. The only restriction is that the coefficients of the beatDuration should add up to 1.0.

void writeNote(int fd, double beatDuration, double freq) { writeNoiseSamples(fd, 0.1 * beatDuration, 0.5 ); // 0.5 is the volume writeSineWaveSamples(fd, 0.4 * beatDuration, freq ); writeSilenceSamples(fd, 0.5 * beatDuration); }

You don't have to do anything to the writeNote() function for this stage. However, you might try experimenting with different kinds of writeNote() functions as part of your "new sound idea" in the stage that follows this one.

Step-by-step instructions for this stage

1. Modify mary.cc to play out the entire song.
2. Use "make" and "make install" to check that mary.wav now contains the entire song.
3. That's all you have to do!

Stage 5: A new sound idea.
( 20% of total, 90% complete when done)

For a general overview of what you must do, re-read the section "The New Sound Idea" near the beginning of this project description first.

Step-by-step instructions for this stage

1. Once you have a plan for your new sound idea, make the necessary changes to the wavLibrary.cc and wavLibrary.h files to support your new sound idea.
2. Create a new file called newSounds.cc containing your new idea. You'll need to add rules into the Makefile to support this new file, including rules for whatever wav files you use to demonstrate this new sound idea. Be sure that you add comments into all your C++ code, and in the Makefile explaining your ideas and your changes.
3. Use "make" and "make install" to run and test your code.

Stage 6: Farnsworth Timing.
( 10% of total, 100% complete when done (except for submitting) )

This stage is an update of the Morse code stages (1-3). The file farnsworthCISC181.cc is currently nearly identical to morseCISC181.cc. Your job is to read the comments near the bottom of the file about Farnsworth timing (as well as perhaps doing some reading on the web) and then modifying the program to produce the Morse Code output with the proper Farnsworth timing (expressed in words per minute.)

As an extra challenge, I'm not providing step-by-step instructions for this stage; I'm only giving you a description of the goal. The goal is that when you are done, the files produced by the "make install" step called CISC181_5wpm.wav, CISC181_10wpm.wav, and CISC181_20wpm.wav will all contain CISC181 in proper Morse code at 5 words per minute, 10 words per minute, or 20 words per minute, using the Farnsworth timing rules described in the comment at the bottom of the source code for farnsworthCISC181.cc.

Stage 7: Submitting your work (tar file and script file)
( 10% of total (was included in running total since stage 1, complete this stage last )

Scripting your work and creating your tar file should follow the techniques learned in lab04b, so refer back to that lab for details. Here is a summary of what is required of you:

1. Make a tar file called proj1.tar. Reminders:
• you should be one level up from ~/cisc181/proj1 when you do your tar, i.e., you should be in the directory ~/cisc181/.
• Do a "make clean" inside ~/cisc181/proj1 before creating your tar file. If you create it correctly, the size should be no more than a couple hundred KB, maybe less. (You can use the Unix command ls -lh to see how large each file is in bytes, KB, MB, or GB.)
  
2. Make a script called proj1.txt. In your script, you should cd into your proj1 directory, cat all of your .cpp files and your .h file, and then cat your Makefile. Finally, do following three commands: "make clean", "make all", and "make install". That completes your script.
   
3. Then, submit your proj1.txt and your proj1.tar file to WebCT.
   
4. Print your proj1.txt file and give it to your TA.
   
5. Make sure you have a link on your CISC181 web page to your ~/public_html/cisc181/proj1 directory.

Grading

Here is a summary of the grading rubric. TAs might indicate more detailed grading in their own rubrics.

(end of project 1b)