com.beaglebuddy.id3.v23.frame_body

## Class ID3v23FrameBodySynchronizedLyricsText

- java.lang.Object
- - com.beaglebuddy.util.Utility
  - - com.beaglebuddy.id3.v23.frame_body.ID3v23FrameBodyUtility
    - - com.beaglebuddy.id3.v23.frame_body.ID3v23FrameBody
      - - com.beaglebuddy.id3.v23.frame_body.ID3v23FrameBodySynchronizedLyricsText

-     public class ID3v23FrameBodySynchronizedLyricsText
      extends ID3v23FrameBody

  A synchronized lyrics/text frame body is associated with an ID3v2.3 `SYLT` `frame` which is used to include the words or lyrics in the .mp3 file in sync with the audio. The most common use for this frame is to create Kareoke songs. It might also be used to describe events e.g. occurring on a stage or on the screen in sync with the audio.

  A few considerations regarding whitespace characters. Whitespace separating words should mark the beginning of a new word, thus occurring in front of the first syllable of a new word. This is also valid for newline characters. A syllable followed by a comma should not be broken apart with a sync (both the syllable and the comma should be before the sync).

  The synchronized lyrics/text frame body contains the following fields:

  Synchronized Lyrics/Text Frame Body Fields
  | Field | Description
  --- | --- | ---
  1. | `encoding` | character set used to `encode` the description and the text fields.
  2. | `language` | `language` the synchronized lyrics are written in.
  3. | `time stamp format` | `units` of the time stamp field in a synchronized lyric.
  4. | `contentType` | `predefined list` describing the type of lyric.
  5. | description | description of the lyrics/text.
  6. | synchronizedLyrics | list of synchronized lyrics, where each synchonized lyric consists of a syllable (or whatever size of text is considered to be convenient) and a time stamp denoting where in the .mp3 file it belongs. All synchronized lyrics should be sorted in chronological order.

  There may be more than one synchronized lyrics/text frame in an ID3v2.3 `tag`, but only one with the same language and description fields.

  example: ``

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

       import com.beaglebuddy.mp3.MP3;
       import com.beaglebuddy.id3.enums.v23.FrameType;
       import com.beaglebuddy.id3.enums.SynchronizedLyric;
       import com.beaglebuddy.id3.v23.ID3v23Frame;
       import com.beaglebuddy.id3.v23.ID3v23Tag;
       import com.beaglebuddy.id3.v23.frame_body.ID3v23FrameBodySynchronizedLyricsText;

       public class Kareoke
       {

          public static void main(String[] args)
          {
             try
             {
                // add Bon Jovi's "Livin on a Prayer" lyrics to the .mp3 so that they are displayed like a kareoke song by the mp3 player software
                MP3               mp3       = new MP3("c:\\music\\bon jovi\\livin on a prayer.mp3");
                ID3v23Tag         iD3v23Tag = mp3.getID3v23Tag();
                List<ID3v23Frame> frames    = iD3v23Tag.getFrames();

                // 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

                // break the lyrics into syllables
                SynchronizedLyric[] synchronizedLyrics = {new SynchronizedLyric("Tom-"   , 20350),
                                                          new SynchronizedLyric("my"     , 20400),
                                                          new SynchronizedLyric("used"   , 20625),
                                                          new SynchronizedLyric("to"     , 20700),
                                                          new SynchronizedLyric("work"   , 20800),
                                                          new SynchronizedLyric("on"     , 20900),
                                                          new SynchronizedLyric("the"    , 21000),
                                                          new SynchronizedLyric("docks"  , 21100),
                                                          new SynchronizedLyric("Un-"    , 22800),
                                                          new SynchronizedLyric("ions"   , 22900),
                                                          new SynchronizedLyric("been"   , 23000),
                                                          new SynchronizedLyric("on"     , 23100),
                                                          new SynchronizedLyric("strike" , 23200),
                                                          new SynchronizedLyric("He's"   , 23800),
                                                          new SynchronizedLyric("down"   , 23900),
                                                          new SynchronizedLyric("on"     , 24000),
                                                          new SynchronizedLyric("his"    , 24100),
                                                          new SynchronizedLyric("luck"   , 24200),
                                                          new SynchronizedLyric("it's"   , 25000),
                                                          new SynchronizedLyric("tough"  , 25300),
                                                          new SynchronizedLyric("so"     , 26900),
                                                          new SynchronizedLyric("tough"  , 27200)};

                // add the synchronized lyrics frame to the ID3v2.3 tag
                ID3v23Frame frame = new ID3v23Frame(FrameType.SYNCHRONIZED_LYRIC_TEXT, new ID3v23FrameBodySynchronizedLyricsText(synchronizedLyrics));
                frames.add(frame);
                // save the ID3v2.3 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:
    `ID3v23Frame`, `ID3v23FrameBodyUnsynchronizedLyrics`, ID3 tag version 2.3.0 standard, wikipedia history of ID3 tags

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `ID3v23FrameBodySynchronizedLyricsText.ContentType` ID3v2.3 types of synchronized lyrics/text.

  - ### Field Summary

    - ### Fields inherited from class com.beaglebuddy.id3.v23.frame_body.ID3v23FrameBody

      `buffer, dirty, frameType`

    - ### Fields inherited from class com.beaglebuddy.id3.v23.frame_body.ID3v23FrameBodyUtility

      `nextNullTerminatorIndex, nullTerminatorIndex`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ID3v23FrameBodySynchronizedLyricsText()` The default constructor is called when creating a new frame.
    `ID3v23FrameBodySynchronizedLyricsText(Encoding encoding, Language language, TimeStampFormat timeStampFormat, ID3v23FrameBodySynchronizedLyricsText.ContentType contentType, java.lang.String description, java.util.List<SynchronizedLyric> synchronizedLyrics)` This constructor is called when creating a new frame.
    `ID3v23FrameBodySynchronizedLyricsText(Encoding encoding, Language language, TimeStampFormat timeStampFormat, ID3v23FrameBodySynchronizedLyricsText.ContentType contentType, java.lang.String description, SynchronizedLyric[] synchronizedLyrics)` This constructor is called when creating a new frame.
    `ID3v23FrameBodySynchronizedLyricsText(java.io.InputStream inputStream, int frameBodySize)` This constructor is called when reading in an existing frame from an .mp3 file.
    `ID3v23FrameBodySynchronizedLyricsText(SynchronizedLyric[] synchronizedLyrics)` The default constructor is called when creating a new frame.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `ID3v23FrameBodySynchronizedLyricsText.ContentType` | `getContentType()` gets the type of lyric.
    `java.lang.String` | `getDescription()` gets the description of the synchronized lyrics.
    `Encoding` | `getEncoding()` gets the character encoding of the description and the synchronized lyrics.
    `Language` | `getLanguage()` gets the `language` the synchronized lyrics are written in.
    `java.util.List<SynchronizedLyric>` | `getSynchronizedLyrics()` gets the synchronized lyrics/text.
    `TimeStampFormat` | `getTimeStampFormat()` get the time stamp format.
    `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` | `setContentType(ID3v23FrameBodySynchronizedLyricsText.ContentType contentType)` sets the type of synchronized lyrics/text to one of the predefined types listed below.
    `void` | `setDescription(java.lang.String description)` sets the description of the synchronized lyrics.
    `void` | `setEncoding(Encoding encoding)` sets the character encoding of the description and the synchronized lyrics.
    `void` | `setLanguage(Language language)` sets the `language` the synchronized lyrics are written in.
    `void` | `setSynchronizedLyrics(java.util.List<SynchronizedLyric> synchronizedLyrics)` sets the synchronized lyrics/text.
    `void` | `setTimeStampFormat(TimeStampFormat timeStampFormat)` sets the time stamp format.
    `java.lang.String` | `toString()` gets a string representation of the synchronized lyrics/text frame body showing all of the frame's fields and their values.

    - ### Methods inherited from class com.beaglebuddy.id3.v23.frame_body.ID3v23FrameBody

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

    - ### Methods inherited from class com.beaglebuddy.id3.v23.frame_body.ID3v23FrameBodyUtility

      `getNextNullTerminator, pricesToString, stringToBytes`

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

      `bytesToInt, bytesToInt, bytesToShort, bytesToShort, bytesToSynchsafeInt, bytesToSynchsafeShort, formateDate, 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

    - #### ID3v23FrameBodySynchronizedLyricsText

          public ID3v23FrameBodySynchronizedLyricsText()

      The default constructor is called when creating a new frame. The default values used are:
      - ISO-8859-1 encoding
      - english language
      - time stamp format in milliseconds
      - lyrics content type
      - "synchronized lyrics" description
      - no synchronized lyrics

    - #### ID3v23FrameBodySynchronizedLyricsText

          public ID3v23FrameBodySynchronizedLyricsText(SynchronizedLyric[] synchronizedLyrics)

      The default constructor is called when creating a new frame. The default values used are:
      - ISO-8859-1 encoding
      - english language
      - time stamp format in milliseconds
      - lyrics content type
      - "synchronized lyrics" description
      Parameters:
        `synchronizedLyrics` - array of synchronized lyrics in english.

    - #### ID3v23FrameBodySynchronizedLyricsText

          public ID3v23FrameBodySynchronizedLyricsText(Encoding encoding,
                                               Language language,
                                               TimeStampFormat timeStampFormat,
                                               ID3v23FrameBodySynchronizedLyricsText.ContentType contentType,
                                               java.lang.String description,
                                               SynchronizedLyric[] synchronizedLyrics)

      This constructor is called when creating a new frame.
      Parameters:
        `encoding` - character set used to encode the description and the lyric. see `setEncoding(Encoding)`
        `language` - ISO-639-2 language code indicating the language the lyric were written in. see `setLanguage(Language)`
        `timeStampFormat` - units of the time stamp. see `setTimeStampFormat(TimeStampFormat)`
        `contentType` - type of lyics/text. see `setContentType(ContentType)`
        `description` - description of the lyrics/text.
        `synchronizedLyrics` - array of synchronized lyrics/text.
      Throws:
        `java.lang.IllegalArgumentException` - if the time stamps in the synchronized lyrics are not in ascending chronological order.

    - #### ID3v23FrameBodySynchronizedLyricsText

          public ID3v23FrameBodySynchronizedLyricsText(Encoding encoding,
                                               Language language,
                                               TimeStampFormat timeStampFormat,
                                               ID3v23FrameBodySynchronizedLyricsText.ContentType contentType,
                                               java.lang.String description,
                                               java.util.List<SynchronizedLyric> synchronizedLyrics)

      This constructor is called when creating a new frame.
      Parameters:
        `encoding` - character set used to encode the description and the lyric. see `setEncoding(Encoding)`
        `language` - ISO-639-2 language code indicating the language the lyric were written in. see `setLanguage(Language)`
        `timeStampFormat` - units of the time stamp. see `setTimeStampFormat(TimeStampFormat)`
        `contentType` - type of lyics/text. see `setContentType(ContentType)`
        `description` - description of the lyrics/text.
        `synchronizedLyrics` - list of synchronized lyrics/text.
      Throws:
        `java.lang.IllegalArgumentException` - if the time stamps in the synchronized lyrics are not in ascending chronological order.

    - #### ID3v23FrameBodySynchronizedLyricsText

          public ID3v23FrameBodySynchronizedLyricsText(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 a sychronized lyrics/text 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 `ID3v23FrameBody`
      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 synchronized lyrics.
      Returns:
        the character encoding of the description and the synchronized lyrics.
      See Also:
        `setEncoding(Encoding)`

    - #### setEncoding

          public void setEncoding(Encoding encoding)

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

    - #### getLanguage

          public Language getLanguage()

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

    - #### setLanguage

          public void setLanguage(Language language)

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

    - #### getTimeStampFormat

          public TimeStampFormat getTimeStampFormat()

      get the time stamp format.
      Returns:
        the time stamp format.
      See Also:
        `setTimeStampFormat(TimeStampFormat)`

    - #### setTimeStampFormat

          public void setTimeStampFormat(TimeStampFormat timeStampFormat)

      sets the time stamp format.
      Parameters:
        `timeStampFormat` - the units of the time stamp.
      See Also:
        `getTimeStampFormat()`

    - #### getContentType

          public ID3v23FrameBodySynchronizedLyricsText.ContentType getContentType()

      gets the type of lyric.
      Returns:
        the type of lyric.
      See Also:
        `setContentType(ContentType)`

    - #### setContentType

          public void setContentType(ID3v23FrameBodySynchronizedLyricsText.ContentType contentType)

      sets the type of synchronized lyrics/text to one of the predefined types listed below.

      | Content Type | Description
      --- | --- | ---
      0 | Other | other
      1 | Lyrics | song lyrics
      2 | Text Transcription | text transcription
      3 | Movement | movement/part name (e.g. "Adagio")
      4 | Events | events (e.g. "Don Quijote enters the stage)
      5 | Chord | chord (e.g. "Bb F Fsus")
      6 | Trivia | trivia/'pop up' information

      Parameters:
        `contentType` - one of the predefined values indicating the type of lyric.
      See Also:
        `getContentType()`

    - #### getDescription

          public java.lang.String getDescription()

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

    - #### setDescription

          public void setDescription(java.lang.String description)

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

    - #### getSynchronizedLyrics

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

      gets the synchronized lyrics/text.
      Returns:
        the synchronized lyrics/text.
      See Also:
        `getSynchronizedLyrics()`

    - #### setSynchronizedLyrics

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

      sets the synchronized lyrics/text.
      Parameters:
        `synchronizedLyrics` - the synchronized lyrics/text.
      See Also:
        `getSynchronizedLyrics()`

    - #### 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 `ID3v23FrameBody`

    - #### toString

          public java.lang.String toString()

      gets a string representation of the synchronized lyrics/text frame body showing all of the frame's fields and their values.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        a string representation of the frame body.