ncmpcpp(1)ncmpcpp(1)NAMEncmpcpp - An ncurses Music Player Daemon (MPD) client.
SYNOPSISncmpcpp [options]
DESCRIPTIONncmpcpp is an ncurses client for MPD (Music Player Daemon), inspired by
ncmpc.
Read more about MPD at http://www.musicpd.org
OPTIONS-h, --host Connect to server at host [localhost]
-p, --port
Connect to server at port [6600]
--current-song
Print current song using given format and exit
-c, --config
Specify configuration file(s)--ignore-config-errors
Ignore unknown and invalid options in configuration files
-c, --bindings
Specify bindings file
-s, --screen <name>
Specify the startup screen (<name> may be: help, playlist,
browser, search_engine, media_library, playlist_editor, tag_edi‐
tor, outputs, visualizer, clock)
-S, --slave-screen <name>
Specify the startup slave screen (<name> may be: help, playlist,
browser, search_engine, media_library, playlist_editor, tag_edi‐
tor, outputs, visualizer, clock)
-?, --help
Display help.
-v, --version
Display version information.
CONFIGURATION
When ncmpcpp starts, it tries to read user's settings from
$HOME/.ncmpcpp/config and $XDG_CONFIG_HOME/ncmpcpp/config files.
If no configuration is found, ncmpcpp uses its default configu‐
ration. An example configuration file containing all default
values is provided with ncmpcpp and can be usually found in
/usr/share/doc/ncmpcpp (exact location may depend on used dis‐
tribution or configure prefix).
Note: Configuration option values can either be enclosed in quo‐
tation marks or not.
- If they are enclosed, the leftmost and the rightmost quota‐
tion marks are treated as delimiters, therefore it is not neces‐
sary to escape quotation marks you use within the value itself.
- If they are not, any whitespace characters between = and the
first printable character of the value, as well as whitespace
characters after the last printable character of the value are
trimmed.
Therefore the rule of thumb is: if you need whitespaces at the
beginning or at the end of the value, enclose it in quotation
marks. Otherwise, don't.
Note: COLOR has to be the name (not a number) of one of colors
1-8 from SONG FORMAT section.
Supported configuration options:
ncmpcpp_directory = PATH
Directory for storing ncmpcpp related files. Changing it is use‐
ful if you want to store everything somewhere else and provide
command line setting for alternative location to config file
which defines that while launching ncmpcpp.
lyrics_directory = PATH
Directory for storing downloaded lyrics. It defaults to
~/.lyrics since other MPD clients (eg. ncmpc) also use that
location.
mpd_host = HOST
Connect to MPD running on specified host/unix socket. When HOST
starts with a '/', it is assumed to be a unix socket.
mpd_port = PORT
Connect to MPD on the specified port.
mpd_music_dir = PATH
Search for files in specified directory. This is needed for tag
editor to work.
mpd_connection_timeout = SECONDS
Set connection timeout to MPD to given value.
mpd_crossfade_time = SECONDS
Default number of seconds to crossfade, if enabled by ncmpcpp.
visualizer_fifo_path = PATH
Path to mpd fifo output. This is needed to make music visualizer
work (note that output sound format of this fifo has to be
either 44100:16:1 or 44100:16:2, depending on whether you want
mono or stereo visualization)
visualizer_output_name = NAME
Name of output that provides data for visualizer. Needed to keep
sound and visualization in sync.
visualizer_in_stereo = yes/no
Should be set to 'yes', if fifo output's format was set to
44100:16:2.
visualizer_sample_multiplier = NUMBER
Multiply received samples by given value. Very useful for proper
visualization of quiet music.
visualizer_sync_interval = SECONDS
Defines interval between syncing visualizer and audio outputs.
visualizer_type = spectrum/wave/wave_filled/ellipse
Defines default visualizer type (spectrum is available only if
ncmpcpp was compiled with fftw support).
visualizer_look = STRING
Defines visualizer's look (string has to be exactly 2 characters
long: first one is for wave whereas second for frequency spec‐
trum).
visualizer_color = COLORS
Comma separated list of colors to be used in music visualiza‐
tion.
system_encoding = ENCODING
If you use encoding other than utf8, set it in order to handle
utf8 encoded strings properly.
playlist_disable_highlight_delay = SECONDS
Delay for highlighting playlist since the last key was pressed.
If set to 0, highlighting never fades away.
message_delay_time = SECONDS
Delay for displayed messages to remain visible.
song_list_format
Format for songs' list.
song_status_format
Song's format for statusbar.
song_library_format
alternative_header_first_line_format = TEXT Now playing song
format for the first line in alternative user interface header
window.
alternative_header_second_line_format = TEXT
Now playing song format for the second line in alternative user
interface header window.
now_playing_prefix = TEXT
Prefix for currently playing song.
now_playing_suffix = TEXT
Suffix for currently playing song.
browser_playlist_prefix = TEXT
Prefix for playlists in Browser.
selected_item_prefix = TEXT
Prefix for selected items.
selected_item_suffix = TEXT
Suffix for selected items.
modified_item_prefix = TEXT
Prefix for modified item (tag editor).
browser_sort_mode
Determines sort mode for browser. Possible values are "name",
"mtime", "format" and "noop".
browser_sort_format
Format to use for sorting songs in browser. For this option to
be effective, browser_sort_mode must be set to "format".
song_window_title_format
Song format for window title.
song_columns_list_format
Format for songs' list displayed in columns.
execute_on_song_change = COMMAND
Shell command to execute on song change.
playlist_show_mpd_host = yes/no
If enabled, current MPD host will be shown in playlist.
playlist_show_remaining_time = yes/no
If enabled, time remaining to end of playlist will be shown
after playlist statistics.
playlist_shorten_total_times = yes/no
If enabled, total/remaining playlist time displayed in statusbar
will be shown using shortened units' names (d:h:m:s instead of
days:hours:minutes:seconds).
playlist_separate_albums = yes/no
If enabled, separators will be placed between albums.
playlist_display_mode = classic/columns
Default display mode for Playlist.
browser_display_mode = classic/columns
Default display mode for Browser.
search_engine_display_mode = classic/columns
Default display mode for Search engine.
playlist_editor_display_mode = classic/columns
Default display mode for Playlist editor.
discard_colors_if_item_is_selected = yes/no
Indicates whether custom colors of tags have to be discarded if
item is selected or not.
incremental_seeking = yes/no
If enabled, seek time will increment by one each second of seek‐
ing.
seek_time = SECONDS
Base seek time to begin with.
volume_change_step = NUMBER
Number of percents volume has to be increased/decreased by in
volume_up/volume_down.
autocenter_mode = yes/no
Default state for autocenter mode at start.
centered_cursor = yes/no
If enabled, currently highlighted position in the list will be
always centered.
progressbar_look = TEXT
This variable defines the look of progressbar. Note that it has
to be exactly two or three characters long.
progressbar_boldness = yes/no
This variable defines whether progressbar should be displayed in
bold or not.
default_place_to_search_in = database/playlist
If set to "playlist", Search engine will perform searching in
current MPD playlist rather than in music database.
user_interface = classic/alternative
Default user interface used by ncmpcpp at start.
data_fetching_delay = yes/no
If enabled, there will be a 250ms delay between refreshing posi‐
tion in media library or playlist editor and fetching appropri‐
ate data from MPD. This limits data fetched from the server and
is particularly useful if ncmpcpp is connected to a remote host.
media_library_primary_tag = artist/album_artist/date/genre/com‐
poser/performer
Default tag type for leftmost column in media library.
default_find_mode = wrapped/normal
If set to "wrapped", going from last found position to next will
take you to the first one (same goes for the first position and
going to previous one), otherwise no actions will be performed.
default_tag_editor_pattern = TEXT
Default pattern used by Tag editor's parser.
header_visibility = yes/no
If enabled, header window will be displayed, otherwise hidden.
statusbar_visibility = yes/no
If enabled, statusbar will be displayed, otherwise hidden.
titles_visibility = yes/no
If enabled, column titles will be displayed, otherwise hidden.
header_text_scrolling = yes/no
If enabled, text in header window will scroll if its length is
longer then actual screen width, otherwise it won't.
cyclic_scrolling = yes/no
If enabled, cyclic scrolling is used (e.g. if you press down
arrow being at the end of list, it'll take you to the beginning)
lines_scrolled = NUMBER
Number of lines that are scrolled with mouse wheel.
follow_now_playing_lyrics = yes/no
If enabled, lyrics will be switched at song's change to cur‐
rently playing one's (Note: this works only if you are viewing
lyrics of item from Playlist).
fetch_lyrics_for_current_song_in_background = yes/no
If enabled, each time song changes lyrics fetcher will be auto‐
matically run in background in attempt to download lyrics for
currently playing song.
store_lyrics_in_song_dir = yes/no
If enabled, lyrics will be saved in song's directory, otherwise
in ~/.lyrics. Note that it needs properly set mpd_music_dir.
generate_win32_compatible_filenames = yes/no
If set to yes, filenames generated by ncmpcpp (with tag editor,
for lyrics, artists etc.) will not contain the following charac‐
ters: \?*:|"<> - otherwise only slash (/) will not be used.
allow_for_physical_item_deletion = yes/no
If set to yes, it will be possible to physically delete files
and directories from the disk in the browser.
lastfm_preferred_language = ISO 639 alpha-2 language code
If set, ncmpcpp will try to get info from last.fm in language
you set and if it fails, it will fall back to english. Otherwise
it will use english the first time.
show_hidden_files_in_local_browser = yes/no
Trigger for displaying in local browser files and directories
that begin with '.'
screen_switcher_mode = SWITCHER_MODE
If set to "previous", key_screen_switcher will switch between
current and last used screen. If set to "screen1,...screenN" (a
list of screens) it will switch between them in a sequence. Syn‐
tax clarification can be found in example config file.
startup_screen = SCREEN_NAME
Screen that has to be displayed at start (playlist by default).
startup_slave_screen = SCREEN_NAME
Slave screen that has to be displayed at start (nothing by
default).
startup_slave_screen_focus = yes/no
If set to yes, slave screen will be the active one after
startup. Otherwise master screen will be.
locked_screen_width_part = 20-80
If you want to lock a screen, ncmpcpp asks for % of locked
screen's width to be reserved before that and provides a default
value, which is the one you can set here.
ask_for_locked_screen_width_part = yes/no
If enabled, ncmpcpp will ask for % of locked screen's width each
time you want to lock a screen. If you disable that, it'll
silently attempt to use default value.
jump_to_now_playing_song_at_start = yes/no
If enabled, ncmpcpp will jump at start to now playing song if
mpd is playing or paused.
ask_before_clearing_playlists = yes/no
If enabled, user will be asked if he really wants to clear the
playlist after pressing key responsible for that.
clock_display_seconds = yes/no
If enabled, clock will display time in format hh:mm:ss, other‐
wise hh:mm.
display_volume_level = yes/no
If enabled, volume level will be displayed in statusbar, other‐
wise not.
display_bitrate = yes/no
If enabled, bitrate of currently playing song will be displayed
in statusbar.
display_remaining_time = yes/no
If enabled, remaining time of currently playing song will be be
displayed in statusbar instead of elapsed time.
regular_expressions = none/basic/extended/perl
Type of currently used regular expressions.
ignore_leading_the = yes/no
If enabled, word "the" at the beginning of tags/filenames/sort
format will be ignored while sorting items.
block_search_constraints_change_if_items_found = yes/no
If enabled, fields in Search engine above "Reset" button will be
blocked after successful searching, otherwise they won't.
mouse_support = yes/no
If set to yes, mouse support will be enabled.
mouse_list_scroll_whole_page = yes/no
If enabled, mouse wheel will scroll the whole page of item list
at a time, otherwise the number of lines specified by
lines_scrolled variable.
empty_tag_marker = TEXT
Text that will be displayed, if requested tag is not set.
tags_separator = TEXT
Separator that is placed between tags. Also interpreted by tag
editor which splits input string into separate tags using it.
tag_editor_extended_numeration = yes/no
If enabled, tag editor will number tracks using format xx/yy
(where xx is the current track and yy is total amount of all
numbered tracks), not plain xx.
media_library_sort_by_mtime = yes/no
If enabled, media library will be sorted by modification time.
Otherwise lexicographic sorting is used.
enable_window_title = yes/no
If enabled, ncmpcpp will override current window title with its
own one.
search_engine_default_search_mode = MODE_NUMBER
Number of default mode used in search engine.
external_editor = PATH
Path to external editor used to edit lyrics.
use_console_editor = yes/no
If your external editor is console application, you need to
enable it.
colors_enabled = yes/no
No need to describe it, huh?
empty_tag_color = COLOR
Color of empty tag marker.
header_window_color = COLOR
Color of header window.
volume_color = COLOR
Color of volume state.
state_line_color = COLOR
Color of lines separating header and statusbar from main window.
state_flags_color = COLOR
Color of MPD status flags.
main_window_color = COLOR
Color of main window.
color1 = COLOR
One of colors used in Song info, Tiny tag editor and Search
engine.
color2 = COLOR
One of colors used in Song info, Tiny tag editor and Search
engine.
main_window_highlight_color = COLOR
Color of main window's highlight.
progressbar_color = COLOR
Color of progressbar.
progressbar_elapsed_color = COLOR
Color of part of progressbar that represents elapsed time.
statusbar_color = COLOR
Color of statusbar.
alternative_ui_separator_color = COLOR
Color of separators used in alternative user interface.
active_column_color = COLOR
Color of active column's highlight.
window_border_color = BORDER
Border color of pop-up windows. If set to 'none', no border will
be shown.
active_window_border = COLOR
Color of active window's border.
BINDINGS
When ncmpcpp starts, it tries to read user's bindings from
~/.ncmpcpp/bindings file. If no bindings file is found, ncmpcpp
uses the defaults. An example bindings file with the default
values can be found usually in /usr/share/doc/ncmpcpp (exact
location may depend on used distribution or configure prefix).
You can view current keybindings by pressing F1.
SONG FORMAT
For song format you can use:
%l - length
%f - filename
%D - directory
%a - artist
%A - album artist
%t - title
%b - album
%y - date
%n - track number (01/12 -> 01)
%N - full track info (01/12 -> 01/12)
%g - genre
%c - composer
%p - performer
%d - disc
%C - comment
%P - priority
$R - begin right alignment
You can also put them in { } and then they will be displayed only if
all requested values are available and/or define alternate value with {
}|{ } e.g. {%a - %t}|{%f} will check if artist and title tags are
available and if they are, display them. Otherwise it'll display file‐
name.
Note: If you want to set limit on maximal length of a tag, just put the
appropriate number between % and character that defines tag type, e.g.
to make album take max. 20 terminal cells, use '%20b'.
Note: Format that is similar to "%a - %t" (i.e. without any additional
braces) is equal to "{%a - %t}", so if one of the tags is missing,
you'll get nothing.
Text can have different color than the main window, e.g. if you want
length to be green, write $3%l$9.
Available values for colors:
- 0 - default window color (discards all other colors)
- 1 - black
- 2 - red
- 3 - green
- 4 - yellow
- 5 - blue
- 6 - magenta
- 7 - cyan
- 8 - white
- 9 - end of current color
Note: colors can be nested, so if you write $2some$5text$9, it'll dis‐
able only usage of blue color and make red the current one.
BUGS
Report bugs on http://www.musicpd.org/mantis/
NOTE
Since MPD uses UTF-8, ncmpcpp needs to convert characters to the
charset used by the local system. If you get character conversion
errors while you are running ncmpcpp, you probably need to set up your
locale. This is done by setting LANG and LC_ALL/LC_CTYPE environment
variables (LC_CTYPE only affects character handling).
HOMEPAGE
-> http://unkart.ovh.org/ncmpcpp
SEE ALSOmpc(1), mpd(1)ncmpcpp(1)
