rockbox/manual/plugins/lrcplayer.tex

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

\subsubsection{Supported file types}
\begin{enumerate}
\item \fname{.lrc}
\item \fname{.lrc8}
\item \fname{.snc}
\item \fname{.txt}
\item id3v2 SYLT or USLT tags in mp3 files
\end{enumerate}

\fname{.lrc8} files are the same as \fname{.lrc} files except that they are UTF8
encoded. The Lyrics3 tag is not supported.

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

Each line should resemble one of the following:
\begin{verbatim}
[time tag]line
[time tag]...[time tag]line
[time tag]<word time tag>word<word time tag>...<word time tag>
\end{verbatim}

The time tag must be in the form [mm:ss], [mm:ss.xx], or [mm:ss.xxx] where mm is
minutes, ss is seconds, xx is tenth of milliseconds, and xxx is milliseconds.
Any other tags and lines without time tags are ignored.

\subsubsection{Location of lyrics files}
The plugin checks the following directories for lyrics files.
\opt{swcodec}{If no lyrics file is found and the audio file is a \fname{.mp3},
  it also checks for SYLT and USLT tags in the id3v2 tags.}

\begin{enumerate}
\item The directory containing the audio file and its parent directories.
\item For each of the above directories, the plugin searches for a subdirectory
      named ``Lyrics''.
\item Finally, the plugin will search as above, but within a directory called
      ``/Lyrics''. The name of this directory can be customized, see below.
\end{enumerate}

If the audio file currently playing is \fname{/Music/Artist/Album/Title.mp3},
then the following files will be searched for, in this order. \fname{.ext} is one
of the supported extensions from the list above, and will be searched for in the
same order as in that list.

\begin{verbatim}
/Music/Artist/Album/Title.ext
/Music/Artist/Title.ext
/Music/Title.ext
/Title.ext
/Music/Artist/Album/Lyrics/Title.ext
/Music/Artist/Lyrics/Title.ext
/Music/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 the statusbar.
      \item[Display Title.] Show / hide the track title.
    }%
    \item[Display Time.] Show / hide the current time.
    \opt{lcd_color}{%
      \item[Inactive Colour.] Set the colour of the inactive part of the lyrics.
    }%
    \item[Backlight Force On.] Do not turn off the backlight while displaying
         the lyrics.
  \end{description}
  \opt{lcd_bitmap}{%
    \item[Display Settings.] Change how the lyrics are displayed.
    \begin{description}
      \item[Wrap.] Breaks lines at white space.
      \item[Wipe.] Wipes the text.
      \item[Alignment.] Align text to the left, centre, or right.
      \item[Activate Only Current Line.]
          Activate only the current line, or the current and previous lines.
    \end{description}
  }%
  \item[Lyrics Settings.] Change how the lyrics files are loaded.
  \begin{description}
    \item[Encoding.] Sets the codepage used in the plugin.
    \opt{swcodec}{%
      \item[Read ID3 tag.] Read lyrics from id3 tags in mp3 files.
    }%
    \item[Lrc Directory.] Set the directory where lyrics files are stored,
      must be a maximum of 63 bytes.
  \end{description}
  \item[Playback Control.] Show the playback control menu.
  \item[Time Offset.] Set an offset for the time tags for the lyrics currently in use.
  \item[Timetag Editor.] Enter the timetag editor.
  \item[Quit.] Exit the plugin.
\end{description}

\subsubsection{Editing the time tags}

The display time for each line can be changed with the timetag editor.
Selecting a line changes its time to the current position of the track.
To set a specific time or to adjust the time, press \ActionStdContext{} to
bring up a screen to adjust the time.
Changes will be saved automatically when the song is changed.
Edting words in lyrics is not supported.