public class ID3v24FrameBodySynchronizedLyricsText extends ID3v24FrameBody
A synchronized lyrics/text frame body is associated with an ID3v2.4 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:
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.4 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.v24.FrameType;
import com.beaglebuddy.id3.pojo.SynchronizedLyric;
import com.beaglebuddy.id3.v24.ID3v24Frame;
import com.beaglebuddy.id3.v24.ID3v24Tag;
import com.beaglebuddy.id3.v24.frame_body.ID3v24FrameBodySynchronizedLyricsText;
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");
ID3v24Tag iD3v24Tag = mp3.getID3v24Tag();
List<ID3v24Frame> frames = iD3v24Tag.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" , 24000),
new SynchronizedLyric("on" , 24100),
new SynchronizedLyric("strike" , 24200),
new SynchronizedLyric("He's" , 24800),
new SynchronizedLyric("down" , 24900),
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.4 tag
ID3v24Frame frame = new ID3v24Frame(FrameType.SYNCHRONIZED_LYRIC_TEXT, new ID3v24FrameBodySynchronizedLyricsText(synchronizedLyrics));
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();
}
}
}
Modifier and Type | Class and Description |
---|---|
static class |
ID3v24FrameBodySynchronizedLyricsText.ContentType
ID3v2.4 types of synchronized lyrics/text.
|
buffer, dirty, frameType
nextNullTerminatorIndex, nullTerminatorIndex
Constructor and Description |
---|
ID3v24FrameBodySynchronizedLyricsText()
The default constructor is called when creating a new frame.
|
ID3v24FrameBodySynchronizedLyricsText(Encoding encoding,
Language language,
TimeStampFormat timeStampFormat,
ID3v24FrameBodySynchronizedLyricsText.ContentType contentType,
java.lang.String description,
java.util.List<SynchronizedLyric> synchronizedLyrics)
This constructor is called when creating a new frame.
|
ID3v24FrameBodySynchronizedLyricsText(Encoding encoding,
Language language,
TimeStampFormat timeStampFormat,
ID3v24FrameBodySynchronizedLyricsText.ContentType contentType,
java.lang.String description,
SynchronizedLyric[] synchronizedLyrics)
This constructor is called when creating a new frame.
|
ID3v24FrameBodySynchronizedLyricsText(java.io.InputStream inputStream,
int frameBodySize)
This constructor is called when reading in an existing frame from an .mp3 file.
|
ID3v24FrameBodySynchronizedLyricsText(SynchronizedLyric[] synchronizedLyrics)
The default constructor is called when creating a new frame.
|
Modifier and Type | Method and Description |
---|---|
ID3v24FrameBodySynchronizedLyricsText.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(ID3v24FrameBodySynchronizedLyricsText.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.
|
getFrameType, getNextNullTerminator, getSize, isDirty, save, save
getNextNullTerminator, pricesToString, stringToBytes
bytesToInt, bytesToInt, bytesToShort, bytesToShort, bytesToSynchsafeInt, bytesToSynchsafeShort, formateDate, hex, hex, hex, intToBytes, littleEndianBytesToInt, pad, shortToBytes, synchsafeIntToBytes
public ID3v24FrameBodySynchronizedLyricsText()
public ID3v24FrameBodySynchronizedLyricsText(SynchronizedLyric[] synchronizedLyrics)
synchronizedLyrics
- array of synchronized lyrics in english.public ID3v24FrameBodySynchronizedLyricsText(Encoding encoding, Language language, TimeStampFormat timeStampFormat, ID3v24FrameBodySynchronizedLyricsText.ContentType contentType, java.lang.String description, SynchronizedLyric[] synchronizedLyrics)
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.java.lang.IllegalArgumentException
- if the time stamps in the synchronized lyrics are not in ascending chronological order.public ID3v24FrameBodySynchronizedLyricsText(Encoding encoding, Language language, TimeStampFormat timeStampFormat, ID3v24FrameBodySynchronizedLyricsText.ContentType contentType, java.lang.String description, java.util.List<SynchronizedLyric> synchronizedLyrics)
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.java.lang.IllegalArgumentException
- if the time stamps in the synchronized lyrics are not in ascending chronological order.public ID3v24FrameBodySynchronizedLyricsText(java.io.InputStream inputStream, int frameBodySize) throws java.io.IOException
inputStream
- input stream pointing to a sychronized lyrics/text frame body in the .mp3 file.frameBodySize
- size (in bytes) of the frame's body.java.io.IOException
- if there is an error while reading the frame body.public void parse() throws java.lang.IllegalArgumentException
parse
in class ID3v24FrameBody
java.lang.IllegalArgumentException
- if an invalid value is detected while parsing the frame body's raw bytes.public Encoding getEncoding()
setEncoding(Encoding)
public void setEncoding(Encoding encoding)
encoding
- the character set used to encode the description and the synchronized lyrics. Only ISO 8859-1 and UTF-16 are allowed.getEncoding()
public Language getLanguage()
language
the synchronized lyrics are written in.language
the synchronized lyrics are written in.setLanguage(Language)
public void setLanguage(Language language)
language
the synchronized lyrics are written in.language
- language
the synchronized lyrics are written in.getLanguage()
public TimeStampFormat getTimeStampFormat()
setTimeStampFormat(TimeStampFormat)
public void setTimeStampFormat(TimeStampFormat timeStampFormat)
timeStampFormat
- the units of the time stamp.getTimeStampFormat()
public ID3v24FrameBodySynchronizedLyricsText.ContentType getContentType()
setContentType(ContentType)
public void setContentType(ID3v24FrameBodySynchronizedLyricsText.ContentType contentType)
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 |
contentType
- one of the predefined values indicating the type of lyric.getContentType()
public java.lang.String getDescription()
setDescription(String)
public void setDescription(java.lang.String description)
description
- the description of the synchronized lyrics.getDescription()
public java.util.List<SynchronizedLyric> getSynchronizedLyrics()
getSynchronizedLyrics()
public void setSynchronizedLyrics(java.util.List<SynchronizedLyric> synchronizedLyrics)
synchronizedLyrics
- the synchronized lyrics/text.getSynchronizedLyrics()
public void setBuffer()
setBuffer
in class ID3v24FrameBody
public java.lang.String toString()
toString
in class java.lang.Object