ncmpcpp(1)

📦

version 0.10.1 · 2 versions

0.10.1 · alpine 3.24, arch rolling, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable (latest)
0.9.2 · debian bookworm, debian trixie, opensuse-leap 16.0, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

, in alpine 3.24, arch rolling, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

✨ NAME ✨

okay bestie, meet ncmpcpp(1) from the General Commands Manual — it's an ncurses client for MPD, the Music Player Daemon. It was inspired by ncmpc, and it's giving terminal music main character energy. 💖

🌈 SYNOPSIS 🌈

ncmpcpp [options]

💫 DESCRIPTION 💫

ncmpcpp is an ncurses client for MPD (Music Player Daemon), inspired by ncmpc. That's the core. It's your terminal bestie for controlling MPD.

Read more about MPD at http://www.musicpd.org — literally the source. ✨

🎀 OPTIONS 🎀

Real talk: mandatory arguments to long options are mandatory for short options too. No cap.

-h, --host=HOST — Connect to server at host [localhost]
-p, --port=PORT — Connect to server at port [6600]
--current-song[=FORMAT] — Print current song using given format and exit
-c, --config=FILE — Specify configuration file(s)
--ignore-config-errors — Ignore unknown and invalid options in configuration files
-b, --bindings=FILE — Specify bindings file(s)
-s, --screen <name> — Specify the startup screen (<name> may be: help, playlist, browser, search_engine, media_library, playlist_editor, tag_editor, 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_editor, outputs, visualizer, clock)
-q, --quiet — Suppress logs and excess output
-?, --help — Display help.
-v, --version — Display version information.

💅 CONFIGURATION 💅

When ncmpcpp starts, it tries to read settings from $XDG_CONFIG_HOME/ncmpcpp/config and $HOME/.ncmpcpp/config files. If no configuration is found, ncmpcpp uses its default configuration. An example configuration file containing all default values is provided with ncmpcpp and can be usually found in /usr/share/doc/ncmpcpp (the exact location may depend on your operating system or configure prefix). 🫶

Note: Configuration option values can either be enclosed in quotation marks or not.

