Handling MP3 Files

This assignment introduces the second part of the MP3 player project that we’ll complete this semester. Following on from the first assignment, we now start handling real MP3 files and extracting information about the track from them. We also modify the TrackList class to hold Track objects and support sorting of tracks and searching for tracks by title. Finally we will read and write track lists as M3U format files. These are commonly used to exchange track lists between desktop MP3 players.

As before, this document sets out the main requirements for the assignment but more detail is given in some of the unit tests that you are supplied with. For this assignment you will be given most of the required tests, but you will be asked to write some tests yourself. You will be assesed based on your code passing our tests and on the quality of your code, tests and documentation.

The work for this assignment is split into three parts: implmenting and testing the Track class, implementing search and sort methods on the TrackList class, and reading and writing files. The last of these is intended as an extension for students looking for higher grades.

All queries to Steve.Cassidy@mq.edu.au or via the Assignment Discussion Forum on iLearn. See image.

The Track Class

The first modification to the earlier project is to build an explicit representation of a track which can hold more information about an MP3 file. We do this with a Track class which represents an mp3 file on the file system; we can then use instances of Track to manipulate mp3 files; in our case, we will use it to extract various properties of the file, such as the artist, track name and album title.

To extract information from the MP3 file we will use a third party library that can read the ID3 format tags stored in most MP3 files. Instructions on how to install and use the jid3lib library from http:// javamusictag.sourceforge.net/ will be given later.

The Track class provides the following interface:

• public Track(String filename) the class constructor takes a single argument that should be the name of a file on the filesystem. The constructor verifies that the file exists and initialises its internal data structures.
• public String getFilename() return the filename associated with the Track instance.
• public String getTitle() return the title of the mp3 file associated with the track. If possible, the title is taken from the ID3 tags but if there is no title stored, the name of the file is returned without any directory names or the final .mp3 extension. For example, if the filename was music\song3.mp3" the title would be "song3" if no ID3 tag were available.
• public String getArtist() return the name of the lead artist on the track based on the ID3 tags. If no suitable tag is available, return the empty string "".
• public String getAlbum() return the title of the album that the track belongs to based on the ID3 tags. If no suitable tag is available, return the empty string "".
• public int getTrackNumber() return the track number of the track based on the ID3 tags. If no suitable tag is available, return 0 (zero).

No tests are provided for the Track class. Part of your task is to write suitable tests for the above methods.

The TrackList Class

The TrackList class is similar to the one that you implemented in assignment 1 except that it stores an array of Track instances rather than an array of Strings.

You are provided with a modified version of the assignment 1 solution which implements all of the methods you wrote for TrackList but using Tracks instead of Strings. The only difference in this implementation is that no TrackListFull exception is thrown by the append method. Instead, if there is no room for the track being added, the grow method is called to make more space. The tests have also been modified and the code you are given passes all of the relevant tests. One method, contains has been removed as it is replaced with a different search method below.

Your task is to extend the TrackList class with a number of new methods relevant to handling lists of MP3 Tracks. These relate to sorting and searching the list, and reading and writing tracklist M3U files. The new methods are split into two groups: one is core and should be completed by everyone, the other is an extension and should be completed by those aiming for a higher grade.

The core set of methods relate to searching and sorting track lists:

• public int findTitle(String title) Find a track with the given title in the track list. If the track is found, return the index of the track, otherwise return -1.
• public void sortArtist() sort the TrackList based on the name of the artist in each track. The sort modifies the track list and must be a stable sort. You may not use the built in sort imple- mentation.
• public void sortAlbumTrack() sort the Tracklist based on both the album name and track number on each track. The resulting order will have all the tracks for each album grouped together ordered by track number with the album groups ordered based on the album title. So "Aardvark Kiss" Track 1 would come before "Aardvark Kiss" Track 3 and both would come before "Buffalo Bump" Track 9. You may not use the built in sort implementation.

The extension set of methods relate to reading and writing lists of tracks and generating track lists from a directory of MP3 files.

