com.beaglebuddy.mp3

## Class MP3Base

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

- Direct Known Subclasses:
    MP3

      public class MP3Base
      extends MP3BaseID3v24

  This base class provides some underlying methods that help make the derived MP3 class's interface much cleaner and easier to understand. Thus, this class provides lower level methods that are used by the MP3 class, but would otherwise clutter the MP3 class's public interface.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected long` | `audioSize` size (in bytes) of the audio portion of the .mp3 file.
    `protected int` | `bitrate` the actual bit rate for `CBR` encoded .mp3 files and the average bit rate for `VBR` encoded .mp3 files.
    `protected BitrateType` | `bitrateType` whether the mp3 file was encoded with a constant bit rate (`CBR`) or with a variable bit rate (`VBR`).
    `protected long` | `fileSize` size (in bytes) of the .mp3 file.
    `protected java.io.File` | `mp3File` if the mp3 file is loaded from a local file, then this data member will contain the path to the .mp3 file.
    `protected java.net.URL` | `mp3Url` if the mp3 file is loaded from a URL, then this data member will contain the URL to the .mp3 file.
    `protected MPEGFrame` | `mpegFrame` the 1st mpeg audio frame found after the end of the ID3v2.x tag.
    `protected long` | `tagSize` size (in bytes) of the ID3v2.x tag.

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

      `id3v24Tag`

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

      `id3v23Tag`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `MP3Base(java.io.File mp3File)` constructor.
    `MP3Base(java.lang.String mp3File)` constructor.
    `MP3Base(java.net.URL mp3Url)` constructor.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected int` | `calculateAudioDuration()` calculates the duration of the song (in seconds) from data found in the `mpeg audio frames`.
    `void` | `displayErrors(java.io.PrintStream printStream)` displays any errors found in the ID3v2.x tag from the .mp3 file.
    `java.util.List<java.lang.String>` | `getErrors()` gets a list of any errors found in the ID3v2.x tag.
    `long` | `getFileSize()` returns the size (in bytes) of the .mp3 file.
    `ID3v24Tag` | `getID3v24TagAtEnd()` gets the optional `ID3v2.4 tag` found at the end of an .mp3 file.
    `java.lang.String` | `getPath()` gets the path to the .mp3 file.
    `protected java.lang.String` | `getReadOnlyErrorMessage()` gets the read only error message to display to users when they try to modify an .mp3 file loaded from a URL.
    `boolean` | `hasErrors()` determines if the mp3 file had any errors in the information stored in the frames of the ID3v2.x tag.
    `boolean` | `hasID3v1Tag()` determines whether the .mp3 file has an `ID3v1 tag` at the end of the .mp3 file.
    `boolean` | `hasID3v24TagAtEnd()` determines whether the .mp3 file has an `ID3v2.4 tag` at the end of the .mp3 file.
    `boolean` | `isConstantBitRate()` determines whether the mp3 file is encoded at a constant bit rate (`CBR`).
    `protected void` | `readFirstMPEGFrame(java.io.InputStream inputStream)` reads in the first mpeg audio frame from the .mp3 file.
    `protected boolean` | `readID3Tag(java.io.InputStream inputStream)` reads in the ID3v2.x tag from the .mp3 file.
    `void` | `removeID3v1Tag()` remove the `ID3v1 tag` at the end of the .mp3 file.
    `void` | `removeID3v24TagAtEnd()` remove the `ID3v2.4 tag` at the end of the .mp3 file.
    `protected void` | `saveID3v23()` save the `ID3v2.3 tag` to the .mp3 file.
    `protected void` | `saveID3v24()` save the `ID3v2.4 tag` to the .mp3 file.
    `java.lang.String` | `toString()` gets a string representation of the mp3 file.
    `java.util.List<java.lang.String>` | `validateMPEGFrames()` This method reads through the audio portion of an .mp3 file and validates the `MPEG audio frames`.

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

      `addV24Frame, getID3v24Tag, getV24Album, getV24AttachedPicture, getV24AttachedPictureFrame, getV24AttachedPictures, getV24AudioDuration, getV24AudioSize, getV24Band, getV24Comments, getV24CommentsFrame, 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, removeV24Frame, removeV24Frames, removeV24LeadPerformer, removeV24LyricsBy, removeV24MusicBy, removeV24MusicType, removeV24Publisher, removeV24Rating, removeV24SynchronizedLyrics, removeV24Title, removeV24Track, removeV24UnsynchronizedLyrics, removeV24Year, setV24Album, setV24AttachedPicture, setV24AudioDuration, setV24AudioSize, setV24Band, setV24Comments, 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, 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, removeV23Frame, removeV23Frames, removeV23LeadPerformer, removeV23LyricsBy, removeV23MusicBy, removeV23MusicType, removeV23Publisher, removeV23Rating, removeV23SynchronizedLyrics, removeV23Title, removeV23Track, removeV23UnsynchronizedLyrics, removeV23Year, setV23Album, setV23AttachedPicture, setV23AudioDuration, setV23AudioSize, setV23Band, setV23Comments, 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`

