NAME
ncmpcpp - An ncurses Music Player Daemon (MPD) client.
SYNOPSIS
ncmpcpp [options]
DESCRIPTION
ncmpcpp 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]
-?, --help
Display help.
-v, --version
Display version information.
--now-playing
Display now playing song [{{(%l) }{{%a - }%t}}|{%f}}]
play Start playing and exit.
pause Pause and exit.
toggle Toggle playing and exit.
stop Stop playing and exit.
next Switch to next song and exit.
prev Switch to previous song and exit.
volume [+-]<number>
Raise/lower volume by given number of percents and exit.
CONFIGURATION
When ncmpcpp starts, it tries to read user’s settings from the
~/.ncmpcpp/config file. If no user’s configuration is found,
ncmpcpp uses its default configuration. An example configuration
file containing all default values is provided with ncmpcpp and
can be found usually in /usr/share/doc/ncmpcpp (exact location
may depend on used distribution/OS/configure prefix).
Note: Each config option value must be enclosed in quotation
marks (var = "example"). If you want to use quotation mark
inside config option, prepend character ’\’ to it.
Note: COLOR has to be the name (not a number) of one of colors
1-8 from SONG FORMAT section.
Supported configuration options:
mpd_host = HOST
Connect to MPD running on specified host/unix socket.
mpd_music_dir = PATH
Search for files in specified directory. This is needed for tag
editor to work.
mpd_port = PORT
Connect to MPD on the specified port.
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.
mpd_communication_mode = MODE
If set to ’polling’, ncmpcpp will constantly poll mpd for its
status. If set to ’notifications’, ncmppcp will make use of
’idle’ command and wait for events. This is more efficient and
responsive, but kinda experimental. If you decide to use it, you
may want to run the latest mpd version available.
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
44100:16:1)
visualizer_output_name = NAME
Name of output that provides data for visualizer. Needed to keep
sound and visualization in sync.
visualizer_sync_interval = SECONDS
Defines interval between syncing visualizer and audio outputs.
visualizer_type = spectrum/wave
Defines default visualizer type (spectrum is available only if
ncmpcpp was compiled with fftw support).
system_encoding = ENCODING
If you use encoding other than utf8, set it in order to handle
utf8 encoded strings properly.
seek_time = SECONDS
Base seek time to begin with.
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_columns_list_format
Format for songs’ list displayed in columns.
song_status_format
Song’s format for statusbar.
song_library_format
Format for songs in Media library.
tag_editor_album_format
Format for albums’ list in Tag editor.
song_window_title_format
Song format for window title.
external_editor = PATH
Path to external editor used to edit lyrics.
browser_playlist_prefix = TEXT
Prefix for playlists in Browser.
default_tag_editor_pattern = TEXT
Deafult pattern used by Tag editor’s parser.
now_playing_prefix = TEXT
Prefix for currently playing song.
now_playing_suffix = TEXT
Suffix for currently playing song.
selected_item_prefix = TEXT
Prefix for selected items.
selected_item_suffix = TEXT
Suffix for selected items.
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.
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.
colors_enabled = yes/no
No need to describe it, huh?
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.
fancy_scrolling = yes/no
If enabled, content of other columns will be updated immediately
while scrolling, otherwise only after you stop scrolling.
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)
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.
lines_scrolled = NUMBER
Number of lines that are scrolled with mouse wheel.
search_engine_default_search_mode = MODE_NUMBER
Number of default mode used in search engine.
playlist_show_remaining_time = yes/no
If enabled, time remaining to end of playlist will be shown
after playlist’s statistics.
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.
discard_colors_if_item_is_selected = yes/no
Indicates whether custom colors of tags have to be discarded if
item is selected or not.
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.
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 characters long.
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_space_mode = select/add
If set to "select", space will select items instead of adding
them to playlist (although selecting by space is default and the
only one action for space in Playlist).
default_tag_editor_left_col = albums/dirs
If set to "albums", tag editor will display list of all albums
from database, otherwise it’ll allow you to browse the database.
incremental_seeking = yes/no
If enabled, seek time will increment by one each second of
seeking.
follow_now_playing_lyrics = yes/no
If enabled, lyrics will be switched at song’s change to
currently playing one’s (Note: this works only if you are
viewing lyrics of item from Playlist).
ncmpc_like_songs_adding = yes/no
If enabled, pressing space on item, which is already in playlist
will remove it, otherwise add it again.
show_hidden_files_in_local_browser = yes/no
Trigger for displaying in local browser files and directories
that begin with ’.’
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.
display_screens_numbers_on_start = yes/no
If enabled, screens’ names and their keybindings will be shown
in header window until key is pressed, otherwise they won’t be
displayed at all.
screen_switcher_previous = SWITCHER_MODE
If set to "previous", key_screen_switcher will switch between
current and last used screen. If set to "sequence:
user_defined_sequence", it will switch between given sequence of
screens. Syntax clarification can be found in example config
file.
startup_screen = SCREEN_NUMBER
Screen that has to be displayed at start (playlist by default).
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_main_playlist = yes/no
If enabled, user will be asked if he really wants to clear the
main playlist after pressing key responsible for that.
clock_display_seconds = yes/no
If enabled, clock will display time in format hh:mm:ss,
otherwise hh:mm.
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.
ignore_leading_the = yes/no
If enabled, word "the" at the beginning of tags/filenames will
be ignored while sorting items.
use_console_editor = yes/no
If your external editor is console application, you need to
enable it.
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
Self-descriptive, isn’t it?
allow_physical_files_deletion = yes/no
If enabled, ncmpcpp will be able to delete files using its
browser screen.
allow_physical_directories_deletion = yes/no
If enabled, ncmpcpp will be able to delete directories using its
browser screen.
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_display_date = yes/no
If enabled, dates of albums in media library will be displayed
and respected in searching, otherwise not.
media_library_disable_two_column_mode = yes/no
If enabled, pressing the key for the media library twice won’t
switch it to two column mode.
enable_window_title = yes/no
If enabled, ncmpcpp will override current window title with its
own one.
regular_expressions = basic/extended
Type of currently used regular expressions.
lyrics_database = NUMBER
Number of lyrics database in use. Currently supported DBs are:
1 - lyricsplugin.com
user_interface = classic/alternative
Default user interface used by ncmpcpp at start.
media_library_left_column = a/y/g/c/p
Default tag type for left column in media library. Legend for
possible letters is in SONG FORMAT section.
empty_tag_marker = TEXT
Text that will be displayed, if requested tag is not set.
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.
main_window_highlight_color = COLOR
Color of main window’s highlight.
progressbar_color = COLOR
Color of progressbar.
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.
active_window_border = COLOR
Color of active window’s border.
KEYS When ncmpcpp starts, it tries to read user’s keybindings from
~/.ncmpcpp/keys file. If no user’s keybindings is found, ncmpcpp
uses its default keybindings. An example keybindings file
containing all default values is provided with ncmpcpp and can
be found usually in /usr/share/doc/ncmpcpp (exact location may
depend on used distribution/OS/configure prefix).
You can view current ncmpcpp’s keybindings by pressing ’1’
(Help).
SONG FORMAT
For song format you can use:
%l - length
%f - filename
%D - directory
%a - artist
%A - album artist
%t - title
%b - album
%y - year
%n - track number (01/12 -> 01)
%N - full track info (01/12 -> 01/12)
%g - genre
%c - composer
%p - performer
%d - disc
%C - comment
$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
filename.
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
disable 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 ALSO
mpc(1), mpd(1)
ncmpcpp(1)