• public boolean readM3UFile(String filename) Read a track list from an M3U format file (for details see below). Any existing tracks stored in the track list are replaced by those read from the file. If an MP3 file named in the M3U file is not found, it is silently ignored. This method will throw a FileNotFound exception if the M3U file can’t be opened.
• public void writeM3UFile(String filename) Write the current track list to an M3U format file. Each filename written should be relative to the directory the M3U file is written in. So if the M3U file is C:\Music\Blues.m3u and the track filename was C:\Music\Blues\Kevin_MacLeod_-_01_-_Niles_ Blues.mp3 then the M3U file should contain Blues\Kevin_MacLeod_-_01_-_Niles_Blues.mp3. This method will throw a FileNotFound exception if the M3U file can’t be opened.
• public void readDirectory(String directory) Generate a track list by scanning for MP3 files in the given directory on the file system. Only files ending in a .mp3 extension should be included in the track list. Any other files, or any mp3 file that can’t be read, will be silently ignored.

M3U Files

An M3U file is a very simple file format used to exchange lists of tracks for MP3 players. You may have come accross them if you’ve used desktop players such as Winamp. M3U files are very simple: each line is the name of an MP3 file which can be either:

• an absolute local path name (e.g. C:\Music\TheLegends\Hooluu.mp3)
• a local path name relative to the location of the M3U file (e.g. TheLegends\Hooluu.mp3)
• a URL for an MP3 file on the web (e.g. http://tunez.org/Hooluu.mp3)

In addition, any line beginning with the # character is ignored as a comment. Blank lines are allowed in the file and are ignored. For this assignment, we will only work with M3U files containing relative local path names. So an example M3U playlist would be: See image.

If this file were stored in the directory C:\Music then you would expect to find the first track in C:\Music\ Blues\Kevin_MacLeod_-_01_-_Niles_Blues.mp3.

Using the JID3lib Library

MP3 files can contain tags with information about the track such as artist, title, album and track number. To read these tags you need to look inside the MP3 file and understand its format. This is a complex task and so we will take advantage of someone elses work and use a library to get access to tag information.

The Java ID3 Tag Library is an open source project http://javamusictag.sourceforge.net/ that provides a library to access ID3 tags in MP3 files. The full documentation and some useful examples can be found on the website. You need to download the file jid3lib-0.5.4.jar. (A Jar file is a Java library archive, it contains all of the compiled class definitions for that libary). Download this file and copy it to somewhere in your file space - that is, don’t leave it in a temporary directory.

To make use of the library in your Eclipse project you need to add this JAR file to the build path. Here is the procedure:

• From the Project menu choose Properties, this should show the properties window
• Choose "Java Build Path" in menu on left
• Choose the Libraries tab
• Choose "Add External JARS", this should show a file chooser window
• Select the jid3lib-0.5.4.jar file you downloaded
• Click OK, you should now have access to the ID3 library

You can read the full documentation and examples on the website but the main things you will need from this library are as follows:

• The MP3File class is sort of like our Track class, it provides methods to access information about the MP3 file.
• The getID3v2Tag method of MP3File returns an instance of the ID3v2_3 class which can be used to access tag values for this file.
• Various methods of the ID3v2_3 class such as getSongTitle

Sample Files

Included in the zip file starter pack are a number of sample MP3 files. These were downloaded from http://freemusicarchive.org/ which provides music that can be redistributed with attribution (which is provided in the TrackListTest.java comments). The tracks are stored in the music directory. One MP3 file is provided that has no ID3 tag information - Theme - Fat Albert.mp3, this is taken from the test data that comes with the JID3Lib distribution. The remaining tracks in the Test directory all contain usable ID3 tags and can be used for testing searching and sorting.

Unit Tests

You are provided with a set of JUnit tests for the TrackList class which test the provided methods and those you are asked to write above. Part of the mark for this assignment will be based on your code passing these tests. You are also required to write tests for the Track class. In grading your assignment, we will run our own set of tests against your implementation. Your tests will be checked manually for quality and completeness.

Using TrackList

Your final task, once you have passed all of the tests that are provided, is to write a simple application that makes use of the TrackList class. This means that you need to define a public static void main(String[] args) method either in the TrackList class or in a new class that you define. Your application should:

• prompt the user to enter a directory name
• generate a track list from the files in that directory
• prompt the user for an M3U file name
• write out an M3U file with tracks ordered by Album and Track number

Clearly, this requires that you have completed the extension parts of the TrackList class. If you only complete the core methods, you won’t be able to do this part of the assignment.