com.beaglebuddy.mp3

## Class MP3

- java.lang.Object
- - com.beaglebuddy.mp3.MP3BaseID3v23
  - - com.beaglebuddy.mp3.MP3BaseID3v24
    - - com.beaglebuddy.mp3.MP3Base
      - - com.beaglebuddy.mp3.MP3

-     public class MP3
      extends MP3Base

  This class provides high level, easy to use functions for working with .mp3 files. In particular, it provides a simple, easy to use yet powerful interface for getting and setting information about the song stored in the .mp3 file. Internally, this information is stored in a tag (most commonly an `ID3v2.3 tag`) embedded in the .mp3 file. And by most commonly, I mean 99.9% of the time. Occasionally, an .mp3 file will contain an `ID3v2.4 tag`. The format of an .mp3 file is shown below:

  You don't have to know any of the details about the low level format of an `ID3v2.3 tag` or `ID3v2.4 tag` in order to use this class. You can simply open an .mp3 file, and then use the MP3 class's methods to get or set the information you want. You can set things like the name of the song, the track number, the name of the band, who wrote the song, the lyrics to the song, the album the song was released on, store images of the CD cover, etc. all without knowing a single thing about `ID3v2.3 tags`. All of the details are handled for you. To see how easy the MP3 class is to use, look at the numerous examples of sample code provided in the sample_code/src directory. For a quick start, take a look at the sample code shown below:

       import java.io.File;
       import java.io.IOException;
       import com.beaglebuddy.mp3.MP3;
       import com.beaglebuddy.id3.enums.Genre;
       import com.beaglebuddy.id3.enums.PictureType;

       public class MP3Example
       {
          public static void main(String[] args)
          {
             try
             {
                MP3 mp3 = new MP3("c:/mp3/Wild Cat.mp3");

                // if there was any invalid information (ie, ID3v2.x frames) in the .mp3 file,
                // then display the errors to the user
                if (mp3.hasErrors())
                {
                   mp3.displayErrors(System.out);      // display the errors that were found
                   mp3.save();                         // discard the invalid information (ID3v2.x frames) and
                }                                      // save only the valid frames back to the .mp3 file

                mp3.setBand("Axel Rudi Pell");
                mp3.setAlbum("Wild Obsession");
                mp3.setTitle("Wild Cat");              // name of the song
                mp3.setMusicType(Genre.HARD_ROCK);     // 79 == Hard Rock
                mp3.setRating(220);                    // 1= worst, 255 = best
                mp3.setTrack(1);
                mp3.setYear(1989);                     // year the song was released
                mp3.setLyrics("Like a wild cat, breakin' out of my cage\n...");
                mp3.setPicture(PictureType.FRONT_COVER, new File("c:/images/axel_rudi_pell.wild_obsession.jpg"));

                if (mp3.getAudioDuration() == 0)       // if the length of the song hasn't been specified,
                   mp3.setAudioDuration(221);          // if you know how long the song is:  221 seconds == 3 minutes and 41 seconds
                mp3.setAudioDuration();                // otherwise, calculate it from the mpeg audio frames

                mp3.save();
             }
             catch (IOException ex)
             {
                System.out.println("An error occurred while reading/saving the mp3 file.");
             }
          }
       }

  But, if you're an ID3v2.x tag expert, and want to work directly with the tag itself, then you certainly can do that as well. Just call the MP3 class's `getID3v23Tag()` or `getID3v24Tag()` method in order to get direct access to the `ID3v23Tag`/`ID3v24Tag` tag.

  One thing that you should take a look at is how the Beaglebuddy MP3 library handles errors that are encountered while reading in an existing .mp3 file. Please see the `ID3v23Frame` or `ID3v24Frame` class for the details on the Beaglebuddy MP3 library's error handling.

