rockbox/manual/plugins/lrcplayer.tex

% $Id$ %
\subsection{Lrcplayer}
% \screenshot{plugins/images/ss-lrcplayer}{Lrcplayer}{}
This plugin displays lyrics in .lrc file (and some other formats) synchronized
with the song being played.

\subsubsection{Supproted file types}
\begin{enumerate}
\item .lrc
\item .lrc8
\item .snc
\item .txt
\item id3v2 SYLT or USLT tag in mp3 file
\end{enumerate}

.lrc8 file is equivalent to .lrc files except it is read that
encoded by UTF-8 nevertheless the encoding setting.

Lyrics3 tag is not supported.

\subsubsection{Supported tags and formats for .lrc files}
following tags are supported:
\begin{verbatim}
[ti:title]
[ar:artist]
[offset:offset (msec)]
\end{verbatim}

each line should look like one of these:
\begin{verbatim}
[time tag]line
[time tag]...[time tag]line
[time tag]<word time tag>word<word time tag>...<word time tag>
\end{verbatim}

time tag must be in one of the formats: [mm:ss], [mm:ss.xx], or [mm:ss.xxx]

where mm is minuts, ss is seconds, xx is tenth of millisecounds, xxx is millisecounds.

e.g. [01:23], [01:23.45].

any other tags and lines without time tags are ignored.

\subsubsection{Searching lyrics file}
the plugin checks following directories for lyrics file.
\opt{swcodec}{if no lyrics file is found and the audio file is a mp3,
  it also checks SYLT or USLT tag in id3v2.}

\begin{enumerate}
\item the directory of the audio file and it's parent directories.
\item subdirecory named ``Lylics'' of each directory in 1.
\item almost same as 1, but ``/Lylics'' is prepended to the path.
\end{enumerate}
``Lylics'' can be customized.

e.g.

if the audio file currently playing is /Musics/Artist/Album/Title.mp3,
then following files will be tried in this order.

ext is one in supproted file types list, tried in same order of the list.

\begin{verbatim}
/Musics/Artist/Album/Title.ext
/Musics/Artist/Title.ext
/Musics/Title.ext
/Title.ext
/Musics/Artist/Album/Lyrics/Title.ext
/Musics/Artist/Lyrics/Title.ext
/Musics/Lyrics/Title.ext
/Lyrics/Title.ext
/Lyrics/Musics/Artist/Album/Title.ext
/Lyrics/Musics/Artist/Title.ext
/Lyrics/Musics/Title.ext
/Lyrics/Title.ext
\end{verbatim}

\subsubsection{Controls}
\begin{table}
  \begin{btnmap}{}{}
    \ActionWpsVolUp{} / \ActionWpsVolDown
    \opt{HAVEREMOTEKEYMAP}{& \ActionRCWpsVolUp{} / \ActionRCWpsVolDown}
    & Volume up/down.\\
    %
    \ActionWpsSkipPrev
    \opt{HAVEREMOTEKEYMAP}{& \ActionRCWpsSkipPrev}
    & Go to beginning of track, or if pressed while in the
      first seconds of a track, go to the previous track.\\
    %
    \ActionWpsSeekBack
    \opt{HAVEREMOTEKEYMAP}{& \ActionRCWpsSeekBack}
    & Rewind in track.\\
    %
    \ActionWpsSkipNext
    \opt{HAVEREMOTEKEYMAP}{& \ActionRCWpsSkipNext}
    & Go to the next track.\\
    %
    \ActionWpsSeekFwd
    \opt{HAVEREMOTEKEYMAP}{& \ActionRCWpsSeekFwd}
    & Fast forward in track.\\
    %
    \ActionWpsPlay
    \opt{HAVEREMOTEKEYMAP}{& \ActionRCWpsPlay}
    & Toggle play/pause.\\
    %
    \ActionWpsStop \nopt{ONDIO_PAD}{or \ActionWpsBrowse}
    \opt{HAVEREMOTEKEYMAP}{& \ActionRCWpsStop or \ActionRCWpsBrowse}
    & Exit the plugin.\\
    %
    \ActionWpsContext
    \opt{HAVEREMOTEKEYMAP}{& \ActionRCWpsContext}
    & Enter timetag editor.\\
    %
    \opt{ONDIO_PAD}{\ActionWpsBrowse}%
    \nopt{ONDIO_PAD}{\ActionWpsMenu}%
    \opt{HAVEREMOTEKEYMAP}{& \ActionRCWpsMenu}
    & Enter \setting{Lrcplayer Menu}.\\
    %
  \end{btnmap}
\end{table}

\subsubsection{Lrcplayer Menu}

\begin{description}
  \item[Theme settings.] change theme related settings.
  \begin{description}
    \opt{lcd_bitmap}{%
      \item[Show Statusbar.] show / hide statusbar.
      \item[Display Title.] show / hide title of track.
    }%
    \item[Display Time.] show / hide current time.
    \opt{lcd_color}{%
      \item[Inactive Color.] set color of inactive part of lyrics.
    }%
    \item[Backlight Force On.] don't turn off backlight while in displaying
        lyrics screen.
  \end{description}
  \opt{lcd_bitmap}{%
    \item[Display Settings.] change displaying of lyrics.
    \begin{description}
      \item[Wrap.] breaks lines at white space.
      \item[Wipe.] wipe text.
      \item[Align.] align text to left, center, or right.
      \item[Activate Only Current Line.]
          activate only current line or current line and previous lines.
    \end{description}
  }%
  \item[Lyrics Settings.] change loading of lyrics.
  \begin{description}
    \item[Encoding.] sets the codepage in the plugin.
    \opt{swcodec}{%
      \item[Read ID3 tag.] read lyrics from id3 tag in mp3 file.
    }%
    \item[Lrc Directry.] set name of a directory where lyrics files are sotred,
      63 bytes at maximum.
  \end{description}
  \item[Playback Control.] Show playback control menu.
  \item[Time Offset.] set offset for time tags of the lyrics currently loaded.
  \item[Timetag Editor.] Enter timetag editor.
  \item[Quit.] Exit the plugin.
\end{description}

\subsubsection{Editing time tag}

The time when to dispaly the line can be edited with timetag editor.
Selecting line changes its time to current position of the song.
To set a specific time or to adjust the time, press \ActionStdContext to
 bring up a screen for adjusting the time.
Changes will be saved automatically when the song is changed.

Edting words in lyrics is not supported.