com.beaglebuddy.id3.v24.frame_body

## Class ID3v24FrameBodyUnsynchronizedLyrics

- java.lang.Object
- - com.beaglebuddy.util.Utility
  - - com.beaglebuddy.id3.v24.frame_body.ID3v24FrameBodyUtility
    - - com.beaglebuddy.id3.v24.frame_body.ID3v24FrameBody
      - - com.beaglebuddy.id3.v24.frame_body.ID3v24FrameBodyUnsynchronizedLyrics

-     public class ID3v24FrameBodyUnsynchronizedLyrics
      extends ID3v24FrameBody

  An unsynchronized lyrics frame body is associated with an ID3v2.4 `USLT` `frame` which is used to include the lyrics to a song or a text transcription of other vocal activities in an .mp3 file. This is similar to the `synchronized lyrics/text` frame, but the lyrics in this, the unsynchronized lyrics frame body, are not synchronized with the audio of the .mp3 file. Just like the lyrics that are printed on a CD booklet, the lyrics found in this frame are the entire lyrics for song. The unsynchronized lyrics frame body contains the following fields:

  Terms of Use Frame Body Fields
  | Field | Description
  --- | --- | ---
  1. | `encoding` | character set used to `encode` the description and text fields.
  2. | `language` | language that the text field is written in.
  3. | description | description of the lyrics/text stored in the text field.
  4. | text | the actual text of the lyrics.

  There may be more than one unsynchronized lyrics frame in an ID3v2.4 `tag`, but only one with the same language and description fields. Thus, you may have the english lyrics, the spanish lyrics, and the german lyrics all in the same tag.

  example: ``

       import java.io.IOException;
       import java.util.List;

       import com.beaglebuddy.id3.enums.Language;
       import com.beaglebuddy.id3.enums.v24.Encoding;
       import com.beaglebuddy.id3.enums.v24.FrameType;
       import com.beaglebuddy.id3.v24.ID3v24Frame;
       import com.beaglebuddy.id3.v24.ID3v24Tag;
       import com.beaglebuddy.id3.v24.frame_body.ID3v24FrameBodyUnsynchronizedLyrics;
       import com.beaglebuddy.mp3.MP3;

       public class Lyrics
       {
          public static void main(String[] args)
          {
             try
             {
                // add Bon Jovi's "Livin on a Prayer" lyrics to the .mp3
                MP3               mp3       = new MP3("c:\\music\\bon jovi\\livin on a prayer.mp3");
                ID3v24Tag         iD3v24Tag = mp3.getID3v24Tag();
                List<ID3v24Frame> frames    = iD3v24Tag.getFrames();
                String            lyrics    = "Tommy used to work on the docks, Union's been on strike, He's down on his luck It's tough, ....";

                // if there was any invalid information (ie, 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 (frames) and
                }                                      // save only the valid frames back to the .mp3 file

                // add the unsynchronized lyrics frame to the ID3v2.4 tag
                ID3v24Frame frame = new ID3v24Frame(FrameType.UNSYCHRONIZED_LYRICS, new ID3v24FrameBodyUnsynchronizedLyrics(Encoding.UTF_16, Language.ENG, "lyrics", lyrics));
                frames.add(frame);
                // save the ID3v2.4 tag to the .mp3 file
                mp3.save();
                System.out.println(mp3);
             }
             catch (IOException ex)
             {
                // an error occurred reading/saving the .mp3 file.
                // you may try to read it again to see if the error still occurs.
                ex.printStackTrace();
             }
          }
       }

  See Also:
    `ID3v24Frame`, `ID3v24FrameBodySynchronizedLyricsText`, ID3 tag version 2.4.0 standard, wikipedia history of ID3 tags

- - ### Field Summary

    - ### Fields inherited from class com.beaglebuddy.id3.v24.frame_body.ID3v24FrameBody

      `buffer, dirty, frameType`

    - ### Fields inherited from class com.beaglebuddy.id3.v24.frame_body.ID3v24FrameBodyUtility

      `nextNullTerminatorIndex, nullTerminatorIndex`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ID3v24FrameBodyUnsynchronizedLyrics()` The default constructor is called when creating a new frame.
    `ID3v24FrameBodyUnsynchronizedLyrics(Encoding encoding, Language language, java.lang.String description, java.lang.String text)` This constructor is called when creating a new frame.
    `ID3v24FrameBodyUnsynchronizedLyrics(java.io.InputStream inputStream, int frameBodySize)` This constructor is called when reading in an existing frame from an .mp3 file.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.String` | `getDescription()` gets the description of the lyrics.
    `Encoding` | `getEncoding()` gets the character encoding of the description and the text (lyrics).
    `Language` | `getLanguage()` gets the `language` the unsynchronized lyrics are written in.
    `java.lang.String` | `getText()` gets the lyrics to the song.
    `void` | `parse()` parses the raw bytes of the frame body and stores the parsed values in the frame's fields.
    `void` | `setBuffer()` If the frame body's values have been modified, then resize the raw binary buffer and store the new values there.
    `void` | `setDescription(java.lang.String description)` sets the description of the lyrics.
    `void` | `setEncoding(Encoding encoding)` sets the character encoding of the description and the text (lyrics).
    `void` | `setLanguage(Language language)` sets the `language` the unsynchronized lyrics are written in.
    `void` | `setText(java.lang.String text)` sets the lyrics to the song.
    `java.lang.String` | `toString()` gets a string representation of the unsynchronized lyrics frame body and shows the values of all its fields.

    - ### Methods inherited from class com.beaglebuddy.id3.v24.frame_body.ID3v24FrameBody

      `getFrameType, getNextNullTerminator, getSize, isDirty, save, save`

    - ### Methods inherited from class com.beaglebuddy.id3.v24.frame_body.ID3v24FrameBodyUtility

      `getNextNullTerminator, pricesToString, stringToBytes`

    - ### Methods inherited from class com.beaglebuddy.util.Utility

      `bytesToInt, bytesToInt, bytesToShort, bytesToShort, bytesToSynchsafeInt, bytesToSynchsafeShort, formateDate, getUTF16String, getUTF8String, hex, hex, hex, intToBytes, littleEndianBytesToInt, pad, shortToBytes, synchsafeIntToBytes`

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

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

