Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
NCMPC(1)			     ncmpc			      NCMPC(1)

       ncmpc - ncmpc Documentation

       ncmpc is	a command-line client for the Music Player Daemon (MPD).

       By  default, ncmpc connects to the local	MPD instance.  A different MPD
       instance	can be selected	using the  command  line  options  --host  and
       --port, or by setting the environment variables MPD_HOST	and MPD_PORT:

	  ncmpc	--host=musicserver --port=44000

       You  can	connect	to a "local" socket by setting the host	to a file path
       (e.g. "/run/mpd/socket").  Abstract sockets can be used with a "@" pre-
       fix (e.g. "@mpd").

       To  use	a  password with MPD, set MPD_HOST to password@host or use the
       command line option --password.	Values from the	command	line  override
       values from the environment.

	  ncmpc	[options]

       -?, --help
	      Display help.

       -V, --version
	      Display version information and build-time configuration.

       -c, --colors
	      Enable colors.

       -C, --no-colors
	      Disable colors.

       -m, --mouse
	      Enable mouse.

	      The MPD host to connect to.

       --port=PORT, -p PORT
	      The port to connect to.

       -P, --password=PASSWORD
	      Use password when	connecting.

       -f, --config=FILE
	      Read configuration from file.

       -k, --key-file=FILE
	      Read key bindings	from file.

       When  ncmpc  starts  it	tries  to  read	the user's configuration file,
       $XDG_CONFIG_HOME/ncmpc/config (usually ~/.config/ncmpc/config).	If  no
       user  configuration  file  is found then	ncmpc tries to load the	global
       settings	from $SYSCONFDIR/ncmpc/config (the actual path is displayed in
       the  output  of	the  --version option).	 An example configuration file
       (config.sample) is shipped with ncmpc.

       host = HOST - The MPD host to connect to.

       port = PORT - The port to connect to.

       password	= PASSWORD - Use password when connecting.

       timeout = TIMEOUT - Attempt to reconnect	to mpd if a response to	a com-
       mand  is	not received within TIMEOUT seconds. Specifying	a value	in the
       configuration file overrides the	 "MPD_TIMEOUT"	environment  variable.
       If no timeout is	specified in the configuration file or in the environ-
       ment, the default is 5 seconds.

       enable-mouse = yes|no - Enable mouse support  (if  enabled  at  compile

       screen-list  =  SCREEN1 SCREEN2... - A list of screens to cycle through
       when using the commands screen-next (bound to  "Tab"  by	 default)  and
       screen-prev  ("Shift+Tab").  Valid choices, if enabled at compile time,
	  help,	playlist, browse,  library,  search,  lyrics,  outputs,	 chat,
	  song,	keydef

       The default is playlist browser,	i.e. the "Tab" key cycles only between
       those two pages.

       library-page-tags = TAG1	TAG2 ... - A list of tags to group the library
       page.  The default is artist album.

       search-mode  =  MODE  - Default search mode for the search screen. MODE
       must be one of title, artist, album, filename, and artist+title,	or  an
       integer index (0	for title, 1 for artist	etc.).

       auto-center  = yes|no - Enable/disable auto center mode.	When auto cen-
       ter mode	is enabled ncmpc centers the current  track  in	 the  playlist

       scroll-offset  =	NUM - Keep at least NUM	lines above and	below the cur-
       sor on list windows, if possible.

       find-show-last =	yes|no - Show the most recent query instead of a blank
       line for	a find.

       find-wrap = yes|no - Wrapped find mode.

       wrap-around = yes|no - Wrapped cursor movement.

       bell-on-wrap = yes|no - Ring bell when find wraps around.

       audible-bell = yes|no - Sound audible bell on alerts.

       visible-bell = yes|no - Visible bell on alerts.

       crossfade-time =	CROSSFADE TIME - Default crossfade time	in seconds.

       seek-time = NUM - Seek forward/backward by NUM seconds.

       lyrics-timeout  =  NUM  -  Quits	downloading lyrics of a	song after the
       timeout of NUM seconds is reached, if NUM is greater than zero.

       jump-prefix-only	= yes|no - When	using the jump command,	search for the
       prefix  of an entry.  That means	typing "m" will	start to the first en-
       try which begins	with "m".

       lyrics-autosave = yes|no	- Automatically	save  lyrics  after  receiving

       lyrics-show-plugin  =  yes|no - Show the	name of	the plugin used	to re-
       ceive lyrics on the lyrics screen.

       text-editor = EDITOR - The text editor used for editing lyrics.

       text-editor-ask = yes|no	- Ask before starting an editor.

       chat-prefix = PREFIX - Prefix messages send with	the chat  screen  with
       PREFIX.	 By  default  they are prefixed	with the current user name en-
       closed by < and > and a space (i.e. "<name> ").

       second-column = yes|no -	Display	song length in a second	column.

       welcome-screen-list = yes|no - Show a list of the screens  in  the  top

       wide-cursor = yes|no - Make the cursor as wide as the screen.

       hardware-cursor	=  yes|no - Use	the terminal's hardware	cursor instead
       of inverse colors.

       hide-cursor = NUM - Hide	the playlist cursor after NUM seconds of inac-

       scroll =	yes|no - Scroll	the title if it	is too long for	the screen.

       scroll-sep = STRING - the separator to show at the end of the scrolling

       list-format = SONG FORMAT - The format used to  display	songs  in  the
       main window.

       search-format  =	 SONG FORMAT - The format used to display songs	in the
       search window. Default is to use	list-format.

       status-format = SONG FORMAT - The format	used to	display	songs  on  the
       status line.

       status-message-time  =  TIME  -	The time, in seconds, for which	status
       messages	will be	displayed.

       display-time = yes|no - Display the time	in the status bar when idle.

       timedisplay-type	= elapsed|remaining|none - Sets	whether	to display re-
       maining	or  elapsed  time  in  the status window.  Default is elapsed.
       none doesn't show the time at all.

       visible-bitrate = yes|no	- Show the bitrate  in	the  status  bar  when
       playing a stream.

       set-xterm-title	=  yes|no - Change the XTerm title (ncmpc will not re-
       store the title).

       xterm-title-format = SONG FORMAT	- The format used to for the xterm ti-
       tle when	ncmpc is playing.

       enable-colors = yes|no -	Enable/disable colors.	Defaults to yes.

       The colors used by ncmpc	can be customized.  The	color directive	can be
       used to change how a certain style looks.  It can contain a text	 color
       and attributes.	The following standard colors can be specified by name
       (official reference):
	  black, red, green, yellow, blue, magenta, cyan, white


	  color	list = cyan

       Modern terminals	support	up to 256 colors, but they are	not  standard-
       ized.  You can select them by specifying	the number.  Example:

	  color	title =	42

       The background color can	be specified after the text color separated by
       a slash.	 You can omit the text color if	you want to  change  only  the
       background color:

	  color	title =	white/blue
	  color	title =	/blue

       The color none uses the terminal's default color.

       Attributes  can	be  used to modify the font appearance.	 The following
       attributes can be specified (official reference), though	many  of  them
       are not supported by prevalent terminals:
	  standout, underline, reverse,	blink, dim, bold


	  color	alert =	red blink

       color background	= COLOR	- Set the default background color.

       color  title = COLOR[,ATTRIBUTE]... - Set the text color	and attributes
       for the title row, which	displays the page names.

       color title-bold	= COLOR[,ATTRIBUTE]... - Like title, but refers	to em-
       phasized	 parts	of the title row, i.e. the hot keys for	switching to a
       specific	page.

       color line = COLOR - Set	the color of the line on the second row.

       color line-flags	= COLOR[,ATTRIBUTE]... - Set the text  color  used  to
       indicate	mpd flags on the second	row.

       color list = COLOR[,ATTRIBUTE]... - Set the text	color in the main area
       of ncmpc.

       color list-bold = COLOR[,ATTRIBUTE]... -	Set the	bold text color	in the
       main area of ncmpc.

       color  browser-directory	 =  COLOR[,ATTRIBUTE]...  - Set	the text color
       used to display directories in the browser window.

       color browser-playlist =	COLOR[,ATTRIBUTE]... - Set the text color used
       to display playlists in the browser window.

       color  progressbar  =  COLOR[,ATTRIBUTE]...  -  Set  the	 color	of the
       progress	indicator.

       color progressbar-background = COLOR[,ATTRIBUTE]... - Set the color  of
       the progress indicator background.

       color  status-state = COLOR[,ATTRIBUTE]... - Set	the text color used to
       display mpd status in the status	window.

       color status-song = COLOR[,ATTRIBUTE]...	- Set the text color  used  to
       display song names in the status	window.

       color  status-time  = COLOR[,ATTRIBUTE]... - Set	the text color used to
       display time the	status window.

       color alert = COLOR[,ATTRIBUTE]... - Set	the text color used to display
       alerts in the status window.

       colordef	 COLOR	=  R,  G, B - Redefine any of the base colors. The RGB
       values must be integer values between 0 and 1000.  Note:	Only some ter-
       minals allow redefinitions of colors!

       When  ncmpc  starts it tries to read user-defined key bindings from the
       $XDG_CONFIG_HOME/ncmpc/keys (usually ~/.config/ncmpc/keys) file.	 If no
       user-defined key	bindings are found then	ncmpc tries to load the	global
       key bindings from $SYSCONFDIR/ncmpc/keys	(the actual path is  displayed
       on the help screen).

       You  can	view ncmpc's key bindings by pressing '1' (help) when ncmpc is
       running.	 To edit key bindings press 'K'	and  use  the  key  editor  in

       Format  of  song	 display for status and	the list window.  The metadata
       delimiters are: %artist%, %albumartist%,	%composer%, %performer%,  %ti-
       tle%,  %album%,	%shortalbum%, %track%, %disc, %genre%, %name%, %time%,
       %date%, %file%, %shortfile%.

       The [] operators	are used to group output such  that  if	 none  of  the
       metadata	delimiters between [ and ] are matched,	then none of the char-
       acters between [	and ] are output; literal text is  always  output.   &
       and  | are logical operators for	and and	or.  # is used to escape char-

       Some useful examples for	format are:



	  "[[%artist% -	]%title%]|%file%"

       Another one is:

	  "[%artist%|(artist n/a)] - [%title%|(title n/a)]"

       If  ncmpc  has  been  compiled  with  "chat"  support,  it   uses   the
       client-to-client	 protocol  available in	MPD 0.17 or higher to communi-
       cate with other clients.	 In order to receive messages it subscribes to
       the  channel  with the name "chat", and displays	any message sent there
       as-is.  When the	user enters a message, it is  first  with  the	prefix
       specified  by  the chat-prefix option (or the default prefix), and then
       sent to the "chat" channel for others to	read.

       Report bugs on

       Note ---

       Since MPD uses UTF-8, ncmpc needs to convert characters to the  charset
       used  by	the local system.  If you get character	conversion errors when
       your running ncmpc you probably need to set up your  locale.   This  is
       done  by	 setting any of	the LC_CTYPE, LANG or LC_ALL environment vari-
       ables (LC_CTYPE only affects character handling).

       mpd(1), mpc(1), locale(5), locale(7)

       Max Kellermann

       Copyright (C) 2004-2020 The Music Player	Daemon Project

0.41				 Nov 05, 2021			      NCMPC(1)


Want to link to this manual page? Use this URL:

home | help