README for Tanager V4.0 This is Tanager V4.0, released 15 January 2007. Tanager is a digital music player and is a case study in Object Oriented Analysis and Design (OOAD) using iterative development practices. It is written as part of the requirements for my Master of Science degree at Iowa State University. For more information about Tanager, please see www.cs.iastate.edu/~rjlavey/Tanager 1.0 Executing Tanager from a fat jar file ========================================= 1) download the fat jar file from: www.cs.iastate.edu/~rjlavey/Tanager/Elaboration03/TanagerJava_fat.jar 2) make sure you have a JRE 1.5.0 (or later) loaded on your system (java.sun.com/javase/downloads/index_jdk5.jsp) 3) make sure you have a Java Media Framework (JMF) 2.1.1e (or later) loaded on your system (java.sun.com/products/java-media/jmf/2.1.1/download.html) 4) double-click the TanagerJava_fat.jar file 2.0 Building Tanager ==================== If you received Tanager as part of a zip file, you can build the executable from the source using Eclipse 3.2. 2.1 Prerequisites ----------------- 1) JRE 1.5.0 (or later) is installed (java.sun.com/javase/downloads/index_jdk5.jsp) 2) Eclipse 3.2 (or later) is installed (www.eclipse.org/) 3) Java Media Framework (JMF) 2.1.1e (or later) is installed (java.sun.com/products/java-media/jmf/2.1.1/download.html) 4) if you want to run the unit tests, you'll also need to make sure JUnit 4.1 (or later) is installed (junit.sourceforge.net/) 2.2 Building/Executing in Eclipse --------------------------------- 1) download the zip file from www.cs.iastate.edu/~rjlavey/Tanager/Elaboration03/TanagerJEclipseProject.zip 2) create a new, empty Eclipse project named Tanager 3) import the zip file archive into the Tanager Eclipse project 4) add included archives to the build path (right click and Add to Build Path in Eclipse) 4a) add the JavaPolygonButtons.jar file to the build path 4b) add the JUnitNonPublicHelpers.jar file to the build path 4c) add the Mp3FileAttributes.jar file to the build path 4d) add the JID3.jar file to the build path 5) execute as a java application using org.tanager.application.Tanager as the main class 3.0 User's Guide ================ Starting the Tanager player brings up a UI with 3 main sections: 1) the text area that displays the current status of the player while not in the menus, and which it also used to display the menus 2) the control button area with the menu and on/off buttons 3) the context-sensitive navigation button area with up, down, left, right, and middle buttons 3a) while not in the menus, the up and down buttons adjust the volume, and while in the menus they move up and down from the currently-highlights item to the one above or below 3b) while not in the menus, the left button has no effect, and while in the menus, it jumps to the previous menu 3c) the right button has no effect whether in the menus or not 3d) while not in the menus and playing a song, the middle button pauses the song; while not in the menus and not playing a song, the middle button begins playing the first song in the playlist; while not in the menus and a song is paused, the middle button restarts the paused song; while in the menus, the middle button selects the highlighted item Tanager can be powered off by pressing the On/Off button. A song can be downloaded to Tanager by pressing the menu button and then selecting "Download a Song" from the displayed menu. A downloaded song can be deleted from Tanager by pressing the menu button and then selecting "Delete a Song" from the displayed menu. The current playlist can be viewed by pressing the menu button and then selecting "View Playlist" from the displayed menu. A song can be played by pressing the play button. A song can be stopped by pressing the stop button. A song can be paused by pressing the pause button. The volume can be adjusted by pressing the up and down buttons while not in the menus. A paused song can be restarted by pressing the play button. A paused song can be stopped by pressing the stop button. 4.0 Troubleshooting =================== 1) If you hang with the Initializing message at power on, it's likely that you have an incompatible version of the TanagerSongCollection file in your working directory. Try exiting the Tanager player, deleting the TanagerSongCollection file, and power on again. 2) If you download a song and try to play it but nothing happens, make sure you have JMF 2.1.1.e installed. There is very little error handling code in this early version, and if the system is unable to play the song, the state machine will hang waiting for the song to begin. The play icon will be removed from the middle button, but the pause button will not be displayed in this case. 5.0 Version History =================== Version 4.0 - Elaboration Phase 3 --------------------------------- o The fat jar for this version of Tanager can be found at www.cs.iastate.edu/~rjlavey/Tanager/Elaboration03/TanagerJava_fat.jar o Implemented Stop Music use case. o Implemented View Playlist use case. o Implemented Delete a Song use case. o Implemented Volume Adjustments use case. o Refactored menu system. This had been part of the Download a Song use case, but it needs to be a standalone use case, Enter and Exit Menus. I had implemented this in a very simple way using a JPopup, but user feedback told me that it would be better if the menus were displayed in the main display screen of the Tanager UI. o Refactored state machine handling. I originally implemented this as simple switch/case statements in those methods that required state handling, but the complexity of the state machine has grown, and using the State Pattern is a better solution for non-trivial state machines. o Added ability to save/retreive the last known downloaded song's path, so it's easier to download multiple songs. Version 3.0 - Elaboration Phase 2 --------------------------------- o The fat jar for this version of Tanager can be found at www.cs.iastate.edu/~rjlavey/Tanager/Elaboration02/TanagerJava_fat.jar o Implemented alternate use case for Download a Song, invalid audio file selected. o Implemented a basic scenario for the Play Music use case: play music when system is not paused. o Implemented alternate scenario for the Play Music use case: play music when system is paused. o Implemented a basic scenario for the Pause Music use case: pause music when music is playing. Version 2.0 - Elaboration Phase 1 --------------------------------- o The fat jar for this version of Tanager can be found at www.cs.iastate.edu/~rjlavey/Tanager/Elaboration01/TanagerJava_fat.jar o Implemented a basic scenario for the Power On use case: power on to default state. No checking for saved system state is done. o Implemented a basic scenario for the Power Off use case: system state is not saved. o Implemented a basic scenario for the Download A Song use case: download a song with no error checking. No checking for existence of music file is done.