If they are enclosed, the leftmost and the rightmost quotation marks are treated as delimiters, therefore it is not necessary 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 useful 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. Note: MPD_HOST environment variable overrides this setting.
mpd_port = PORT — Connect to MPD on the specified port. Note: MPD_PORT environment variable overrides this setting.
mpd_password = PASSWORD — Use PASSWORD to authenticate to MPD.
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_data_source = LOCATION — Source of data for the visualizer. For MPD it's going to be a fifo output, for Mopidy a udpsink output (see the example configuration file for more details).
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_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 spectrum).
visualizer_color = COLORS — Comma separated list of colors to be used in music visualization.
visualizer_fps = FPS — The amount of frames per second for the visualizer.
visualizer_autoscale = yes/no — Automatically scale visualizer size.
visualizer_spectrum_smooth_look = yes/no — For spectrum visualizer, use unicode block characters for a smoother, more continuous look. This will override the visualizer_look option. With transparent terminals and visualizer_in_stereo set, artifacts may be visible on the bottom half of the visualization.
visualizer_spectrum_smooth_look_legacy_chars = yes/no — Use unicode block characters from "symbols for legacy computing". This improves the smooth look on transparent terminals by using special unicode chars instead of reversing the background and foreground color on the bottom edge of the spectrum. If it leads to a garbled output on the bottom edge of the spectrum, you can either change the font or disable this option.
visualizer_spectrum_dft_size = NUMBER — For spectrum visualizer, a value between 1 and 5 inclusive. Specifying a larger value makes the visualizer look at a larger slice of time, which results in less jumpy visualizer output.
visualizer_spectrum_gain = dB — Gain for spectrum visualizer in dB, larger/smaller values shift bars up/down.
visualizer_spectrum_hz_min = Hz — For spectrum visualizer, left-most frequency of visualizer, must be less than HZ MAX.
visualizer_spectrum_hz_max = Hz — For spectrum visualizer, right-most frequency of visualizer, must be greater than HZ MIN.
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 — Song format for lists of songs.
song_status_format — Song format for statusbar.
song_library_format — Song format for media library.
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.
current_item_prefix = TEXT — Prefix for currently selected item.
current_item_suffix = TEXT — Suffix for currently selected item.
current_item_inactive_column_prefix = TEXT — Prefix for currently selected item in the inactive column.
current_item_inactive_column_suffix = TEXT — Suffix for currently selected item in the inactive column.
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 "type", "name", "mtime", "format" and "none".
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.
execute_on_player_state_change = COMMAND — Shell command to execute on player state change. The environment variable MPD_PLAYER_STATE is set to the current state (either unknown, play, pause, or stop) for its duration.
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.
show_duplicate_tags = yes/no — Indicates whether ncmpcpp should display multiple tags as-is or remove duplicates.
incremental_seeking = yes/no — If enabled, seek time will increment by one each second of seeking.
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.
default_place_to_search_in = database/playlist — set it to "playlist" and your Search engine will go digging through the current MPD playlist instead of the whole music database. 💅
user_interface = classic/alternative — the default UI ncmpcpp boots up with. classic or alternative, pick your vibe. ✨
data_fetching_delay = yes/no — turn this on and there's a 250ms delay between refreshing your position in the media library or playlist editor and actually fetching the data from MPD. It limits how much data gets pulled from the server — lowkey a lifesaver if ncmpcpp is connected to a remote host. 🌐
media_library_primary_tag = artist/album_artist/date/genre/composer/performer — the default tag type for the leftmost column in the media library. pick your main character tag. 👑
media_library_albums_split_by_date = yes/no — decides whether albums in the media library get split by date. 📅
media_library_hide_album_dates = yes/no — decides whether album dates in the media library are hidden. 🙈
default_find_mode = wrapped/normal — set it to "wrapped" and going from the last found position to the next one wraps around to the first (same energy for the first position going backwards). otherwise, no actions happen. 🔄
default_tag_editor_pattern = TEXT — the default pattern used by Tag editor's parser. ✍️
header_visibility = yes/no — enabled? header window shows up. disabled? it's hidden. 🫥
statusbar_visibility = yes/no — enabled? statusbar shows. otherwise hidden. 💅
connected_message_on_startup = yes/no — show the "Connected to ..." message when you start up. 📡
titles_visibility = yes/no — enabled? column titles show. otherwise hidden. 🏷️
header_text_scrolling = yes/no — if the text in the header window is longer than the actual screen width, it scrolls. otherwise it just sits there. 🌀
cyclic_scrolling = yes/no — enabled? cyclic scrolling is on. like if you press down arrow at the end of a list, it takes you back to the beginning. 🔁
lyrics_fetchers = FETCHERS — comma separated list of lyrics fetchers. 🎤
follow_now_playing_lyrics = yes/no — enabled? lyrics switch when the song changes to the currently playing one. (Note: this only works if you're viewing lyrics of an item from Playlist.) 👀
fetch_lyrics_for_current_song_in_background = yes/no — enabled? every time the song changes, the lyrics fetcher runs in the background trying to download lyrics for the currently playing song. 🫶
store_lyrics_in_song_dir = yes/no — enabled? lyrics get saved in the song's directory. otherwise they go in ~/.lyrics. note that it needs mpd_music_dir properly set. 📁
generate_win32_compatible_filenames = yes/no — set to yes and filenames generated by ncmpcpp (with tag editor, for lyrics, artists etc.) won't contain these characters: \?*:| 🚫
allow_for_physical_item_deletion = yes/no — set to yes and you can physically delete files and directories from the disk in the browser. careful bestie, no undo. 💀
lastfm_preferred_language = ISO 639 alpha-2 language code — if set, ncmpcpp tries to get info from last.fm in your chosen language, and if that fails it falls back to English. otherwise it uses English the first time. 🌍
space_add_mode = add_remove/always_add — set to add_remove, attempting to add files already in the playlist will remove them. otherwise they can be added multiple times. ➕
show_hidden_files_in_local_browser = yes/no — trigger for showing files and directories in the local browser that begin with . 👻
screen_switcher_mode = SWITCHER_MODE — set to "previous" and key_screen_switcher switches between the current and last used screen. set to "screen1,...screenN" (a list of screens) and it switches between them in a sequence. syntax clarification lives in the example config file. 📑
startup_screen = SCREEN_NAME — the screen displayed at start (playlist by default). 🚀
startup_slave_screen = SCREEN_NAME — the slave screen displayed at start (nothing by default). 🫡
startup_slave_screen_focus = yes/no — set to yes and the slave screen is the active one after startup. otherwise the master screen is. 🎯
locked_screen_width_part = 20-80 — if you want to lock a screen, ncmpcpp asks for the % of locked screen's width to reserve before that and gives a default value, which is the one you set here. 🔒
ask_for_locked_screen_width_part = yes/no — enabled? ncmpcpp asks for the % of locked screen's width every time you want to lock a screen. disable it and it silently tries to use the default value. 🤫
media_library_column_width_ratio_two = a:b — the ratio of column widths in the media library when there are two columns. 📏
media_library_column_width_ratio_three = a:b:c — the ratio of column widths in the media library when there are three columns. 📐
playlist_editor_column_width_ratio = a:b — the ratio of column widths in the playlist editor. 📊
jump_to_now_playing_song_at_start = yes/no — enabled? ncmpcpp jumps at start to the now playing song if mpd is playing or paused. ⏭️
ask_before_clearing_playlists = yes/no — enabled? you get asked if you really want to clear the playlist after pressing the key responsible for that. 🙋
clock_display_seconds = yes/no — enabled? clock shows time as hh:mm:ss. otherwise hh:mm. 🕰️
display_volume_level = yes/no — enabled? volume level shows in the statusbar. otherwise not. 🔊
display_bitrate = yes/no — enabled? bitrate of the currently playing song shows in the statusbar. 🎚️
display_remaining_time = yes/no — enabled? remaining time of the currently playing song shows in the statusbar instead of elapsed time. ⏳
regular_expressions = none/basic/extended/perl — type of currently used regular expressions. 🔍
ignore_leading_the = yes/no — enabled? the word "the" at the beginning of tags/filenames/sort format is ignored while sorting items. 🎵
ignore_diacritics = yes/no — enabled? diacritics in strings are ignored while searching and filtering lists. 🔤
block_search_constraints_change_if_items_found = yes/no — enabled? fields in Search engine above the "Reset" button get blocked after a successful search. otherwise they don't. 🚧
mouse_support = yes/no — set to yes and mouse support is enabled. 🖱️
mouse_list_scroll_whole_page = yes/no — enabled? mouse wheel scrolls the whole page of the item list at a time. otherwise it scrolls the number of lines specified by lines_scrolled. 🖲️
lines_scrolled = NUMBER — number of lines scrolled with the mouse wheel. 📜
empty_tag_marker = TEXT — text displayed if the requested tag is not set. 🏷️
tags_separator = TEXT — separator placed between tags. also interpreted by tag editor, which splits the input string into separate tags using it. ✂️
tag_editor_extended_numeration = yes/no — enabled? tag editor numbers 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 — enabled? media library is sorted by modification time. otherwise lexicographic sorting is used. 🗂️
enable_window_title = yes/no — enabled? ncmpcpp overrides the current window title with its own one. 🪟
search_engine_default_search_mode = MODE_NUMBER — number of the default mode used in the search engine. 🔎
external_editor = PATH — path to the external editor used to edit lyrics. ✏️
use_console_editor = yes/no — if your external editor is a console application, you need to enable this. 🖥️
colors_enabled = yes/no — no need to describe it, huh? 🌈
empty_tag_color = COLOR — color of the empty tag marker. 🎨
header_window_color = COLOR — color of the header window. 🎨
volume_color = COLOR — color of the volume state. 🎨
state_line_color = COLOR — color of the lines separating header and statusbar from the main window. 🎨
state_flags_color = COLOR — color of the MPD status flags. 🎨
main_window_color = COLOR — color of the main window. 🎨
color1 = COLOR — one of the colors used in Song info, Tiny tag editor, and Search engine. 🎨
color2 = COLOR — one of the colors used in Song info, Tiny tag editor, and Search engine. 🎨
progressbar_color = COLOR — color of the progressbar. 🎨
progressbar_elapsed_color = COLOR — color of the part of the progressbar that represents elapsed time. 🎨
statusbar_color = COLOR — color of the statusbar. 🎨
statusbar_time_color = COLOR — color of the current track time shown in the statusbar. 🎨
player_state_color = COLOR — color of the player state shown in the statusbar. 🎨
alternative_ui_separator_color = COLOR — color of the separators used in the alternative user interface. 🎨
window_border_color = BORDER — border color of pop-up windows. if set to 'none', no border is shown. 🖼️
active_window_border = COLOR — color of the active window's border. 🖼️

🎹 BINDINGS 🎹

When ncmpcpp starts, it tries to read bindings from $XDG_CONFIG_HOME/ncmpcpp/bindings and ~/.ncmpcpp/bindings files. If no bindings file is found, ncmpcpp uses the defaults. An example bindings file with default values can be found usually in /usr/share/doc/ncmpcpp (the exact location may depend on your operating system or configure prefix). 💅

You can view current keybindings by pressing F1. 👀

✨ SONG FORMAT ✨

okay bestie, for song format you can use these little icons — they're like the outfit pieces for your track display 💅

%l — length
%f — filename
%F — full filepath
%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 filename.

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 disable only usage of blue color and make red the current one.

🐛 BUGS 🐛

Found a lil gremlin? Report bugs on https://github.com/arybczak/ncmpcpp/issues — the devs wanna know, fr fr 💖

📝 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).