Using ncmpc to fetch and read lyrics

About ncmpc

ncmpc is a client for MPD, the Music Player Daemon. It runs in terminal, provides an intuitive to use ncurses user interface and comes with a large set of useful features, including the ability to search and browse your music library, create playlists and read song lyrics.

Building ncmpc with lyrics support

In order to use the lyrics feature this article is about, you may have to build a current version of ncmpc from source. This article assumes you are at least using ncmpc version 0.15.

After downloading the latest version of ncmpc, untar it and change to the newly created directory. To build ncmpc, the usual three steps for this purpose have to be taken: set the desired build options ("./configure"), build it from source ("make") and install it on your machine ("make install").

You will need to have the following libraries and its header files installed:

The following build options are provided (shortend, pass "--help" for a complete list):

  --enable-colors         Enable color support
  --enable-lirc           Enable LIRC support
  --enable-mouse          Enable curses getmouse support [default=yes]
  --enable-artist-screen  Enable artist screen [default=yes]
  --enable-search-screen  Enable search screen (EXPERIMENTAL) [default=yes]
  --enable-song-screen    Enable song viewer screen [default=yes]
  --enable-key-screen     Enable key editor screen [default=yes]
  --enable-lyrics-screen  Enable lyrics screen [default=no]
  --enable-outputs-screen Enable outputs screen [default=yes]

                          Directory where lyrics plugins are stored

In order to make ncmpc handle your lyrics, add "--enable-lyrics-screen" to your build options and set the directory used to keep your lyrics plugins with "--with-lyrics-plugin-dir=DIR" if you want to store them in a custom location.

After the configure script has finished successfully, run make followed by make install. Do not remove the source tree yet, you may need to copy a set of lyrics plugins later.

Here's a complete example:

$ ./configure --prefix=$HOME/swroot \
              --enable-search-screen \
              --enable-lyrics-screen \
$ make
$ make install

Setting up lyrics plugins

All available plugins are executed by ncmpc one after another on any request for a song's lyrics until a plugin successfully handles the request or no plugins are left. At startup, ncmpc reads the list of available plugins from the plugin directory specified at build time. It sorts and registers all available plugins in alphanumerical order afterwards. This means, that the plugins' names determine in which order they will be executed upon a lyrics request.

As an example, a plugin "" will be executed before one named "".

All plugins you like to enable have to be executable - as a result, disabling a plugin is achieved by removing its execute bit ("chmod a-x $plugin").

Before you can fetch and read lyrics with ncmpc, you have to choose and install a set of plugins to the directory ncmpc uses for this purpose. The plugins should be executed in a reasonable order. If you, for example, have an on-disk library of lyrics, a plugin should try to retrieve a song's lyrics from there first before attempting to fetch it from a remote site like

ncmpc comes with a few plugins, which are located within the "lyrics/" directory of the source directory. Additionally, you may find the following plugins useful:

Copy the plugins you like to use to the plugins directory and make them executable ("chmod a+x $plugins").

All saved lyrics are stored beneath "~/.lyrics/". Note that you can also use any other directory to store your lyrics if you wish - just symlink your directory of choice to "~/.lyrics":

$ ln -s ~/Documents/Lyrics/ ~/.lyrics

Using the lyrics plugins

Once the plugins are setup up, start ncmpc as usual, move the cursor to a song while in Playlist or Browse Screen and press "7" to switch to ncmpc's Lyrics Screen. All available plugins will automatically be launched in sequence to fetch and display the requested lyrics for you.

Alternatively, press "u" while in Lyrics Screen to fetch and display the lyrics for the currently playing song.

If you like to save the retrieved lyrics to read it again later, press "S" and ncmpc will save it below "~/.lyrics/".

To automatically save all lyrics, set "lyrics-autosave" to "yes" in ncmpc's configuration file ("~/.ncmpc/config").

Writing your own lyrics plugins

A plugin can be any type of application (compiled executable, Perl or shell script, ...) that satisfies the following requirements:

For a very basic example, have a look at the "" shell script that comes with ncmpc (in "lyrics/") or at one of the Perl scripts mentioned above ( /