- - ### Field Detail

    - #### mp3File

          protected java.io.File mp3File

      if the mp3 file is loaded from a local file, then this data member will contain the path to the .mp3 file. Otherwise, this data member will be null.

    - #### mp3Url

          protected java.net.URL mp3Url

      if the mp3 file is loaded from a URL, then this data member will contain the URL to the .mp3 file. Otherwise, this data member will be null.

    - #### fileSize

          protected long fileSize

      size (in bytes) of the .mp3 file.

    - #### tagSize

          protected long tagSize

      size (in bytes) of the ID3v2.x tag.

    - #### audioSize

          protected long audioSize

      size (in bytes) of the audio portion of the .mp3 file. That is, the number of bytes comprising the actual sound data for the song.

    - #### mpegFrame

          protected MPEGFrame mpegFrame

      the 1st mpeg audio frame found after the end of the ID3v2.x tag.

    - #### bitrate

          protected int bitrate

      the actual bit rate for `CBR` encoded .mp3 files and the average bit rate for `VBR` encoded .mp3 files.

    - #### bitrateType

          protected BitrateType bitrateType

      whether the mp3 file was encoded with a constant bit rate (`CBR`) or with a variable bit rate (`VBR`).

  - ### Constructor Detail

    - #### MP3Base

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

      constructor.
      Parameters:
        `mp3File` - path to the .mp3 file from which to get information.
      Throws:
        `java.io.IOException` - if there is a problem reading the .mp3 file.

    - #### MP3Base

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

      constructor.
      Parameters:
        `mp3File` - .mp3 file from which to get information.
      Throws:
        `java.io.IOException` - if there is a problem reading the .mp3 file.

    - #### MP3Base

          public MP3Base(java.net.URL mp3Url)
                  throws java.io.IOException

      constructor.
      Parameters:
        `mp3Url` - URL of an .mp3 file from which to get information.
      Throws:
        `java.io.IOException` - if there is a problem reading the .mp3 file.

  - ### Method Detail

    - #### readID3Tag

          protected boolean readID3Tag(java.io.InputStream inputStream)
                                throws java.io.IOException

      reads in the ID3v2.x tag from the .mp3 file. If the .mp3 file does not have an ID3v2.x tag, then an ID3v1 tag is searched for, and if found, values from it are used to create an ID3v2.3 tag.
      Parameters:
        `inputStream` - input stream pointing to the beginning of an .mp3 file
      Returns:
        true if a new ID3v2.x tag was created, and false if an existing ID3v2.x tag was found.
      Throws:
        `java.io.IOException` - if there is a problem reading the .mp3 file.

    - #### readFirstMPEGFrame

          protected void readFirstMPEGFrame(java.io.InputStream inputStream)
                                     throws java.io.IOException

      reads in the first mpeg audio frame from the .mp3 file. The audio portion of an .mp3 file is comprised of frames (not to be confused with the frames in an ID3v2.x tag). The 1st mpeg audio frame consists of a `frame header`, `side information`, followed by some optional `VBR` headers, and then by the `audio data`. This method searches the audio section of the .mp3 file until it finds the first valid mpeg audio frame header.
      Parameters:
        `inputStream` - input stream pointing to the beginning of the audio portion of an .mp3 file.
      Throws:
        `java.io.IOException` - if there is a problem reading the MPEG audio section of the .mp3 file.

    - #### validateMPEGFrames

          public java.util.List<java.lang.String> validateMPEGFrames()
                                                              throws java.io.IOException

      This method reads through the audio portion of an .mp3 file and validates the `MPEG audio frames`. It makes sure that the MPEG audio frames:
      - are the correct type: MPEG 1 Layer |||
      - are located where they are supposed to be
      - have valid `MPEG frame headers`
      - have a valid structure (`frame header` followed by `side information` followed by `audio data`)
      - use the same bit rate for every audio sample when the mp3 file is encoded with a `constant bit rate`
      It also makes sure that:
      - `Xing`, `Lame`, and `VBRI` headers occur only in the 1st `MPEG audio frame`
      - `VBR` encoded .mp3 files contain a VBR header
      note: This method should only be called on .mp3 files that are loaded from a file system. This is due to the amount of time it takes to download and read through an .mp3 file that is loaded from a URL. If invoked on an .mp3 loaded from a URL, this method will simply return an empty list, indicating no errors were found.
      Returns:
        a list of errors found in the MPEG audio section of the .mp3 file. If no errors were found, then an empty list is returned.
      Throws:
        `java.io.IOException` - if the .mp3 file can not be read.
      See Also:
        ID3v1 specification, APE v2 specification, LYRICS 3.2 specification

    - #### hasErrors

          public boolean hasErrors()

      determines if the mp3 file had any errors in the information stored in the frames of the ID3v2.x tag. If any of the ID3v2.x frames were invalid, then they are removed from the ID3v2.x tag.
      Returns:
        whether any invalid ID3v2.x frames were found in the ID3v2.x tag from the .mp3 file.
      See Also:
        `getErrors()`, `displayErrors(PrintStream)`

    - #### getErrors

          public java.util.List<java.lang.String> getErrors()

      gets a list of any errors found in the ID3v2.x tag.
      Returns:
        a list of errors found in the ID3v2.x tag. If no errors were found, then an empty list is returned.
      See Also:
        `hasErrors()`, `displayErrors(PrintStream)`

    - #### displayErrors

          public void displayErrors(java.io.PrintStream printStream)

      displays any errors found in the ID3v2.x tag from the .mp3 file. If no errors were found, then nothing is written to the print stream.
      Parameters:
        `printStream` - print stream used to write out the errors.
      See Also:
        `getErrors()`, `hasErrors()`

    - #### getReadOnlyErrorMessage

          protected java.lang.String getReadOnlyErrorMessage()

      gets the read only error message to display to users when they try to modify an .mp3 file loaded from a URL.
      Returns:
        the read only error message to display to users when they try to modify an .mp3 file loaded from a URL.

    - #### getPath

          public java.lang.String getPath()

      gets the path to the .mp3 file. This method may be called regardless of whether the .mp3 file was loaded from a file system or from a url.
      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");
               System.out.println("the mp3 file was loaded from " + mp3.getPath());

               // load the song "Take Hold of the Flame" from Queensryche's album, "The Warning".
               MP3 mp3 = new MP3("http://www.beaglebuddy.com/mp3/queensryche/the warning/take hold of the flame.mp3");
               System.out.println("the mp3 file was loaded from " + mp3.getPath());

      `
      Returns:
        the path to the .mp3 file.

    - #### getFileSize

          public long getFileSize()

      returns the size (in bytes) of the .mp3 file.
      Returns:
        the size (in bytes) of the .mp3 file.

    - #### calculateAudioDuration

          protected int calculateAudioDuration()

      calculates the duration of the song (in seconds) from data found in the `mpeg audio frames`.
      Returns:
        the length (in seconds) of the song.

    - #### isConstantBitRate

          public boolean isConstantBitRate()

      determines whether the mp3 file is encoded at a constant bit rate (`CBR`).
      Returns:
        whether the mp3 file is encoded at a constant bit rate (`CBR`).

    - #### hasID3v1Tag

          public boolean hasID3v1Tag()
                              throws java.io.IOException,
                                     java.lang.IllegalStateException

      determines whether the .mp3 file has an `ID3v1 tag` at the end of the .mp3 file. This method can only be called on mp3's loaded from a file.
      Returns:
        whether the .mp3 file has an `ID3v1 tag` at the end of the .mp3 file.
      Throws:
        `java.io.IOException` - if there is a problem reading the .mp3 file.
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL and therefore will take a considerable amount of time to reach the `ID3v1 tag` at the end of the .mp3 file.

    - #### getID3v24TagAtEnd

          public ID3v24Tag getID3v24TagAtEnd()
                                      throws java.io.IOException,
                                             java.lang.IllegalStateException

      gets the optional `ID3v2.4 tag` found at the end of an .mp3 file. This really is a stupid addition to the Id3v2.4 standard.
      Returns:
        the `ID3v2.4 tag` found at the end of an .mp3 file if present. Otherwise null is returned.
      Throws:
        `java.io.IOException` - if there is a problem reading the .mp3 file.
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL and therefore will take a considerable amount of time to reach the `ID3v2.4 tag` at the end of the .mp3 file.

    - #### hasID3v24TagAtEnd

          public boolean hasID3v24TagAtEnd()
                                    throws java.io.IOException,
                                           java.lang.IllegalStateException

      determines whether the .mp3 file has an `ID3v2.4 tag` at the end of the .mp3 file.
      Returns:
        whether the .mp3 file has an `ID3v2.4 tag` at the end of the .mp3 file.
      Throws:
        `java.io.IOException` - if there is a problem reading the .mp3 file.
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL and therefore will take a considerable amount of time to reach the `ID3v2.4 tag` at the end of the .mp3 file.

    - #### removeID3v1Tag

          public void removeID3v1Tag()
                              throws java.io.IOException

      remove the `ID3v1 tag` at the end of the .mp3 file.
      Throws:
        `java.io.IOException` - if there was an error truncating `ID3v1 tag` from the end of the .mp3 file.
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL and is therefore considered to be read only and thus may not be modified.

    - #### removeID3v24TagAtEnd

          public void removeID3v24TagAtEnd()
                                    throws java.io.IOException

      remove the `ID3v2.4 tag` at the end of the .mp3 file.
      Throws:
        `java.io.IOException` - if there was an error truncating `ID3v2.4 tag` from the end of the .mp3 file.
        `java.lang.IllegalStateException` - if the mp3 song was loaded from a URL and is therefore considered to be read only and thus may not be modified.

    - #### saveID3v23

          protected void saveID3v23()
                             throws java.io.IOException

      save the `ID3v2.3 tag` to the .mp3 file. This is a very messy method, and you really have to understand the ID3v2.3 structure to understand this method. So, if you can, by all means, avoid reading the code in this method.
      Throws:
        `java.io.IOException` - if there was an error writing the `ID3v2.3 tag` to the .mp3 file.

    - #### saveID3v24

          protected void saveID3v24()
                             throws java.io.IOException

      save the `ID3v2.4 tag` to the .mp3 file. This is a very messy method, and you really have to understand the ID3v2.4 structure to understand this method. So, if you can, by all means, avoid reading the code in this method.
      Throws:
        `java.io.IOException` - if there was an error writing the `ID3v2.4 tag` to the .mp3 file.

    - #### toString

          public java.lang.String toString()

      gets a string representation of the mp3 file.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        string representation of the mp3 file.