- - ### Constructor Detail

    - #### ID3v24FrameBodyUnsynchronizedLyrics

          public ID3v24FrameBodyUnsynchronizedLyrics()

      The default constructor is called when creating a new frame. The default values used are:
      - UTF-16 encoding
      - english language code
      - no description
      - no lyrics

    - #### ID3v24FrameBodyUnsynchronizedLyrics

          public ID3v24FrameBodyUnsynchronizedLyrics(Encoding encoding,
                                             Language language,
                                             java.lang.String description,
                                             java.lang.String text)

      This constructor is called when creating a new frame.
      Parameters:
        `encoding` - character set used to encode the description and the lyrics.
        `language` - ISO-639-2 `Language` code the lryics are written in.
        `description` - description of the lyrics.
        `text` - lyrics to the song in the specified language.

    - #### ID3v24FrameBodyUnsynchronizedLyrics

          public ID3v24FrameBodyUnsynchronizedLyrics(java.io.InputStream inputStream,
                                             int frameBodySize)
                                              throws java.io.IOException

      This constructor is called when reading in an existing frame from an .mp3 file. This is then followed by a call to the parse() method.
      Parameters:
        `inputStream` - input stream pointing to an unsychronized lyrics/text transcription frame body in the .mp3 file.
        `frameBodySize` - size (in bytes) of the frame's body.
      Throws:
        `java.io.IOException` - if there is an error while reading the frame body.

  - ### Method Detail

    - #### parse

          public void parse()
                     throws java.lang.IllegalArgumentException

      parses the raw bytes of the frame body and stores the parsed values in the frame's fields.
      Overrides:
        `parse` in class `ID3v24FrameBody`
      Throws:
        `java.lang.IllegalArgumentException` - if an invalid value is detected while parsing the frame body's raw bytes.

    - #### getEncoding

          public Encoding getEncoding()

      gets the character encoding of the description and the text (lyrics).
      Returns:
        the character encoding of the description and the text (lyrics).
      See Also:
        `setEncoding(Encoding)`

    - #### setEncoding

          public void setEncoding(Encoding encoding)

      sets the character encoding of the description and the text (lyrics).
      Parameters:
        `encoding` - the character set used to encode the description and the text (lyrics). Only ISO 8859-1 and UTF-16 are allowed.
      See Also:
        `getEncoding()`

    - #### getLanguage

          public Language getLanguage()

      gets the `language` the unsynchronized lyrics are written in.
      Returns:
        the `language` the unsynchronized lyrics are written in.
      See Also:
        `setLanguage(Language)`

    - #### setLanguage

          public void setLanguage(Language language)

      sets the `language` the unsynchronized lyrics are written in.
      Parameters:
        `language` - `language` the unsynchronized lyrics are written in.
      See Also:
        `getLanguage()`

    - #### getDescription

          public java.lang.String getDescription()

      gets the description of the lyrics.
      Returns:
        the description of the lyrics.
      See Also:
        `setDescription(String)`

    - #### setDescription

          public void setDescription(java.lang.String description)

      sets the description of the lyrics.
      Parameters:
        `description` - the description of the lyrics.
      See Also:
        `getDescription()`

    - #### getText

          public java.lang.String getText()

      gets the lyrics to the song.
      Returns:
        the lyrics.
      See Also:
        `setText(String)`

    - #### setText

          public void setText(java.lang.String text)

      sets the lyrics to the song.
      Parameters:
        `text` - the text of the lyrics.
      See Also:
        `getText()`

    - #### setBuffer

          public void setBuffer()

      If the frame body's values have been modified, then resize the raw binary buffer and store the new values there. When finished, the dirty flag is reset to indicate that the buffer is up to date, and the frame is now ready to be saved to the .mp3 file.
      Overrides:
        `setBuffer` in class `ID3v24FrameBody`

    - #### toString

          public java.lang.String toString()

      gets a string representation of the unsynchronized lyrics frame body and shows the values of all its fields.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        a string representation of the frame body.