- - ### Field Summary

    - ### Fields inherited from class com.beaglebuddy.mp3.MP3Base

      `apeTag, audioSize, bitrate, bitrateType, fileSize, id3v1Tag, lyrics3v1Tag, lyrics3v2Tag, mp3File, mp3Url, mpegFrame, tagSize`

    - ### Fields inherited from class com.beaglebuddy.mp3.MP3BaseID3v24

      `id3v24Tag`

    - ### Fields inherited from class com.beaglebuddy.mp3.MP3BaseID3v23

      `id3v23Tag`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `MP3(java.io.File mp3File)` This constructor reads the ID3 tag(s), which contain the information about the song, from the .mp3 file.
    `MP3(java.io.InputStream inputStream)` This constructor reads the ID3 tag(s), which contain the information about the song, from the .mp3 file pointed to by the specified input stream.
    `MP3(java.lang.String mp3File)` This constructor reads the ID3 tag(s), which contain the information about the song, from the .mp3 file.
    `MP3(java.net.URL mp3URL)` This constructor reads the ID3 tag(s), which contain the information about the song, from the .mp3 file located at the specified URL.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `clear()` clears all the information (ie, frames) in the ID3v2.x tag from the .mp3 file.
    `java.lang.String` | `getAlbum()` gets the name of the album on which the .mp3 song was released.
    `int` | `getAudioDuration()` gets the duration (in seconds) of the song in the .mp3 file.
    `int` | `getAudioSize()` gets the size (in bytes) of the audio portion of the .mp3 file.
    `java.lang.String` | `getBand()` gets the name of the band who recorded the .mp3 song.
    `int` | `getBitrate()` gets the bit rate in kbps (kilobits per second) at which the mp3 file was created.
    `BitrateType` | `getBitrateType()` gets the type of bit rate used to encode the .mp3 file, either constant or variable.
    `ChannelMode` | `getChannelMode()` gets the channel mode (stereo or mono) used to encode the .mp3 file.
    `java.lang.String` | `getCodec()` gets the codec (coder - decoder) used to encode this .mp3 file.
    `java.lang.String` | `getComments()` gets the comments about the song.
    `int` | `getDisc()` gets the disc number of the cd on which the song was released.
    `int` | `getFrequency()` gets the frequency (in herz - hz), which specifies how many times per second the audio is sampled and stored as a number in the .mp3 file.
    `Layer` | `getLayer()` gets the MPEG layer of this .mp3 file.
    `java.lang.String` | `getLeadPerformer()` gets the name of the lead performer who recorded the .mp3 song.
    `java.lang.String` | `getLyrics()` gets the (english) lyrics to the song.
    `java.lang.String` | `getLyrics(Language language)` gets the lyrics to the song in the specified language.
    `java.lang.String` | `getLyricsBy()` gets name of the person(s) who wrote the lyrics to the song.
    `MPEGVersion` | `getMPEGVersion()` gets the MPEG version of this .mp3 file.
    `java.lang.String` | `getMusicBy()` gets name of the person(s) who wrote the music to the song.
    `java.lang.String` | `getMusicType()` gets the category of music for this song.
    `AttachedPicture` | `getPicture(PictureType type)` gets the attached picture for the specified picture type.
    `java.util.List<AttachedPicture>` | `getPictures()` gets all the pictures stored in the .mp3 file's tag.
    `java.lang.String` | `getPublisher()` gets the publisher of the song.
    `int` | `getRating()` gets the rating (ie, how much you like it) of the song.
    `java.util.List<SynchronizedLyric>` | `getSynchronizedLyrics()` gets the (english) synchronized lyrics to the song.
    `java.util.List<SynchronizedLyric>` | `getSynchronizedLyrics(Language language)` gets the synchronized lyrics to the song in the specified language.
    `java.lang.String` | `getTitle()` gets the name of the song stored in the .mp3 file.
    `int` | `getTrack()` gets the track number of the song.
    `ID3TagVersion` | `getVersion()` gets the version of the ID3 tag stored in the .mp3 song which holds all of the information about the .mp3 file.
    `int` | `getYear()` gets the year the song was recorded.
    `void` | `removeAlbum()` removes the name of the album on which the .mp3 song was released.
    `void` | `removeAudioDuration()` removes the duration of the song from the .mp3 file.
    `void` | `removeAudioSize()` removes the size of the audio portion of the song from the .mp3 file.
    `void` | `removeBand()` removes the name of the band who recorded the song from the .mp3 file.
    `void` | `removeComments()` removes the comment about the song from the .mp3 file.
    `void` | `removeDisc()` removes the disc number of the cd on which song was released from the .mp3 file.
    `void` | `removeLeadPerformer()` removes the name of the lead performer who recorded the song from the .mp3 file.
    `void` | `removeLyrics()` removes the (english) lyrics to the song from the .mp3 file.
    `void` | `removeLyrics(Language language)` removes the lyrics in the specified language to the song from the .mp3 file.
    `void` | `removeLyricsBy()` removes the name of the person(s) who wrote the lyrics to the song from the .mp3 file.
    `void` | `removeMusicBy()` removes the name of the person(s) who wrote the music to the song from the .mp3 file.
    `void` | `removeMusicType()` removes the type of music for the song from the .mp3 file.
    `void` | `removePicture(PictureType type)` removes the picture of the specified type from the .mp3 file.
    `java.util.List<AttachedPicture>` | `removePictures()` removes all the picture(s) from the .mp3 file.
    `void` | `removePublisher()` removes the publisher of the the song from the .mp3 file.
    `void` | `removeRating()` removes the rating from the .mp3 file.
    `void` | `removeSynchronizedLyrics()` remove the (english) synchronized lyrics from the .mp3 song.
    `void` | `removeSynchronizedLyrics(Language language)` remove the synchronized lyrics in the specified language from the .mp3 song.
    `void` | `removeTitle()` removes the name of the song from the .mp3 file.
    `void` | `removeTrack()` removes the track number of the song from the .mp3 file.
    `void` | `removeYear()` removes the year the song was released from the .mp3 file.
    `void` | `save()` save the ID3v2.x tag to the .mp3 file.
    `void` | `setAlbum(java.lang.String album)` sets the name of the album on which the .mp3 song was released.
    `void` | `setAudioDuration()` sets the duration (in seconds) of the song in the .mp3 file from a calculation of the audio data.
    `void` | `setAudioDuration(int duration)` sets the duration (in seconds) of the song in the .mp3 file.
    `void` | `setAudioSize(int size)` sets the size (in bytes) of the audio portion of the .mp3 file.
    `void` | `setBand(java.lang.String band)` sets the name of the band who recorded the .mp3 song.
    `void` | `setComments(java.lang.String comments)` stores a comment about the song in the .mp3 file.
    `void` | `setDisc(int disc)` sets the disc number of the cd on which the song was released.
    `void` | `setLeadPerformer(java.lang.String leadPerformer)` sets the name of the lead performer who recorded the .mp3 song.
    `void` | `setLyrics(Language language, java.lang.String lyrics)` sets the lyrics to the song using the specified language.
    `void` | `setLyrics(java.lang.String lyrics)` sets the (english) lyrics to the song.
    `void` | `setLyricsBy(java.lang.String lyricist)` sets the name of the person(s) who wrote the lyrics to the song.
    `void` | `setMusicBy(java.lang.String composer)` sets the name of the person(s) who wrote the music to the song.
    `void` | `setMusicType(Genre genre)` sets the category of music for this song.
    `void` | `setMusicType(java.lang.String type)` sets the category of music for this song.
    `void` | `setPicture(AttachedPicture attachedPicture)` adds the attached picture to the song.
    `void` | `setPicture(PictureType type, java.io.File imageFile)` adds the picture to the song.
    `void` | `setPicture(PictureType type, java.lang.String imageFilename)` adds the picture to the song.
    `void` | `setPicture(PictureType type, java.net.URL imageURL)` adds the picture to the song.
    `void` | `setPublisher(java.lang.String publisher)` sets the publisher of the the song.
    `void` | `setRating(int rating)` sets the rating of the song.
    `void` | `setSynchronizedLyrics(Language language, java.util.List<SynchronizedLyric> synchronizedLyrics)` sets the synchronized lyrics to the song in the specified language.
    `void` | `setSynchronizedLyrics(Language language, SynchronizedLyric[] synchronizedLyrics)` sets the synchronized lyrics to the song in the specified language.
    `void` | `setSynchronizedLyrics(java.util.List<SynchronizedLyric> synchronizedLyrics)` sets the (english) synchronized lyrics to the song.
    `void` | `setSynchronizedLyrics(SynchronizedLyric[] synchronizedLyrics)` sets the (english) synchronized lyrics to the song.
    `void` | `setTitle(java.lang.String title)` sets the name of the song stored in the .mp3 file.
    `void` | `setTitleFromFilename()` sets the name of the song stored in the .mp3 file from the name of the .mp3 file on disk.
    `void` | `setTrack(int track)` sets the track number of the song.
    `void` | `setYear(int year)` sets the year the song was recorded.
    `java.lang.String` | `toString()` returns a string representation of the mp3 file.

    - ### Methods inherited from class com.beaglebuddy.mp3.MP3Base

      `calculateAudioDuration, displayErrors, getAPETag, getErrors, getFileSize, getFirstMpegFrame, getID3v1Tag, getID3v24TagAtEnd, getID3v2xPadding, getLyrics3v1Tag, getLyrics3v2Tag, getPath, getReadOnlyErrorMessage, hasAPETag, hasErrors, hasID3v1Tag, hasID3v24TagAtEnd, hasLyrics3v1Tag, hasLyrics3v2Tag, isConstantBitRate, readMP3File, removeAPETag, removeID3v1Tag, removeID3v24TagAtEnd, removeLyrics3v1Tag, removeLyrics3v2Tag, saveID3v23, saveID3v24, setID3v2xPadding, validateMPEGFrames`

    - ### Methods inherited from class com.beaglebuddy.mp3.MP3BaseID3v24

      `addV24Frame, getID3v24Tag, getV24Album, getV24AttachedPicture, getV24AttachedPictureFrame, getV24AttachedPictures, getV24AudioDuration, getV24Band, getV24Comments, getV24CommentsFrame, getV24Disc, getV24Errors, getV24Frame, getV24Frames, getV24LeadPerformer, getV24LyricsBy, getV24MusicBy, getV24MusicType, getV24Publisher, getV24Rating, getV24SynchronizedLyrics, getV24SynchronizedLyricsFrame, getV24Text, getV24TextAsInteger, getV24Title, getV24Track, getV24UnsynchronizedLyrics, getV24UnsynchronizedLyricsFrame, getV24Year, hasV24Errors, removeV24Album, removeV24AttachedPicture, removeV24AttachedPictures, removeV24AudioDuration, removeV24AudioSize, removeV24Band, removeV24Comments, removeV24Comments, removeV24Disc, removeV24Frame, removeV24Frames, removeV24LeadPerformer, removeV24LyricsBy, removeV24MusicBy, removeV24MusicType, removeV24Publisher, removeV24Rating, removeV24SynchronizedLyrics, removeV24Title, removeV24Track, removeV24UnsynchronizedLyrics, removeV24Year, setV24Album, setV24AttachedPicture, setV24AudioDuration, setV24Band, setV24Comments, setV24Disc, setV24LeadPerformer, setV24LyricsBy, setV24MusicBy, setV24MusicType, setV24MusicType, setV24Publisher, setV24Rating, setV24SynchronizedLyrics, setV24SynchronizedLyrics, setV24SynchronizedLyrics, setV24Text, setV24Text, setV24Text, setV24Title, setV24Track, setV24UnsynchronizedLyrics, setV24Year`

    - ### Methods inherited from class com.beaglebuddy.mp3.MP3BaseID3v23

      `addV23Frame, getID3v23Tag, getV23Album, getV23AttachedPicture, getV23AttachedPictureFrame, getV23AttachedPictures, getV23AudioDuration, getV23AudioSize, getV23Band, getV23Comments, getV23CommentsFrame, getV23Disc, getV23Errors, getV23Frame, getV23Frames, getV23LeadPerformer, getV23LyricsBy, getV23MusicBy, getV23MusicType, getV23Publisher, getV23Rating, getV23SynchronizedLyrics, getV23SynchronizedLyricsFrame, getV23Text, getV23TextAsInteger, getV23Title, getV23Track, getV23UnsynchronizedLyrics, getV23UnsynchronizedLyricsFrame, getV23Year, hasV23Errors, removeV23Album, removeV23AttachedPicture, removeV23AttachedPictures, removeV23AudioDuration, removeV23AudioSize, removeV23Band, removeV23Comments, removeV23Comments, removeV23Disc, removeV23Frame, removeV23Frames, removeV23LeadPerformer, removeV23LyricsBy, removeV23MusicBy, removeV23MusicType, removeV23Publisher, removeV23Rating, removeV23SynchronizedLyrics, removeV23Title, removeV23Track, removeV23UnsynchronizedLyrics, removeV23Year, setV23Album, setV23AttachedPicture, setV23AudioDuration, setV23AudioSize, setV23Band, setV23Comments, setV23Disc, setV23LeadPerformer, setV23LyricsBy, setV23MusicBy, setV23MusicType, setV23MusicType, setV23Publisher, setV23Rating, setV23SynchronizedLyrics, setV23SynchronizedLyrics, setV23SynchronizedLyrics, setV23Text, setV23Text, setV23Text, setV23Title, setV23Track, setV23UnsynchronizedLyrics, setV23Year`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### MP3

          public MP3(java.lang.String mp3File)
              throws java.io.IOException

      This constructor reads the ID3 tag(s), which contain the information about the song, from the .mp3 file.
      Parameters:
        `mp3File` - path to an .mp3 file.
      Throws:
        `java.io.IOException` - if there is a problem reading the .mp3 file.

    - #### MP3

          public MP3(java.io.File mp3File)
              throws java.io.IOException

      This constructor reads the ID3 tag(s), which contain the information about the song, from the .mp3 file.
      Parameters:
        `mp3File` - file pointing to an .mp3 file.
      Throws:
        `java.io.IOException` - if there is a problem reading the .mp3 file.

    - #### MP3

          public MP3(java.net.URL mp3URL)
              throws java.io.IOException

      This constructor reads the ID3 tag(s), which contain the information about the song, from the .mp3 file located at the specified URL.

      When you load an .mp3 file from a URL, the Beaglebuddy MP3 library treats the .mp3 file as being read only. For that reason, you can not change any of the information in the .mp3 file, nor can you save it. You may only read the values that are currently stored in the .mp3 file.

      Please note that the URL must be correctly encoded. That is, it must conform to RFC 1738. A more user friendly explanation can be found at the HTML URL Encoding Reference. Also note that the java class java.net.URLEncoder does not work properly when passed an entire URL.

      Thus, the following URL will not work in java: http://www.beaglebuddy.com/content/downloads/mp3/01.Hells Bells.mp3
      Instead, you must specify the correctly encoded URL to the MP3 constructor as: http://www.beaglebuddy.com/content/downloads/mp3/01.Hells%20Bells.mp3

      Another issue when accessing an .mp3 file through a URL is the use of proxy servers. If you run into the problem of being able to access an .mp3 file in your web browser, such as the following: http://www.beaglebuddy.com/content/downloads/mp3/01.Hells%20Bells.mp3
      but using the exact same URL in your java program does not work (you get a connection time out error message), then perhaps you're internet connection is utilizing a proxy server. If so, you can solve this problem by specifying the proxy server's host and port as system properties in one of two ways:

      1. Specifying them as Defines on the command line to the java JRE
      2. Specifying them with java code in your application
      To specify them on the command line, do something like the following:
      `

           %java_jre_home%\java -Dhttp.proxyHost=usproxy.mycompany.com -Dhttp.proxyPort=9000 -classpath beaglebuddy_mp3.jar;. com.beaglebuddy.mp3.sample_code.BasicURL

      ` To specify them in your code, add the following two lines to your code
      `

           System.setProperty("http.proxyHost", "usproxy.mycompany.com");
           System.setProperty("http.proxyPort", "9000");

      ` See the sample code provided in the com.beaglebuddy.mp3.sample_code.BasicURL for an example of how to load an .mp3 from a URL.
      Parameters:
        `mp3URL` - URL to an .mp3 file.
      Throws:
        `java.io.IOException` - if there is a problem reading the .mp3 file.

    - #### MP3

          public MP3(java.io.InputStream inputStream)
              throws java.io.IOException

      This constructor reads the ID3 tag(s), which contain the information about the song, from the .mp3 file pointed to by the specified input stream. This constructor is usefull for reading .mp3 files from a compressed source (.zip file), from a 3rd party streaming source, etc.

      When you load an .mp3 file from a generic input stream, the Beaglebuddy MP3 library treats the .mp3 file as being read only. For that reason, you can not change any of the information in the .mp3 file, nor can you save it. You may only read the values that are currently stored in the .mp3 file.

      Parameters:
        `inputStream` - An input stream pointing to an .mp3 file.
      Throws:
        `java.io.IOException` - if there is a problem reading the contents of the .mp3 file from the input stream.

  - ### Method Detail

    - #### clear

          public void clear()
                     throws java.lang.IllegalStateException

      clears all the information (ie, frames) in the ID3v2.x tag from the .mp3 file.
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.

    - #### save

          public void save()
                    throws java.io.IOException,
                           java.lang.IllegalStateException

      save the ID3v2.x tag to the .mp3 file. Any invalid frames that were found while reading in the .mp3 file are discarded, thereby ensuring that saved .mp3 file contains only valid information.
      Throws:
        `java.io.IOException` - if there was an error writing the ID3v2.x tag to the .mp3 file.
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.

    - #### getCodec

          public java.lang.String getCodec()

      gets the codec (coder - decoder) used to encode this .mp3 file.
      Returns:
        the codec used to encode this .mp3 file.

    - #### getMPEGVersion

          public MPEGVersion getMPEGVersion()

      gets the MPEG version of this .mp3 file.
      Returns:
        the MPEG version of this .mp3 file.

    - #### getLayer

          public Layer getLayer()

      gets the MPEG layer of this .mp3 file.
      Returns:
        the MPEG layer of this .mp3 file.

    - #### getBitrate

          public int getBitrate()

      gets the bit rate in kbps (kilobits per second) at which the mp3 file was created. If the .mp3 file was encoded using a constant bit rate (CBR), then the bit rate returned is the actual bit rate. If the .mp3 file was encoded using a variable bit rate (VBR), then the bit rate returned is an average bit rate.
      Returns:
        the bit rate in kbps (kilobits per second) at which the mp3 file was created. If the .mp3 file was encoded using a variable bit rate (VBR), then the average bitrate is calculated by reading through the `MPEG audio frames` in the .mp3 file. If an error occurs during this process, then -1 is returned.
      See Also:
        definition of kbps

    - #### getBitrateType

          public BitrateType getBitrateType()

      gets the type of bit rate used to encode the .mp3 file, either constant or variable.
      Returns:
        the type of bit rate used to encode the .mp3 file.

    - #### getFrequency

          public int getFrequency()

      gets the frequency (in herz - hz), which specifies how many times per second the audio is sampled and stored as a number in the .mp3 file. CD audio is sampled at 44.1 khz, which means 44,100 samples per second.
      Returns:
        the sampling frequency (in hz) used to convert the analog audio to a digital .mp3 file. A value of -1 indicates an invalid value due to the MPEG version

    - #### getChannelMode

          public ChannelMode getChannelMode()

      gets the channel mode (stereo or mono) used to encode the .mp3 file.
      Returns:
        the channel mode (stereo or mono) used to encode the .mp3 file.

    - #### getAlbum

          public java.lang.String getAlbum()

      gets the name of the album on which the .mp3 song was released.
      Example:`

               // load the song "Something for Nothing" from Rush's "2112" album.
               MP3 mp3 = new MP3("c:/mp3/rush/2112/something for nothing.mp3");
               System.out.println("the song " + mp3.getTitle() + " was released on the album " + mp3.getAlbum());

      `
      Returns:
        the album on which the song was released. If no album has been specified for this song, then null is returned.
      See Also:
        `setAlbum(String)`, `removeAlbum()`

    - #### setAlbum

          public void setAlbum(java.lang.String album)
                        throws java.lang.IllegalStateException

      sets the name of the album on which the .mp3 song was released.
      Example:`

               // load the song "Something for Nothing" from Rush's "2112" album.
               MP3 mp3 = new MP3("c:/mp3/rush/2112/something for nothing.mp3");
               mp3.setAlbum("2112");
               System.out.println("the song " + mp3.getTitle() + " was released on the album " + mp3.getAlbum());

      `
      Parameters:
        `album` - the name of the album on which the .mp3 song was released.
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getAlbum()`, `removeAlbum()`

    - #### removeAlbum

          public void removeAlbum()
                           throws java.lang.IllegalStateException

      removes the name of the album on which the .mp3 song was released.
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getAlbum()`, `setAlbum(String)`

    - #### getAudioDuration

          public int getAudioDuration()

      gets the duration (in seconds) of the song in the .mp3 file.
      Example:`

               // load the song "El Laberinto del Minotauro" from Tierra Santa's "Sangre de Reyes" album.
               MP3 mp3     = new MP3("c:/mp3/tierra santa/sangre de reyes/el laberinto del minotauro.mp3");
               int minutes = mp3.getAudioDuration() / 60;
               int seconds = mp3.getAudioDuration() % 60;
               System.out.println("the song " + mp3.getTitle() + " is " + minutes + " minutes and " + seconds + " seconds long.");

      `
      Returns:
        the duration (in seconds) of the song in the .mp3 file. . If no audio duration has been specified, then 0 is returned.
      See Also:
        `setAudioDuration()`, `setAudioDuration(int)`, `removeAudioDuration()`

    - #### setAudioDuration

          public void setAudioDuration()
                                throws java.lang.IllegalArgumentException,
                                       java.lang.IllegalStateException

      sets the duration (in seconds) of the song in the .mp3 file from a calculation of the audio data.
      Example:`

               // load the song "El Laberinto del Minotauro" from Tierra Santa's "Sangre de Reyes" album.
               MP3 mp3 = new MP3("c:/mp3/tierra santa/sangre de reyes/el laberinto del minotauro.mp3");
               mp3.setAudioDuration();              // calculate the duration of the song from the audio data in the .mp3
               int minutes = mp3.getAudioDuration() / 60;
               int seconds = mp3.getAudioDuration() % 60;
               System.out.println("the song " + mp3.getTitle() + " is " + minutes + " minutes and " + seconds + " seconds long.");

      `
      Throws:
        `java.lang.IllegalArgumentException` - If the calculated duration is less than 0.
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getAudioDuration()`, `setAudioDuration(int)`, `removeAudioDuration()`

    - #### setAudioDuration

          public void setAudioDuration(int duration)
                                throws java.lang.IllegalArgumentException,
                                       java.lang.IllegalStateException

      sets the duration (in seconds) of the song in the .mp3 file.
      Example:`

               // load the song "El Laberinto del Minotauro" from Tierra Santa's "Sangre de Reyes" album.
               MP3 mp3 = new MP3("c:/mp3/tierra santa/sangre de reyes/el laberinto del minotauro.mp3");
               mp3.setAudioDuration(307);           // 5 minutes and 7 seconds == 5 * 60 + 7 == 307 seconds
               int minutes = mp3.getAudioDuration() / 60;
               int seconds = mp3.getAudioDuration() % 60;
               System.out.println("the song " + mp3.getTitle() + " is " + minutes + " minutes and " + seconds + " seconds long.");

      `
      Parameters:
        `duration` - the duration (in seconds) of the song in the .mp3 file.
      Throws:
        `java.lang.IllegalArgumentException` - If the duration is less than 0.
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getAudioDuration()`, `removeAudioDuration()`

    - #### removeAudioDuration

          public void removeAudioDuration()
                                   throws java.lang.IllegalStateException

      removes the duration of the song from the .mp3 file.
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getAudioDuration()`, `setAudioDuration(int)`

    - #### getAudioSize

          public int getAudioSize()

      gets the size (in bytes) of the audio portion of the .mp3 file. See the mp3 file format to view where the audio portion of a song is stored in an .mp3 file.
      Example:`

               // load the song "All We Are" from Warlock's "Triumph and Agony" album.
               MP3 mp3 = new MP3("c:/mp3/warlock/triumph and agony/all we are.mp3");
               System.out.println("the size of the .mp3 file " + mp3.getPath() + " is " + mp3.getFileSize() + " bytes");
               System.out.println("the actual audio portion of the song " + mp3.getTitle() + " stored in the .mp3 file is " + mp3.getAudioSize() + " bytes");

      `
      Returns:
        the size (in bytes) of the audio portion of the .mp3 file. If no audio size has been specified, then 0 is returned.
      See Also:
        `setAudioSize(int)`, `removeAudioSize()`

    - #### setAudioSize

          public void setAudioSize(int size)
                            throws java.lang.IllegalArgumentException,
                                   java.lang.IllegalStateException

      sets the size (in bytes) of the audio portion of the .mp3 file. See the mp3 file format to view where the audio portion of a song is stored in an .mp3 file.
      Example:`

               // load the song "All We Are" from Warlock's "Triumph and Agony" album.
               MP3 mp3 = new MP3("c:/mp3/warlock/triumph and agony/all we are.mp3");
               mp3.setAudioSize(3202068);
               System.out.println("the size of the .mp3 file " + mp3.getPath() + " is " + mp3.getFileSize() + " bytes");
               System.out.println("the actual audio portion of the song " + mp3.getTitle() + " stored in the .mp3 file is " + mp3.getAudioSize() + " bytes");

      `
      Parameters:
        `size` - size (in bytes) of the audion portion of the .mp3 file.
      Throws:
        `java.lang.IllegalArgumentException` - If the audio size is less than or equal 0.
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getAudioSize()`, `removeAudioSize()`

    - #### removeAudioSize

          public void removeAudioSize()
                               throws java.lang.IllegalStateException

      removes the size of the audio portion of the song from the .mp3 file.
      Throws:
        `java.lang.IllegalStateException` - If the mp3 song was loaded from a URL and therefore is considered read only and may not be modified.
      See Also:
        `getAudioSize()`, `setAudioSize(int)`

    - #### getBand

          public java.lang.String getBand()

      gets the name of the band who recorded the .mp3 song. On Windows machines, this is called the "Artist".
      Note for ID3 tag experts: Some mp3 software stores the name of the band in `TPE2` frames, which is what the getBand() method returns, while other mp3 software use `TPE1` frames, which is what the `getLeadPerformer()` method returns. So, we recommend calling getBand() first, checking if it is null, and if so, calling getLeadPerformer().
      Example:`

               // load the song "Beads Of Ebony" from Praying Mantis's "Time Tells No Lies" album.
               MP3 mp3 = new MP3("c:/mp3/praying mantis/time tells no lies/beads of ebony.mp3");
               String band = mp3.getBand() != null ? mp3.getBand() : mp3.getLeadPerformer();
               System.out.println("the song " + mp3.getTitle() + " was released by " + band + " on the album " + mp3.getAlbum());

      `
      Returns:
        the band who recorded the .mp3 song. If no band has been specified, then null is returned.
      See Also:
        `setBand(String)`, `getLeadPerformer()`, `removeBand()`

    - #### setBand

          public void setBand(java.lang.String band)
                       throws java.lang.IllegalStateException

      sets the name of the band who recorded the .mp3 song.
      Note for ID3 tag experts: The Beaglebuddy MP3 class stores the name of the band in the `TPE2` frame.
      Example:`

               // load the song "Beads Of Ebony" from Praying Mantis's "Time Tells No Lies" album.
               MP3 mp3 = new MP3("c:/mp3/praying mantis/time tells no lies/beads of ebony.mp3");
               mp3.setBand("Praying Mantis");
               System.out.println("the song " + mp3.getTitle() + " was released by " + mp3.getBand() + " on the album " + mp3.getAlbum());

      `
      Parameters:
        `band` - the band who recorded the song.
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getBand()`, `removeBand()`

    - #### removeBand

          public void removeBand()
                          throws java.lang.IllegalStateException

      removes the name of the band who recorded the song from the .mp3 file.
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getBand()`, `setBand(String)`

    - #### getComments

          public java.lang.String getComments()

      gets the comments about the song.
      Note for ID3 tag experts: While the ID3v2.x standards support storing multiple comments within an .mp3 file, with one comment for each of the 504 languages defined by the `ISO-639-2` standard, in practice this is never done, and as such, the MP3 class only supports storing one comment in an .mp3 file.
      Example:`

               // load the song "Pas Plus de Seize Ans" from Voie de Fait's "Ange ou Démon" album.
               MP3 mp3 = new MP3("c:/mp3/voie de fait/ange ou démon/pas plus de seize ans.mp3");
               if (mp3.getComments() == null)
                  System.out.println("the song " + mp3.getTitle() + " does not have any comments");
               else
                  System.out.println("the song " + mp3.getTitle() + " has a comment: " + mp3.getComments());

      `
      Returns:
        the comments about the song. If no comments have been specified, then null is returned.
      See Also:
        `setComments(String)`, `removeComments()`

    - #### setComments

          public void setComments(java.lang.String comments)
                           throws java.lang.IllegalStateException

      stores a comment about the song in the .mp3 file.
      Note for ID3 tag experts: While the ID3v2.x standards support storing multiple comments within an .mp3 file, with one comment for each of the 504 languages defined by the `ISO-639-2` standard, in practice this is never done, and as such, the MP3 class only supports storing one comment in an .mp3 file.
      Example:`

               // load the song "Pas Plus de Seize Ans" from Voie de Fait's "Ange ou Démon" album.
               MP3 mp3 = new MP3("c:/mp3/voie de fait/ange ou démon/pas plus de seize ans.mp3");
               mp3.setComments("I like this song");            // write a comment in english
               mp3.setComments("Das Lied gefällt mir");        // write a comment in german  - overwrites the previous english comment
               mp3.setComments("Me gusta esta Canción");       // write a comment in spanish - overwrites the previous german  comment
               System.out.println("the song " + mp3.getTitle() + " has a comment: " + mp3.getComments());

      `
      Parameters:
        `comments` - comment about the song.
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getComments()`, `removeComments()`

    - #### removeComments

          public void removeComments()
                              throws java.lang.IllegalStateException

      removes the comment about the song from the .mp3 file.
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getComments()`, `setComments(String)`

    - #### getDisc

          public int getDisc()

      gets the disc number of the cd on which the song was released. This is useful for double album cds and boxed set collections.
      Example:`

               // load the song "Phoenix Rising" from "Voices Of Rock"'s "MMVII" album.
               MP3 mp3 = new MP3("c:/mp3/voices of rock/mmvii/phoenix rising.mp3");
               mp3.getDisc();            // get the disc number
               System.out.println("the .mp3 song " + mp3.getTitle() + "  is on cd disc #" + mp3.getDisc() + ".");

      `
      Returns:
        the disc number of the cd on which the song was released. If no disc number has been specified, then 0 is returned.
      See Also:
        `setDisc(int)`, `removeDisc()`

    - #### setDisc

          public void setDisc(int disc)
                       throws java.lang.IllegalArgumentException,
                              java.lang.IllegalStateException

      sets the disc number of the cd on which the song was released. This is useful for double album cds and boxed set collections.
      Example:`

               // load the song "Phoenix Rising" from "Voices Of Rock"'s "MMVII" album.
               MP3 mp3 = new MP3("c:/mp3/voices of rock/mmvii/phoenix rising.mp3");
               mp3.setDisc(2);            // set the disc number to 2
               System.out.println("the .mp3 song " + mp3.getTitle() + "  is on cd disc #" + mp3.getDisc() + ".");

      `
      Parameters:
        `disc` - the disc number of the cd on which the song was released. It must be >= 1.
      Throws:
        `java.lang.IllegalArgumentException` - if the disc number is <= 0.
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getDisc()`, `removeDisc()`

    - #### removeDisc

          public void removeDisc()
                          throws java.lang.IllegalStateException

      removes the disc number of the cd on which song was released from the .mp3 file. If `getDisc()` is subsequently called, it will return 0.
      Example:`

               // load the song "Phoenix Rising" from "Voices Of Rock"'s "MMVII" album.
               MP3 mp3 = new MP3("c:/mp3/voices of rock/mmvii/phoenix rising.mp3");
               mp3.removeDisc();            // removes the disc number from the .mp3 file
               System.out.println("the .mp3 song " + mp3.getTitle() + "  is on cd disc #" + mp3.getDisc() + " on the cd.");

      `
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getDisc()`, `setDisc(int)`

    - #### getLeadPerformer

          public java.lang.String getLeadPerformer()

      gets the name of the lead performer who recorded the .mp3 song. On Windows machines, this is called the "Contributing artist".
      Example:`

               // load the song "Last Tribe" from Magnus Karlson's "FreeFall" album.
               MP3 mp3 = new MP3("c:/mp3/magnus karlson/freefall/last tribe.mp3");
               System.out.println("the song " + mp3.getTitle() + " was released by " + mp3.getLeadPerformer() + " on the album " + mp3.getAlbum());

      `
      Returns:
        the lead performer who recorded the .mp3 song. If no lead performer has been specified, then null is returned.
      See Also:
        `setLeadPerformer(String)`, `removeLeadPerformer()`

    - #### setLeadPerformer

          public void setLeadPerformer(java.lang.String leadPerformer)
                                throws java.lang.IllegalStateException

      sets the name of the lead performer who recorded the .mp3 song.
      Note for ID3 tag experts: The Beaglebuddy MP3 class stores the name of the lead performer in the `TPE1` frame.
      Example:`

               // load the song "Last Tribe" from Magnus Karlson's "FreeFall" album.
               MP3 mp3 = new MP3("c:/mp3/magnus karlson/freefall/last tribe.mp3");
               mp3.setleadPerformer("Magnus Karlson");
               System.out.println("the song " + mp3.getTitle() + " was released by " + mp3.getLeadPerformer() + " on the album " + mp3.getAlbum());

      `
      Parameters:
        `leadPerformer` - the lead performer who recorded the song.
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getLeadPerformer()`, `removeLeadPerformer()`

    - #### removeLeadPerformer

          public void removeLeadPerformer()
                                   throws java.lang.IllegalStateException

      removes the name of the lead performer who recorded the song from the .mp3 file.
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getLeadPerformer()`, `setLeadPerformer(String)`

    - #### getLyrics

          public java.lang.String getLyrics()

      gets the (english) lyrics to the song.
      Example:`

               // load the song "Lethal Heroes" from Pretty Maids' "Jump The Gun" album.
               MP3 mp3 = new MP3("c:/mp3/pretty maids/jump the gun/lethal heroes.mp3");

               System.out.print("the song " + mp3.getTitle() + " was released by " + mp3.getBand() + " on the album " + mp3.getAlbum());
               if (mp3.getLyrics() == null)
                  System.out.println(" does not contain any english lyrics.");
               else
                  System.out.println(" contains the following english lyrics: \n" + mp3.getLyrics());

      `
      Returns:
        the (english) lyrics to the song. If no (english) lyrics have been specified, then null is returned.
      See Also:
        `getLyrics(Language)`, `getLyricsBy()`, `setLyrics(String)`, `setLyrics(Language, String)`, `getSynchronizedLyrics()`, `removeLyrics()`, `removeLyrics(Language)`

    - #### getLyrics

          public java.lang.String getLyrics(Language language)

      gets the lyrics to the song in the specified language.
      Example:`

               // load the song "Lethal Heroes" from Pretty Maids' "Jump The Gun" album.
               MP3 mp3 = new MP3("c:/mp3/pretty maids/jump the gun/lethal heroes.mp3");

               System.out.print("the song " + mp3.getTitle() + " was released by " + mp3.getBand() + " on the album " + mp3.getAlbum());
               if (mp3.getLyrics(Language.DEU) == null)
                  System.out.println(" does not contain any german lyrics.");
               else
                  System.out.println(" contains the following german lyrics: \n" + mp3.getLyrics(Language.DEU));

      `
      Parameters:
        `language` - the ISO-639-2 `language` the lyrics are written in.
      Returns:
        the lyrics to the song in the specified language. If no lyrics have been specified in the specified language, then null is returned.
      See Also:
        `getLyrics()`, `getLyricsBy()`, `setLyrics(String)`, `setLyrics(Language, String)`, `getSynchronizedLyrics()`, `removeLyrics()`, `removeLyrics(Language)`

    - #### setLyrics

          public void setLyrics(java.lang.String lyrics)
                         throws java.lang.IllegalStateException

      sets the (english) lyrics to the song.
      Example:`

               // load the song "Lethal Heroes" from Pretty Maids' "Jump The Gun" album and set the "english" lyrics to the song.
               MP3 mp3 = new MP3("c:/mp3/pretty maids/jump the gun/lethal heroes.mp3");
               mp3.setLyrics("Get a little frightened sometimes\nA little cold inside\nCatching bad news on the radio\n...");

      `
      Parameters:
        `lyrics` - the (english) lyrics to the song.
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getLyrics()`, `getLyrics(Language)`, `getLyricsBy()`, `getSynchronizedLyrics()`, `removeLyrics()`, `removeLyrics(Language)`, `setLyrics(Language,String)`

    - #### setLyrics

          public void setLyrics(Language language,
                       java.lang.String lyrics)
                         throws java.lang.IllegalStateException

      sets the lyrics to the song using the specified language.
      Example:`

               // load the song "Lethal Heroes" from Pretty Maids' "Jump The Gun" album and set the "german" lyrics to the song.
               MP3 mp3 = new MP3("c:/mp3/pretty maids/jump the gun/lethal heroes.mp3");
               mp3.setLyrics(Language.DEU, "Get a little frightened sometimes\nA little cold inside\nCatching bad news on the radio\n...");

      `
      Parameters:
        `language` - the ISO-639-2 `language` the lyrics are written in.
        `lyrics` - the lyrics to the song in the specified language.
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getLyrics()`, `getLyrics(Language)`, `getLyricsBy()`, `setLyricsBy(String)`, `getSynchronizedLyrics()`, `removeLyrics()`, `removeLyrics(Language)`, `setLyrics(String)`

    - #### removeLyrics

          public void removeLyrics()
                            throws java.lang.IllegalStateException

      removes the (english) lyrics to the song from the .mp3 file.
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getLyrics()`, `getLyrics(Language)`, `getLyricsBy()`, `removeLyrics(Language)`, `getSynchronizedLyrics()`, `setLyrics(String)`, `setLyrics(Language, String)`

    - #### removeLyrics

          public void removeLyrics(Language language)
                            throws java.lang.IllegalStateException

      removes the lyrics in the specified language to the song from the .mp3 file.
      Parameters:
        `language` - the ISO-639-2 `language` the lyrics are written in.
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getLyrics()`, `getLyrics(Language)`, `getLyricsBy()`, `getSynchronizedLyrics()`, `removeLyrics()`, `setLyrics(String)`, `setLyrics(Language, String)`

    - #### getLyricsBy

          public java.lang.String getLyricsBy()

      gets name of the person(s) who wrote the lyrics to the song. If more than one person wrote the lyrics, their names are separated by a forward slash, "/".
      Example:`

               // load the song "The Clairvoyant" from Iron Maiden's "Seventh Son of a Seventh Son" album.
               MP3 mp3 = new MP3("c:/mp3/iron maiden/seventh son of a seventh son/the clairvoyant.mp3");
               System.out.println("the lyrics to the song " + mp3.getTitle() + " were written by " + mp3.getLyricsBy());

      `
      Returns:
        the person(s) who wrote the lyrics to the song. If no lyricist has been specified, then null is returned.
      See Also:
        `setLyricsBy(String)`, `removeLyricsBy()`, `getMusicBy()`

    - #### setLyricsBy

          public void setLyricsBy(java.lang.String lyricist)
                           throws java.lang.IllegalStateException

      sets the name of the person(s) who wrote the lyrics to the song. If there is more than one person, separate their names by a forward slash, "/".
      Example:`

               // load the song "The Clairvoyant" from Iron Maiden's "Seventh Son of a Seventh Son" album.
               MP3 mp3 = new MP3("c:/mp3/iron maiden/seventh son of a seventh son/the clairvoyant.mp3");
               mp3.setLyricsBy("Steve Harris/Bruce Dickenson")
               System.out.println("the lyrics to the song " + mp3.getTitle() + " were written by " + mp3.getLyricsBy());

      `
      Parameters:
        `lyricist` - the person(s) who wrote the lyrics to the song.
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getLyricsBy()`, `removeLyricsBy()`, `getMusicBy()`

    - #### removeLyricsBy

          public void removeLyricsBy()
                              throws java.lang.IllegalStateException

      removes the name of the person(s) who wrote the lyrics to the song from the .mp3 file.
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getLyricsBy()`, `setLyricsBy(String)`, `getMusicBy()`

    - #### getMusicBy

          public java.lang.String getMusicBy()

      gets name of the person(s) who wrote the music to the song. If more than one person wrote the music, their names are separated by a forward slash, "/".
      Example:`

               // load the song "Tell Me What You Want" from Zebra's 1st album, "Zebra".
               MP3 mp3 = new MP3("c:/mp3/zebra/zebra/tell me what you want.mp3");
               System.out.println("the music to the song " + mp3.getTitle() + " was written by " + mp3.getMusicBy());

      `
      Returns:
        the person(s) who wrote the music to the song. If no composer has been specified, then null is returned.
      See Also:
        `setMusicBy(String)`, `removeMusicBy()`, `getLyricsBy()`

    - #### setMusicBy

          public void setMusicBy(java.lang.String composer)
                          throws java.lang.IllegalStateException

      sets the name of the person(s) who wrote the music to the song. If there is more than one person, separate their names by a forward slash, "/".
      Example:`

               // load the song "Tell Me What You Want" from Zebra's 1st album, "Zebra".
               MP3 mp3 = new MP3("c:/mp3/zebra/zebra/tell me what you want.mp3");
               mp3.setMusicBy("Randy Jackson");
               System.out.println("the music to the song " + mp3.getTitle() + " was written by " + mp3.getMusicBy());

               // load the song "Living in a World" from Axxis' album, "Kingdom of the Night".
               MP3 mp3 = new MP3("c:/mp3/axxis/kingdom of the night/living in a world.mp3");
               mp3.setMusicBy("Bernhard Weiß/Walter Pietsch");
               System.out.println("the music to the song " + mp3.getTitle() + " was written by " + mp3.getMusicBy());

      `
      Parameters:
        `composer` - the person(s) who wrote the music to the song.
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getMusicBy()`, `removeMusicBy()`, `getLyricsBy()`

    - #### removeMusicBy

          public void removeMusicBy()
                             throws java.lang.IllegalStateException

      removes the name of the person(s) who wrote the music to the song from the .mp3 file.
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getMusicBy()`, `setMusicBy(String)`

    - #### getMusicType

          public java.lang.String getMusicType()

      gets the category of music for this song. see `Genre` or `setMusicType(String)` for a list of standard music categories.
      Returns:
        the music category for the type of music. If the type of music has not been specified, then null is returned.
      See Also:
        `setMusicType(Genre)`, `setMusicType(String)`

    - #### setMusicType

          public void setMusicType(Genre genre)
                            throws java.lang.IllegalStateException

      sets the category of music for this song.
      Parameters:
        `genre` - the song's music type. That is, the type of music the song would be described as.
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getMusicType()`, `setMusicType(String)`

    - #### setMusicType

          public void setMusicType(java.lang.String type)
                            throws java.lang.IllegalStateException

      sets the category of music for this song.

      References to the ID3v1, ID3v2, and WinAmp genres (which are shown in the list below) can be made by starting with an opening parenthesis "(" followed by a number from the genres list and ended with a closing parenthesis ")".
      example: mp3.setMusicType("(17)"); // indicates "Rock"

      This may optionally be followed by a refinement. The refinement can either be another music category from the list, or it may be text.
      If the refinement is a music category from the list below, then the refinement should have two opening parentheses, as shown in the following example.
      Example: mp3.setMusicType("(17)((79)"); // indicates "Rock" with a refinement of "Hard Rock"

      Otherwise, if the refinement is text, it can appear as in the example below.
      example: mp3.setMusicType("(4)Eurodisco"); // indicates "Disco" with a refinement of "Eurodisco"

      Number | Music Type
      --- | ---
      ID3v1 Extensions
      0. | Blues
      1. | Classic Rock
      2. | Country
      3. | Dance
      4. | Disco
      5. | Funk
      6. | Grunge
      7. | Hip-Hop
      8. | Jazz
      9. | Metal
      10. | New Age
      11. | Oldies
      12. | Other
      13. | Pop
      14. | R&B
      15. | Rap
      16. | Reggae
      17. | Rock
      18. | Techno
      19. | Industrial
      20. | Alternative
      21. | Ska
      22. | Death Metal
      23. | Pranks
      24. | Soundtrack
      25. | Euro-Techno
      26. | Ambient
      27. | Trip-Hop
      28. | Vocal
      29. | Jazz+Funk
      30. | Fusion
      31. | Trance
      32. | Classical
      33. | Instrumental
      34. | Acid
      35. | House
      36. | Game
      37. | Sound Clip
      38. | Gospel
      39. | Noise
      40. | AlternRock
      41. | Bass
      42. | Soul
      43. | Punk
      44. | Space
      45. | Meditative
      46. | Instrumental Pop
      47. | Instrumental Rock
      48. | Ethnic
      49. | Gothic
      50. | Darkwave
      51. | Techno-Industrial
      52. | Electronic
      53. | Pop-Folk
      54. | Eurodance
      55. | Dream
      56. | Southern Rock
      57. | Comedy
      58. | Cult
      59. | Gangsta
      60. | Top 40
      61. | Christian Rap
      62. | Pop/Funk
      63. | Jungle
      64. | Native American
      65. | Cabaret
      66. | New Wave
      67. | Psychadelic
      68. | Rave
      69. | Showtunes
      70. | Trailer
      71. | Lo-Fi
      72. | Tribal
      73. | Acid Punk
      74. | Acid Jazz
      75. | Polka
      76. | Retro
      77. | Musical
      78. | Rock & Roll
      79. | Hard Rock
      WinAmp Extensions
      80. | Folk
      81. | Folk-Rock
      82. | National Folk
      83. | Swing
      84. | Fast Fusion
      85. | Bebob
      86. | Latin
      87. | Revival
      88. | Celtic
      89. | Bluegrass
      90. | Avantgarde
      91. | Gothic Rock
      92. | Progressive Rock
      93. | Psychedelic Rock
      94. | Symphonic Rock
      95. | Slow Rock
      96. | Big Band
      97. | Chorus
      98. | Easy Listening
      99. | Acoustic
      100. | Humour
      101. | Speech
      102. | Chanson
      103. | Opera
      104. | Chamber Music
      105. | Sonata
      106. | Symphony
      107. | Booty Brass
      108. | Primus
      109. | Porn Groove
      110. | Satire
      111. | Slow Jam
      112. | Club
      113. | Tango
      114. | Samba
      115. | Folklore
      116. | Ballad
      117. | Power Ballad
      118. | Rhytmic Soul
      119. | Freestyle
      120. | Duet
      121. | Punk Rock
      122. | Drum Solo
      123. | A Capela
      124. | Euro-House
      125. | Dance Hall
      126. | Goa
      127. | Drum & Bass
      128. | Club-House
      129. | Hardcore
      130. | Terror
      131. | Indie
      132. | BritPop
      133. | Negerpunk
      134. | Polsk Punk
      135. | Beat
      136. | Christian Gangsta
      137. | Heavy Metal
      138. | Black Metal
      139. | Crossover
      140. | Contemporary C
      141. | Christian Rock
      142. | Merengue
      143. | Salsa
      144. | Thrash Metal
      145. | Anime
      146. | JPop
      147. | SynthPop
      ID3v2 Extensions
      RX | Remix
      CR | Cover

      Parameters:
        `type` - the music category for the type of music.
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getMusicType()`, `removeMusicType()`

    - #### removeMusicType

          public void removeMusicType()
                               throws java.lang.IllegalStateException

      removes the type of music for the song from the .mp3 file.
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getMusicType()`, `setMusicType(String)`

    - #### getPicture

          public AttachedPicture getPicture(PictureType type)

      gets the attached picture for the specified picture type.
      Example:`

               // load the song "Take Hold of the Flame" from Queensryche's album, "The Warning".
               MP3             mp3             = new MP3("c:/mp3/queensryche/the warning/take hold of the flame.mp3");
               AttachedPicture attachedPicture = mp3.getPicture(PictureType.FRONT_COVER);

               if (attachedPicture == null)
                  System.out.println("no front cover image was stored in the mp3.");
               else
                  System.out.println("the front cover image stored in the mp3 is " + attachedPicture);

               attachedPicture = mp3.getPicture(PictureType.BAND_LOGO);
               if (attachedPicture == null)
                  System.out.println("no band logo image was stored in the mp3.");
               else
                  System.out.println("the band logo image stored in the mp3 is " + attachedPicture);

      `
      Parameters:
        `type` - `type` of picture.
      Returns:
        the attached picture for the specified picture type. If no picture of the specified type is found in the .mp3 file, then null is returned.
      See Also:
        `setPicture(PictureType, String)`, `setPicture(PictureType, File)`, `setPicture(AttachedPicture)`, `getPictures()`, `removePicture(PictureType)`, `removePictures()`, `ID3v23FrameBodyAttachedPicture.setPictureType(PictureType)`

    - #### getPictures

          public java.util.List<AttachedPicture> getPictures()

      gets all the pictures stored in the .mp3 file's tag.
      Example:`

               // load the song "Take Hold of the Flame" from Queensryche's album, "The Warning".
               MP3                   mp3              = new MP3("c:/mp3/queensryche/the warning/take hold of the flame.mp3");
               List<AttachedPicture> attachedPictures = mp3.getPictures();

              // print out each picture's type, picture's mime type, optional description of the picture, and the number of bytes in the image
              if (attachedPictures.size() == 0)
              {
                 System.out.println("No pictures were found in the .mp3 file");
              }
              else
              {
                 System.out.println("" + attachedPictures.size() + " pictures were found in the .mp3 file");
                 for(AttachedPicture picture : attachedPictures)
                    System.out.println(picture);
              }

      `
      Returns:
        a list of all the pictures in the .mp3 file's tag. If no pictures are found in the tag, then an empty list is returned.
      See Also:
        `setPicture(PictureType, String)`, `setPicture(PictureType, File)`, `setPicture(AttachedPicture)`, `getPicture(PictureType)`, `removePicture(PictureType)`, `removePictures()`

    - #### setPicture

          public void setPicture(PictureType type,
                        java.lang.String imageFilename)
                          throws java.io.IOException,
                                 java.lang.IllegalStateException

      adds the picture to the song. The mime type of the image is derived from the image file's extension (ie, .jpg -> image/jpg).
      Example:`

               // load the song "Take Hold of the Flame" from Queensryche's album, "The Warning".
               MP3 mp3 = new MP3("c:/mp3/queensryche/the warning/take hold of the flame.mp3");

               mp3.setPicture(PictureType.FRONT_COVER, "c:/mp3/queensryche/the warning/take hold of the flame.jpg");

      `
      Parameters:
        `type` - `type` of picture.
        `imageFilename` - path to the image file, such as a .jpg, .gif, .png, etc.
      Throws:
        `java.io.IOException` - if the specified image file can not be read.
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `setPicture(PictureType, File)`, `setPicture(AttachedPicture)`, `getPicture(PictureType)`, `getPictures()`, `removePicture(PictureType)`, `removePictures()`

    - #### setPicture

          public void setPicture(PictureType type,
                        java.io.File imageFile)
                          throws java.io.IOException,
                                 java.lang.IllegalStateException

      adds the picture to the song. The mime type of the image is derived from the image file's extension (ie, .jpg -> image/jpg).
      Example:`

               // load the song "Take Hold of the Flame" from Queensryche's album, "The Warning".
               MP3 mp3 = new MP3("c:/mp3/queensryche/the warning/take hold of the flame.mp3");

               mp3.setPicture(PictureType.FRONT_COVER, new File("c:/mp3/queensryche/the warning/take hold of the flame.jpg"));

      `
      Parameters:
        `type` - `type` of picture.
        `imageFile` - file, such as a .jpg, .gif, .png, etc. containing the image to be added to the .mp3 file.
      Throws:
        `java.io.IOException` - if the specified image file can not be read.
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `setPicture(PictureType, String)`, `setPicture(AttachedPicture)`, `getPicture(PictureType)`, `getPictures()`, `removePicture(PictureType)`, `removePictures()`

    - #### setPicture

          public void setPicture(PictureType type,
                        java.net.URL imageURL)
                          throws java.io.IOException,
                                 java.lang.IllegalStateException

      adds the picture to the song. The mime type of the image is derived from the image file's extension (ie, .jpg -> image/jpg).
      Example:`

               // load the song "Take Hold of the Flame" from Queensryche's album, "The Warning".
               MP3 mp3 = new MP3("c:/mp3/queensryche/the warning/take hold of the flame.mp3");

               mp3.setPicture(PictureType.FRONT_COVER, new URL("http://www.beaglebuddy.com/content/downloads/mp3/take%20hold%20of%20the%20flame.front%20cover.jpg"));

      `
      Parameters:
        `type` - `type` of picture.
        `imageURL` - url of an image file, such as a .jpg, .gif, .png, etc.
      Throws:
        `java.io.IOException` - if the specified image file can not be read.
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `setPicture(PictureType, File)`, `setPicture(AttachedPicture)`, `getPicture(PictureType)`, `getPictures()`, `removePicture(PictureType)`, `removePictures()`

    - #### setPicture

          public void setPicture(AttachedPicture attachedPicture)
                          throws java.lang.IllegalStateException

      adds the attached picture to the song.
      Example:`

               // load the song "Take Hold of the Flame" from Queensryche's album, "The Warning".
               MP3             mp3             = new MP3("c:/mp3/queensryche/the warning/take hold of the flame.mp3");
               AttachedPicture attachedPicture = new AttachedPicture(PictureType.FRONT_COVER, "image/jpg", "front cover of cd", new File("c:/mp3/queensryche/the warning/take hold of the flame.jpg"));

               mp3.setPicture(attachedPicture);

      `
      Parameters:
        `attachedPicture` - picture to add to the .mp3 file.
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `setPicture(PictureType, String)`, `setPicture(PictureType, File)`, `getPicture(PictureType)`, `getPictures()`, `removePicture(PictureType)`, `removePictures()`

    - #### removePicture

          public void removePicture(PictureType type)
                             throws java.lang.IllegalStateException

      removes the picture of the specified type from the .mp3 file. If no picture of the specified type is found in the .mp3 file, then no action is taken.
      Example:`

               // load the song "Take Hold of the Flame" from Queensryche's album, "The Warning".
               MP3 mp3 = new MP3("c:/mp3/queensryche/the warning/take hold of the flame.mp3");

               mp3.removePicture(PictureType.FRONT_COVER);

      `
      Parameters:
        `type` - `type` of picture to remove from the .mp3 file.
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `setPicture(PictureType, String)`, `setPicture(PictureType, File)`, `setPicture(AttachedPicture)`, `getPicture(PictureType)`, `getPictures()`, `removePictures()`

    - #### removePictures

          public java.util.List<AttachedPicture> removePictures()
                                                         throws java.lang.IllegalStateException

      removes all the picture(s) from the .mp3 file.
      Example:`

               // load the song "Take Hold of the Flame" from Queensryche's album, "The Warning".
               MP3 mp3 = new MP3("c:/mp3/queensryche/the warning/take hold of the flame.mp3");

               mp3.removePictures();

      `
      Returns:
        the list of attached pictures that were removed from the ID3v2.x tag. If the ID3v2.x tag does not contain any attached pictures, then an empty list is returned.
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `setPicture(PictureType, String)`, `setPicture(PictureType, File)`, `setPicture(AttachedPicture)`, `getPicture(PictureType)`, `getPictures()`, `removePicture(PictureType)`

    - #### getPublisher

          public java.lang.String getPublisher()

      gets the publisher of the song.
      Example:`

               // load the song "Soldier Of The Line" from Magnum's "Chase The Dragon" album.
               MP3 mp3 = new MP3("c:/mp3/magnum/chase the dragon/soldier of the line.mp3");
               System.out.println("the song " + mp3.getTitle() + " was published by " + mp3.getPublisher());

      `
      Returns:
        the publisher of the song. If no publisher has been specified, then null is returned.
      See Also:
        `setPublisher(String)`, `removePublisher()`

    - #### setPublisher

          public void setPublisher(java.lang.String publisher)
                            throws java.lang.IllegalStateException

      sets the publisher of the the song.
      Example:`

               // load the song "Soldier Of The Line" from Magnum's "Chase The Dragon" album.
               MP3 mp3 = new MP3("c:/mp3/magnum/chase the dragon/soldier of the line.mp3");
               mp3.setPublisher("Jet Records");
               System.out.println("the song " + mp3.getTitle() + " was published by " + mp3.getPublisher());

      `
      Parameters:
        `publisher` - the publisher of the song.
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getPublisher()`, `removePublisher()`

    - #### removePublisher

          public void removePublisher()
                               throws java.lang.IllegalStateException

      removes the publisher of the the song from the .mp3 file.
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getPublisher()`, `setPublisher(String)`

    - #### getRating

          public int getRating()

      gets the rating (ie, how much you like it) of the song.
      Example:`

               // load the song "Magic Power" from Triumph's "Allied Forces" album.
               MP3 mp3 = new MP3("c:/mp3/triumph/allied forces/magic power.mp3");
               if (mp3.getRating() == 0)
                  System.out.println("the song " + mp3.getTitle() + " has not yet been rated.");
               else
                  System.out.println("the song " + mp3.getTitle() + " was rated a " + mp3.getRating() + " out of 255.");

      `
      Returns:
        the rating of the song. The rating is 1-255 where 1 is worst and 255 is best. 0 is unknown, or unrated. If no song rating has been specified, then 0 is returned.
      See Also:
        `setRating(int)`, `removeRating()`

    - #### setRating

          public void setRating(int rating)
                         throws java.lang.IllegalStateException

      sets the rating of the song.
      Example:`

               // load the song "Magic Power" from Triumph's "Allied Forces" album.
               MP3 mp3 = new MP3("c:/mp3/triumph/allied forces/magic power.mp3");
               mp3.getRating(240);
               System.out.println("the song " + mp3.getTitle() + " was rated a " + mp3.getRating() + " out of 255.");

      `
      Parameters:
        `rating` - the rating of the song where 1 is worst and 255 is best. 0 is unknown, ie, the song has not yet been rated.
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getRating()`, `removeRating()`

    - #### removeRating

          public void removeRating()
                            throws java.lang.IllegalStateException

      removes the rating from the .mp3 file. This sets the rating to 0, which means "unrated", ie, the song has not yet been rated.
      Example:`

               // load the song "Magic Power" from Triumph's "Allied Forces" album.
               MP3 mp3 = new MP3("c:/mp3/triumph/allied forces/magic power.mp3");
               mp3.removeRating();
               System.out.println("the song " + mp3.getTitle() + " was rated a " + mp3.getRating() + " out of 255.");

      `
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `setRating(int)`, `getRating()`

    - #### getSynchronizedLyrics

          public java.util.List<SynchronizedLyric> getSynchronizedLyrics()

      gets the (english) synchronized lyrics to the song. Synchronized lyrics are like those seen on Kareoke machines. The words to the song are synchonized with the music. Each syllable or word (or whatever size of text is considered to be convenient) has a corresponding timestamp indicating when in the song it occurs.
      Example:`

               // load the song "Long After Midnight" from Loudness's "Soldier Of Fortune" album.
               MP3                     mp3    = new MP3("c:/mp3/loudness/soldier of fortune/long after midnight.mp3");
               List<SynchronizedLyric> lyrics = mp3.getSynchronizedLyrics();

               if (lyrics == null)
                  System.out.println("the song " + mp3.getTitle() + " does not have any english kareoke lyrics.");
               else
                  System.out.println("the song " + mp3.getTitle() + " contains " + lyrics.size() + " english synchonized lyrics.");

      `
      Returns:
        the synchronized (english) lyrics to the song. If no synchronized (english) lyrics have been specified, then null is returned.
      See Also:
        `setSynchronizedLyrics(SynchronizedLyric [])`, `setSynchronizedLyrics(Language, SynchronizedLyric [])`, `setSynchronizedLyrics(List)`, `setSynchronizedLyrics(Language, List)`, `removeSynchronizedLyrics()`, `removeSynchronizedLyrics(Language)`, `getLyrics()`, `getLyrics(Language)`, "com.beaglebuddy.mp3.sample_code.Kareoke"

    - #### getSynchronizedLyrics

          public java.util.List<SynchronizedLyric> getSynchronizedLyrics(Language language)

      gets the synchronized lyrics to the song in the specified language. Synchronized lyrics are like those seen on Kareoke machines. The words to the song are synchonized with the music. Each syllable or word (or whatever size of text is considered to be convenient) has a corresponding timestamp indicating when in the song it occurs.
      Example:`

               // load the song "Long After Midnight" from Loudness's "Soldier Of Fortune" album.
               MP3                     mp3    = new MP3("c:/mp3/loudness/soldier of fortune/long after midnight.mp3");
               List<SynchronizedLyric> lyrics = mp3.getSynchronizedLyrics(Language.SPA);

               if (lyrics == null)
                  System.out.println("the song " + mp3.getTitle() + " does not have any spanish kareoke lyrics.");
               else
                  System.out.println("the song " + mp3.getTitle() + " contains " + lyrics.size() + " spanish synchonized lyrics.");

      `
      Parameters:
        `language` - the ISO-639-2 `language` the lyrics are written in.
      Returns:
        the synchronized lyrics to the song in the specified language. If no synchronized lyrics in the specified language have been specified, then null is returned.
      See Also:
        `setSynchronizedLyrics(SynchronizedLyric [])`, `setSynchronizedLyrics(Language, SynchronizedLyric [])`, `setSynchronizedLyrics(List)`, `setSynchronizedLyrics(Language, List)`, `removeSynchronizedLyrics()`, `removeSynchronizedLyrics(Language)`, `getLyrics()`, `getLyrics(Language)`, "com.beaglebuddy.mp3.sample_code.Kareoke"

    - #### setSynchronizedLyrics

          public void setSynchronizedLyrics(SynchronizedLyric[] synchronizedLyrics)
                                     throws java.lang.IllegalStateException

      sets the (english) synchronized lyrics to the song. Synchronized lyrics are like those seen on Kareoke machines. The words to the song are synchonized with the music. Each syllable or word (or whatever size of text is considered to be convenient) has a corresponding timestamp indicating when in the song it occurs.
      Example:`

               // load the song "Long After Midnight" from Loudness's "Soldier Of Fortune" album.
               MP3                 mp3    = new MP3("c:/mp3/loudness/soldier of fortune/long after midnight.mp3");
               SynchronizedLyric[] lyrics = {new SynchronizedLyric("I"    , 33000),
                                             new SynchronizedLyric("can"  , 33400),
                                             new SynchronizedLyric("feel" , 33825),
                                             new SynchronizedLyric("a"    , 34000),
                                             new SynchronizedLyric("touch", 34500),
                                             etc...
                                                                                    };

               mp3.setSynchronizedLyrics(lyrics);

      `
      Parameters:
        `synchronizedLyrics` - the synchronized (english) lyrics to the song.
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getSynchronizedLyrics()`, `getSynchronizedLyrics(Language)`, `setSynchronizedLyrics(Language, SynchronizedLyric [])`, `setSynchronizedLyrics(List)`, `setSynchronizedLyrics(Language, List)`, `removeSynchronizedLyrics()`, `removeSynchronizedLyrics(Language)`, `setLyrics(String)`, `setLyrics(Language, String)`, "com.beaglebuddy.mp3.sample_code.Kareoke"

    - #### setSynchronizedLyrics

          public void setSynchronizedLyrics(Language language,
                                   SynchronizedLyric[] synchronizedLyrics)
                                     throws java.lang.IllegalStateException

      sets the synchronized lyrics to the song in the specified language. Synchronized lyrics are like those seen on Kareoke machines. The words to the song are synchonized with the music. Each syllable or word (or whatever size of text is considered to be convenient) has a corresponding timestamp indicating when in the song it occurs.
      Example:`

               // load the song "Long After Midnight" from Loudness's "Soldier Of Fortune" album.
               MP3                 mp3    = new MP3("c:/mp3/loudness/soldier of fortune/long after midnight.mp3");
               SynchronizedLyric[] lyrics = {new SynchronizedLyric("I"    , 33000),
                                             new SynchronizedLyric("can"  , 33400),
                                             new SynchronizedLyric("feel" , 33825),
                                             new SynchronizedLyric("a"    , 34000),
                                             new SynchronizedLyric("touch", 34500),
                                             etc...
                                                                                    };

               mp3.setSynchronizedLyrics(Language.SPA, lyrics);

      `
      Parameters:
        `language` - the ISO-639-2 `language` the lyrics are written in.
        `synchronizedLyrics` - the synchronized lyrics to the song in the specified language.
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getSynchronizedLyrics()`, `getSynchronizedLyrics(Language)`, `setSynchronizedLyrics(SynchronizedLyric [])`, `setSynchronizedLyrics(List)`, `setSynchronizedLyrics(Language, List)`, `removeSynchronizedLyrics()`, `removeSynchronizedLyrics(Language)`, `setLyrics(String)`, `setLyrics(Language, String)`, "com.beaglebuddy.mp3.sample_code.Kareoke"

    - #### setSynchronizedLyrics

          public void setSynchronizedLyrics(java.util.List<SynchronizedLyric> synchronizedLyrics)
                                     throws java.lang.IllegalStateException

      sets the (english) synchronized lyrics to the song. Synchronized lyrics are like those seen on Kareoke machines. The words to the song are synchonized with the music. Each syllable or word (or whatever size of text is considered to be convenient) has a corresponding timestamp indicating when in the song it occurs.
      Example:`

               // load the song "Long After Midnight" from Loudness's "Soldier Of Fortune" album.
               MP3                     mp3    = new MP3("c:/mp3/loudness/soldier of fortune/long after midnight.mp3");
               List<SynchronizedLyric> lyrics = new List();

               lyrics.add(new SynchronizedLyric("I"    , 33000));
               lyrics.add(new SynchronizedLyric("can"  , 33400));
               lyrics.add(new SynchronizedLyric("feel" , 33825));
               lyrics.add(new SynchronizedLyric("a"    , 34000));
               lyrics.add(new SynchronizedLyric("touch", 34500));
                          etc...

               mp3.setSynchronizedLyrics(lyrics);

      `
      Parameters:
        `synchronizedLyrics` - the (english) synchronized lyrics to the song.
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getSynchronizedLyrics()`, `getSynchronizedLyrics(Language)`, `setSynchronizedLyrics(SynchronizedLyric [])`, `setSynchronizedLyrics(Language, SynchronizedLyric [])`, `setSynchronizedLyrics(Language, List)`, `removeSynchronizedLyrics()`, `removeSynchronizedLyrics(Language)`, `setLyrics(String)`, `setLyrics(Language, String)`, "com.beaglebuddy.mp3.sample_code.Kareoke"

    - #### setSynchronizedLyrics

          public void setSynchronizedLyrics(Language language,
                                   java.util.List<SynchronizedLyric> synchronizedLyrics)
                                     throws java.lang.IllegalStateException

      sets the synchronized lyrics to the song in the specified language. Synchronized lyrics are like those seen on Kareoke machines. The words to the song are synchonized with the music. Each syllable or word (or whatever size of text is considered to be convenient) has a corresponding timestamp indicating when in the song it occurs.
      Example:`

               // load the song "Long After Midnight" from Loudness's "Soldier Of Fortune" album.
               MP3                     mp3    = new MP3("c:/mp3/loudness/soldier of fortune/long after midnight.mp3");
               List<SynchronizedLyric> lyrics = new List();

               lyrics.add(new SynchronizedLyric("I"    , 33000));
               lyrics.add(new SynchronizedLyric("can"  , 33400));
               lyrics.add(new SynchronizedLyric("feel" , 33825));
               lyrics.add(new SynchronizedLyric("a"    , 34000));
               lyrics.add(new SynchronizedLyric("touch", 34500));
                          etc...

               mp3.setSynchronizedLyrics(Language.DEU, lyrics);

      `
      Parameters:
        `language` - the ISO-639-2 `language` the lyrics are written in.
        `synchronizedLyrics` - the synchronized lyrics to the song in the specified language.
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getSynchronizedLyrics()`, `getSynchronizedLyrics(Language)`, `setSynchronizedLyrics(SynchronizedLyric [])`, `setSynchronizedLyrics(Language, SynchronizedLyric [])`, `setSynchronizedLyrics(List)`, `removeSynchronizedLyrics()`, `removeSynchronizedLyrics(Language)`, `setLyrics(String)`, `setLyrics(Language, String)`, "com.beaglebuddy.mp3.sample_code.Kareoke"

    - #### removeSynchronizedLyrics

          public void removeSynchronizedLyrics()
                                        throws java.lang.IllegalStateException

      remove the (english) synchronized lyrics from the .mp3 song.
      Example:`

               // load the song "Long After Midnight" from Loudness's "Soldier Of Fortune" album.
               MP3 mp3 = new MP3("c:/mp3/loudness/soldier of fortune/long after midnight.mp3");
               mp3.removeSynchronizedLyrics();         // remove the (english) synchronized lyrics

      `
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `setLyrics(String)`, `setLyrics(Language, String)`, `getSynchronizedLyrics()`, `getSynchronizedLyrics(Language)`, `setSynchronizedLyrics(SynchronizedLyric [])`, `setSynchronizedLyrics(Language, SynchronizedLyric [])`, `setSynchronizedLyrics(List)`, `setSynchronizedLyrics(Language, List)`, `removeSynchronizedLyrics()`, `removeSynchronizedLyrics(Language)`

    - #### removeSynchronizedLyrics

          public void removeSynchronizedLyrics(Language language)
                                        throws java.lang.IllegalStateException

      remove the synchronized lyrics in the specified language from the .mp3 song.
      Example:`

               // load the song "Long After Midnight" from Loudness's "Soldier Of Fortune" album.
               MP3 mp3 = new MP3("c:/mp3/loudness/soldier of fortune/long after midnight.mp3");
               mp3.removeSynchronizedLyrics(Language.SPA);         // remove the spanish synchronized lyrics

      `
      Parameters:
        `language` - the ISO-639-2 `language` the lyrics are written in.
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `setLyrics(String)`, `setLyrics(Language, String)`, `getSynchronizedLyrics()`, `getSynchronizedLyrics(Language)`, `setSynchronizedLyrics(SynchronizedLyric [])`, `setSynchronizedLyrics(Language, SynchronizedLyric [])`, `setSynchronizedLyrics(List)`, `setSynchronizedLyrics(Language, List)`, `removeSynchronizedLyrics()`, `removeSynchronizedLyrics(Language)`

    - #### getTitle

          public java.lang.String getTitle()

      gets the name of the song stored in the .mp3 file.
      Example:`

               // load the song "The Arena" from Fates Warning's "Perfect Symmetry" album.
               MP3 mp3 = new MP3("c:/mp3/fates warning/perfect symmetry/the arena.mp3");
               System.out.println("the .mp3 file " + mp3.getPath() + " contains the song " + mp3.getTitle());

      `
      Returns:
        the name of the song. If no song name has been specified, then null is returned.
      See Also:
        `setTitle(String)`, `setTitleFromFilename()`, `removeTitle()`

    - #### setTitle

          public void setTitle(java.lang.String title)
                        throws java.lang.IllegalStateException

      sets the name of the song stored in the .mp3 file.
      Example:`

               // load the song "The Arena" from Fates Warning's "Perfect Symmetry" album.
               MP3 mp3 = new MP3("c:/mp3/fates warning/perfect symmetry/the arena.mp3");
               mp3.setTitle("The Arena");
               System.out.println("the .mp3 file " + mp3.getPath() + " contains the song " + mp3.getTitle());

      `
      Parameters:
        `title` - the name of the song.
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getTitle()`, `setTitleFromFilename()`, `removeTitle()`

    - #### setTitleFromFilename

          public void setTitleFromFilename()
                                    throws java.lang.IllegalStateException

      sets the name of the song stored in the .mp3 file from the name of the .mp3 file on disk.
      Example:`

               // load the song "The Arena" from Fates Warning's "Perfect Symmetry" album.
               MP3 mp3 = new MP3("c:/mp3/fates warning/perfect symmetry/the arena.mp3");
               mp3.setTitleFromFilename();         // set the title to "the arena"
               System.out.println("the .mp3 file " + mp3.getPath() + " contains the song " + mp3.getTitle());

      `
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getTitle()`, `setTitle(String)`, `removeTitle()`

    - #### removeTitle

          public void removeTitle()
                           throws java.lang.IllegalStateException

      removes the name of the song from the .mp3 file.
      Example:`

               // load the song "The Arena" from Fates Warning's "Perfect Symmetry" album.
               MP3 mp3 = new MP3("c:/mp3/fates warning/perfect symmetry/the arena.mp3");
               mp3.removeTitle();         // remove the title
               System.out.println("the .mp3 file " + mp3.getPath() + " contains the song " + mp3.getTitle());

      `
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getTitle()`, `setTitle(String)`, `setTitleFromFilename()`

    - #### getTrack

          public int getTrack()

      gets the track number of the song.
      Example:`

               // load the song "O Father" from House of Lords' "Demons Down" album.
               MP3 mp3 = new MP3("c:/mp3/house of lords/demons down/o father.mp3");
               mp3.getTrack();            // get the track number
               System.out.println("the .mp3 song " + mp3.getTitle() + "  is song #" + mp3.getTrack() + " on the cd.");

      `
      Returns:
        the track number of the song. If no track number has been specified, then 0 is returned.
      See Also:
        `setTrack(int)`, `removeTrack()`

    - #### setTrack

          public void setTrack(int track)
                        throws java.lang.IllegalArgumentException,
                               java.lang.IllegalStateException

      sets the track number of the song.
      Example:`

               // load the song "O Father" from House of Lords' "Demons Down" album.
               MP3 mp3 = new MP3("c:/mp3/house of lords/demons down/o father.mp3");
               mp3.setTrack(2);            // set the track number to 2
               System.out.println("the .mp3 song " + mp3.getTitle() + "  is song #" + mp3.getTrack() + " on the cd.");

      `
      Parameters:
        `track` - the track number of the song. It must be >= 1.
      Throws:
        `java.lang.IllegalArgumentException` - if the track number is <= 0.
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getTrack()`, `removeTrack()`

    - #### removeTrack

          public void removeTrack()
                           throws java.lang.IllegalStateException

      removes the track number of the song from the .mp3 file. If `getTrack()` is subsequently called, it will return 0.
      Example:`

               // load the song "O Father" from House of Lords' "Demons Down" album.
               MP3 mp3 = new MP3("c:/mp3/house of lords/demons down/o father.mp3");
               mp3.removeTrack();            // removes the track number from the .mp3 file
               System.out.println("the .mp3 song " + mp3.getTitle() + "  is song #" + mp3.getTrack() + " on the cd.");

      `
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getTrack()`, `setTrack(int)`

    - #### getVersion

          public ID3TagVersion getVersion()

      gets the version of the ID3 tag stored in the .mp3 song which holds all of the information about the .mp3 file.
      Returns:
        the version of the ID3 tag stored in the .mp3 song which holds all of the information about the .mp3 file.

    - #### getYear

          public int getYear()

      gets the year the song was recorded.
      Example:`

               // load the song "Lethal Heroes" from Pretty Maids' "Jump The Gun" album.
               MP3 mp3 = new MP3("c:/mp3/pretty maids/jump the gun/lethal heroes.mp3");
               System.out.println("the song " + mp3.getTitle() + "  was recorded in " + mp3.getYear());

      `
      Returns:
        the year the song was released. If no year has been specified, then 0 is returned.
      See Also:
        `setYear(int)`, `removeYear()`

    - #### setYear

          public void setYear(int year)
                       throws java.lang.IllegalArgumentException,
                              java.lang.IllegalStateException

      sets the year the song was recorded.
      Example:`

               // load the song "Lethal Heroes" from Pretty Maids' "Jump The Gun" album.
               MP3 mp3 = new MP3("c:/mp3/pretty maids/jump the gun/lethal heroes.mp3");
               mp3.setYear(1990);
               System.out.println("the song " + mp3.getTitle() + "  was recorded in " + mp3.getYear());

      `
      Parameters:
        `year` - the year the song was recorded. It must be >= 1.
      Throws:
        `java.lang.IllegalArgumentException` - if the year is <= 0.
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getYear()`, `removeYear()`

    - #### removeYear

          public void removeYear()
                          throws java.lang.IllegalStateException

      removes the year the song was released from the .mp3 file.
      Example:`

               // load the song "Lethal Heroes" from Pretty Maids' "Jump The Gun" album.
               MP3 mp3 = new MP3("c:/mp3/pretty maids/jump the gun/lethal heroes.mp3");
               mp3.removeYear();

      `
      Throws:
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL or an input stream and is therefore considered to be read only and thus may not be modified.
      See Also:
        `getYear()`, `setYear(int)`

    - #### toString

          public java.lang.String toString()

      returns a string representation of the mp3 file. This is useful in debugging, as this method shows all of the internal details of the .mp3 file, including the ID3v2.x tag, the 1st mpeg audio frame, etc.
      Example:`

               // load the song "Knife in my Heart" from Sinner's "Dangerous Charm" album.
               MP3 mp3 = new MP3("c:/mp3/sinner/dangerous charm/knife in my heart.mp3");
               System.out.println(mp3);

      `
      Overrides:
        `toString` in class `MP3Base`
      Returns:
        string representation of the mp3 file.