From ArchWiki

Ncmpcpp is an mpd client (compatible with mopidy) with a UI very similar to ncmpc, but it provides new useful features such as support for regular expressions for library searches, extended song format, items filtering, the ability to sort playlists, and a local filesystem browser.

To use it, a functional mpd must be present on the system since ncmpcpp/mpd work together in a client/server relationship.


Install ncmpcpp from the official repositories.

Basic configuration

The shell "GUI" for ncmpcpp is highly customizable. Edit $XDG_CONFIG_HOME/ncmpcpp/config to your liking. If, after installation, $XDG_CONFIG_HOME/ncmpcpp/config has not been created, simply copy the sample config, change owner and edit at the very least the following three configuration options:

  • mpd_host - Should point to the host on which mpd resides, can be "localhost", "" or "::1" if on the same machine. To connect with a password, write "password@host"
  • mpd_port - The default of mpd should be "6600"
  • mpd_music_dir - The same directory value as specified in "music_directory" in mpd.conf

For inspiration, see the following resources:

Enabling visualization

For visualization, add a few lines to /etc/mpd.conf or ~/.config/mpd/mpd.conf to enable the generation of the fast Fourier transform data for the visualization:

audio_output {
    type                    "fifo"
    name                    "my_fifo"
    path                    "/tmp/mpd.fifo"
    format                  "44100:16:2"
Note: You may need to add an audio_output section for the normal audio output. See Music Player Daemon#Audio configuration for details.

Additional lines need to be added to $XDG_CONFIG_HOME/ncmpcpp/config

visualizer_data_source = "/tmp/mpd.fifo"
visualizer_output_name = "my_fifo"
visualizer_in_stereo = "yes"
visualizer_type = "spectrum"
visualizer_look = "+|"
  • visualizer_type - Set the visualization to either a spectrum/ellipse/wave_filled analyzer or wave form.
  • visualizer_look - Set the visualizer's look (string has to be exactly 2 characters long: first one is for wave and whereas second for frequency spectrum, wave_filled and ellipse).
Note: If you experience synchronization issues, change the buffer_time in your mpd configuration to 100000 or less.

If you use mopidy, visualization is handled via gstreamer's udpsink. Edit the output in the [audio] block of your mopidy.conf:

output = tee name=t ! queue ! autoaudiosink t. ! queue ! audio/x-raw,rate=44100,channels=2,format=S16LE ! udpsink host=localhost port=5555

This forwards the audio data to port 5555. For ncmpcpp to read from this port, change its visualizer_data_source accordingly:

visualizer_data_source = "localhost:5555"

Basic usage

Tango-edit-cut.pngThis section is being considered for removal.Tango-edit-cut.png

Reason: Assuming that the internal F1 help also shows these shortcuts, they can be removed here. (Discuss in Talk:Ncmpcpp#Deletion of the key list)

Loading ncmpcpp

Load ncmpcpp in a shell:

$ ncmpcpp

Different views

Partial list of views within ncmpcpp:

  • 1 - Current playlist
  • 2 - Filesystem browser
  • 3 - DB search
  • 4 - Library
  • 5 - Playlist editor
  • 6 - Tag editor (very powerful!)
  • 7 - Output selector
  • 8 - Music visualizer
  • = - Clock
  • F1 - Help

Other UI keys

  • q - Quit
  • f - Seek forward
  • b - Seek backward
  • \ - Switch between classic and alternative views
  • # - Display bitrate of file
  • i - Show song info
  • I - Show artist info (saved in $XDG_CONFIG_HOME/ncmpcpp/config/artists/ARTIST.txt)
  • L - Shuffle between available lyric databases
  • l - Retrieve song lyrics for current song Show/hide lyrics
  • > - Next track
  • < - Previous track
  • p - Play/Pause
  • + - Increase volume 2%
  • - - Decrease volume 2%

Playback modes

Notice the control panel in the upper right; shown in alternative mode:

1:40/4:16 1082 kbps                            ──┤ Criminal ├──                                       Vol: 98%
[playing]                             Disturbed - Indestructible (2008)                               [-z-c--]

And again in classic mode:


This corresponds to the playback modes; ordered from left to right, they are:

  • r - repeat mode [r-----] (Repeats the playlist after reaching the end.)
  • z - random mode [-z----]
  • y - single mode [--s---] (Only plays a single track and then stops.)
  • R - consume mode [---c--] (Removes the current track from playlist after reaching the end.)
  • x - crossfade mode [----x-]

The final "-" is only active when the user forces an update to the datebase via u.

In order to loop a single track, turn on both single and repeat mode.

Tips and tricks

Remapping keys

A listing of key bindings and their respective functions is available from within npmpcpp itself via hitting F1. Users may remap any of the default keys simply by copying /usr/share/doc/ncmpcpp/bindings to $XDG_CONFIG_HOME/ncmpcpp/ and editing it.

Autoset Tags from Filename and vice versa

In the Tag Editor you can select a directory with music and then select the Filename option in the middle section. This opens a little window with two options: Get Tags from Filename and Rename files. If you choose Get Tags From Filename, a popup with two windows is shown. On the left side you can enter a pattern that extracts the selected information from the filenames. You can also hit Preview to see what the result would look like. On the right side you can see the legend containing all the possible keywords to be used for extraction.

A simple Example would be the pattern: %a - %t. If your files are named according to this pattern (Artist - Title) then this pattern would extract this information and set the Tags for the File.

The other option Rename Files does the exact opposite. It takes the Tags from the audio files and creates a Filename from them.

Notification on song change

The execute_on_song_change command can be coupled with notify-send to generate notifications whenever the song changes (and upon application launch). This is contingent upon having a notification server installed and configured. Edit $XDG_CONFIG_HOME/ncmpcpp/config, for example:

execute_on_song_change = notify-send "Now Playing" "$(mpc --format '%title% \n%artist% - %album%' current)"

See also configurations