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

FreeBSD Manual Pages


home | help
CMUS(1)			    General Commands Manual		       CMUS(1)

       cmus - C* Music Player

       cmus [options]

       cmus is a lightweight ncurses music player. It supports various output
       methods by using	dynamically-loaded output plugins. cmus	has
       configurable keybindings	and can	be controlled externally using

       --listen	ADDR
	      Listen on	ADDR (UNIX socket) instead of $CMUS_SOCKET or
	      $XDG_RUNTIME_DIR/cmus-socket. ADDR must be a UNIX	socket or

	      WARNING: Using host[:port] is insecure even with a password! It
	      may be on	a LAN if you want multiple users to able to control
	      cmus. Never expose cmus to the internet.

	      NOTE: Don't use this option to run multiple instances as same
	      user. Doing so would corrupt the track metadata cache.

       --passwd	PASSWD
	      Set the password for TCP/IP connections. Required	if listening
	      on host[:port]. Used in conjunction with --listen.

	      List available plugins and exit.

	      Always display the cursor. This is useful	for screen readers.

	      Display usage information	and exit.

	      Display version information and exit.

       There are 7 views in cmus. Press	keys 1-7 to change active view.

       Library view (1)
	      Displays all tracks in the library. Tracks are sorted and
	      displayed	in a tree grouped by artist/album. Artist sorting is
	      done alphabetically. Albums are sorted by	year.

       Sorted library view (2)
	      Displays the same	content	as view	1, but as a simple list
	      automatically sorted by user criteria.

       Playlist	view (3)
	      Displays editable	playlists with optional	sorting.

       Play Queue view (4)
	      Displays upcoming	tracks.	These tracks are played	before
	      anything else (i.e. the playlist or library). Once the queue is
	      empty, playback will resume from the last	position in the

       Browser (5)
	      Displays the directory browser. In this view, music from the
	      filesystem can be	added to the library, active playlist, or

       Filters view (6)
	      Lists user-defined filters.

       Settings	view (7)
	      Lists keybindings, unbound commands and options. Remove bindings
	      with D or	del, change bindings and variables with	enter, and
	      toggle variables with space.

       Everything in cmus is implemented as commands which can be typed	at
       command line or bound to	a key. To enter	command	mode type :. To
       execute a command, press	ENTER, and to cancel, press ESC	or CTRL-C. Use
       up/down arrows to browse	the command history. Use TAB to	complete
       commands	and parameters.	You don't need to type full command name if it
       is unambiguous (no other	commands starting with the same	characters).


	      #	add files, short for ':add ~/music'
	      :a ~/music

	      #	change output plugin
	      :set output_plugin=oss

	      #	start playing
	      #	you could just press 'x' which is the default
	      #	binding	for this command

	      #	clear current view (library, playlist or play queue)

       Search mode works like the command mode.	To enter search	mode, press /
       and type	the query then press ENTER. Press n to move to the next	result
       or N for	the previous one. Type ? to search backwards.

       In views	1-4 the	query is matched against the artist, album and title
       tags. Type //WORDS or ??WORDS to	search only artists/albums in view 1
       and only	titles in views	2-4. If	the file doesn't have tags, words are
       compared	to the filename	excluding the path.

       Searching also works in views 5-7.

   Selecting Tracks
       Editing commands	affect the currently marked tracks. If there are no
       marked tracks, the currently selected track (or selected	artist/album
       in view 1) is used.

       To mark the selected track, press SPACE.	Marked tracks appear with a
       gray background.	You can	only mark tracks in the	list views (2-4).

   Copying Tracks Between Views
       You can copy marked or selected tracks in views 1-5.

       a      copy tracks to the library (1-2)

       y      copy tracks to the marked	playlist (3)

       e      append tracks to the play	queue (4)

       E      prepend tracks to	the play queue (4)

   Moving Tracks
       In views	2-4, tracks can	be moved within	the list. Note that moving is
       disabled	if the view is auto-sorted (see	lib_sort and pl_sort options).

       Pressing	p moves	marked tracks to the position immediately after	the
       selected	track. P moves them to the position immediately	before the
       selected	track. If there	are no marked tracks, the selected track is
       moved down (p) or up (P).

       Note that changing active filters in view 2 reloads it, losing any
       changes made to the track order.

   Removing Tracks
       Press D or delete to remove the marked or selected tracks in the
       current view (1-4). The tracks will be removed immediately from the
       view without asking for confirmation. In	the browser and	filters	views,
       the same	keys are used to remove	a file or filter after asking for

       The right hand side of the status line (second row from the bottom,
       black text on a grey background)	consists of the	following fields:

       aaa_mode	& play_sorted &	play_library | continue	follow repeat shuffle

       NOTE: aaa_mode and play_sorted will be only displayed if	play_library
       is true because these are meaningless when playing the playlists	(view

       Pressing	m, o, M, C, r and s should make	it easier to understand	what
       these fields mean.

       See CONFIGURATION OPTIONS section for more information about these

       Here's list of default keybindings. To change them, see the unbind and
       bind commands in	the COMMANDS section.

   Common: Playback
       b		       player-next
       c		       player-pause
       x		       player-play
       z		       player-prev
       v		       player-stop

       ]		       vol +0 +1%
       [		       vol +1% +0
       +		       vol +10%
       =		       vol +10%
       }		       vol -0 -1%
       {		       vol -1% -0
       -		       vol -10%

       ,		       seek -1m
       .		       seek +1m

       h		       seek -5
       l		       seek +5

       left		       seek -5
       right		       seek +5

       mlb_click_bar	       player-pause
       mouse_scroll_up_bar     seek +5
       mouse_scroll_down_bar   seek -5

   Common: Setting Toggles
       m		       toggle aaa_mode
       C		       toggle continue
       M		       toggle play_library
       o		       toggle play_sorted
       r		       toggle repeat
       ^R		       toggle repeat_current
       t		       toggle show_remaining_time
       s		       toggle shuffle
       f		       toggle follow

   Common: Commands
       q		       quit -i
       ^C		       echo Type :quit<enter> to exit cmus.
       I		       echo {}

       !		       push shell<space>

   Common: View/Window Navigation
       1		       view tree
       2		       view sorted
       3		       view playlist
       4		       view queue
       5		       view browser
       6		       view filters
       7		       view settings

       mouse_scroll_up_title   left-view
       mouse_scroll_down_title right-view

       tab		       win-next

       ^L		       refresh

   Common: Navigation
       ^Y		       win-scroll-up
       ^E		       win-scroll-down
       ^B		       win-page-up
       ^F		       win-page-down
       ^U		       win-half-page-up
       ^D		       win-half-page-down

       k		       win-up
       j		       win-down
       g		       win-top
       G		       win-bottom

       up		       win-up
       down		       win-down
       home		       win-top
       end		       win-bottom
       page_up		       win-page-up
       page_down	       win-page-down

       mouse_scroll_up	       win-up
       mouse_scroll_down       win-down

   Common: Selection
       i		       win-sel-cur
       enter		       win-activate
       mlb_click_selected      win-activate

       space		       win-toggle
       D		       win-remove
       delete		       win-remove
       p		       win-mv-after
       P		       win-mv-before

       E		       win-add-Q
       a		       win-add-l
       y		       win-add-p
       e		       win-add-q

       u		       update-cache
       U		       win-update-cache

   Common: Filters
       /		       search-start
       ?		       search-b-start
       n		       search-next
       N		       search-prev

       F		       push filter<space>
       L		       push live-filter<space>

   File	Browser
       space		       win-activate
       backspace	       browser-up
       i		       toggle show_hidden
       u		       win-update

       The library view	(the tree-like one; not	the sorted library view, which
       is configured with lib_sort - see CONFIGURATION OPTIONS), is sorted
       automatically using tags	from the audio files.

       Note: Albums which feature various artists (e.g.	samplers or
       compilations) are treated specially. If an album	artist tag or the
       ID3v2 TPE2 frame	is set,	it will	be used	instead	of the real artist
       name. Otherwise,	cmus determines	if the album is	a compilation (if
       albumartist or artist are set to	Various	Artists, Various, VA, or V/A;
       or if compilation or partofacompilation are set to a truthy value; or
       if the ID3v2 TCMP frame is set).	If so, the artist is named <Various

       Note: If	the filename is	a URL, the artist/album	tags are set to
       <Stream>. If it is a file, cmus sets the	artist and/or album tags to
       <No Name> if they are not already set. These names will be treated the
       same way	as other names for sorting.

       In general, three levels	of sorting are used in the library view: the
       artist name, then the album, and	finally	the track itself.

       First, cmus sorts alphanumerically by the value of the artist tag. If a
       special sorting tag is available, its value will	be used	instead.

       Next, cmus sorts	by the album. Tracks are grouped by the	album name,
       and the groups are sorted by the	date of	the first track, then
       alphanumerically	by the name of the album. If the date header is	not
       set, the	album will be placed on	top of the list.

       Finally,	each album is sorted by	the track discnumber, tracknumber,
       then filename (not the track name).

       This section describes cmus' commands, which can	be bound to keys and
       mouse events, put in configuration files, executed in command mode, or
       passed to cmus-remote.

       Optional	parameters are in [brackets], required parameters in <angle
       brackets> and default key bindings are (parenthesized).

       add [-l]	[-p] [-q] [-Q] <file|dir|url|playlist>
	      Adds file/dir/url/playlist to the	specified view or the current

	      -l     add to library

	      -p     add to playlist

	      -q     add play queue

	      -Q     prepend to	play queue

	      Supported	files are based	on the loaded input plugins.

	      Supported	URLs: Shoutcast	(http://...), CDDA (cdda://...).

	      Supported	playlist types:	plain, .m3u, .pls.

       bind [-f] <context> <key> <command>
	      Adds a key binding.

	      -f     overwrite existing	binding

	      Valid contexts: common (i.e. all views), library (1-2), playlist
	      (3), queue (4), browser (5), filters (6)

	      There's one context for each view. Common	is a special context
	      on which bound keys work in every	view.

	      You can override specific	keys in	common context for a view. For
	      example i	selects	the current track in views 1-3 but in browser
	      it is overridden to toggle showing of hidden files.

	      When setting custom bindings in $XDG_CONFIG_HOME/cmus/rc,	it is
	      recommended to use the -f	option,	or else	bind may fail due to
	      an existing binding in the autosave or system-level config

	      Hint: You	can press tab from command mode	to expand contexts,
	      keys, and	commands.

       browser-up (backspace)
	      Navigates	the browser view to the	parent directory (5). This
	      command only makes sense to be bound to the browser key context
	      although it's possible to	use this even if browser view is not

       cd [directory]
	      Changes the current working directory. Also changes the
	      directory	displayed in the browser view.

       clear [-l] [-p] [-q]
	      Removes all tracks from a	single view.

	      -l     clear library

	      -p     clear playlist

	      -q     clear play	queue

	      If a view	is not specified, the current view is used.

       colorscheme <name>
	      Changes the color	scheme.	Color schemes are found	in
	      /usr/local/share/cmus/ or	$XDG_CONFIG_HOME/cmus/ and have	the
	      extension	.theme.

       echo <arg>...
	      Displays the arguments on	the command line.

	      {} it is replaced	with file name of the first selected track.

       factivate <user-defined-filter>...
	      Selects and activates the	given user defined filters (displayed
	      in the filters view). Filter names are separated by spaces. This
	      command is mostly	useful when bound to a key to change active
	      filters quickly. If no arguments are provided, all filters are

	      Prefix a filter name with	! to negate it.

       filter <filter-expression>
	      Temporarily filters a library view. The filter is	not saved (use
	      fset and factivate for that).

       fset <name>=<filter-expression>
	      Defines or replaces an existing filter and adds it to the
	      filters view (6).

	      Shows information	about help files.

	      Inverts the marking of tracks in playlist	and queue views. See
	      mark and unmark.

       live-filter <simple-filter-expression|short-filter-expression>
	      Like filter, but uses simple filters and shows a preview as you
	      type. It persists	even after leaving command mode.

       load [-l] [-p] <playlist>
	      Loads a playlist to a view.

	      -l     load to library views

	      -p     load to playlist view

	      If a view	is not specified, the current view is used.

       lqueue [NUM]
	      Queues NUM (default 1) random albums from	the library. Also see

       mark <filter-expression>
	      Marks tracks in playlist and queue view using a filter

	      Toggles mute for the sound output.

       pl-create <name>
	      Creates a	new playlist.

       pl-export <filename>
	      Exports the currently selected playlist. The file	will be
	      overwritten if it	exists.

       pl-import [filename]
	      Imports a	playlist into the playlist view. The argument can be
	      omitted in the file browser view.

       pl-rename <name>
	      Renames the selected playlist.

       player-next (b)
	      Skips to the next	track.

       player-pause (c)
	      Toggles pause.

	      Pauses if	currently playing.

       player-play [filename] (x)
	      Plays the	given track, or, if none is specified, [re]plays the
	      current track from the beginning.

       player-prev (z)
	      Skips to the previous track.

       player-stop (v)
	      Stops playback.

	      Goes to the previously used view.

	      Goes to the to view to the left of current one (e.g. view	4 ->
	      view 3)

	      Goes to view to the right	of current one (e.g. view 3 -> view

       push [text]
	      Enters command mode with the command line	pre-set	to text.

		     bind common w push	filter artist=

	      Text can contain spaces, which will be used as-is	(e.g. trailing
	      spaces will be preserved). If no text is given, it defaults to a
	      blank command line.

	      This command can only be used from a keybinding.

	      Prints the current working directory.

       quit [-i] (q, :wq)
	      Exits cmus.

	      -i     ask before	exiting

	      Raises the virtual terminal emulator window. Only	works within a
	      X	session.

	      Randomizes (shuffles) the	tracks in the library, playlist	or
	      queue view.

       refresh (^L)
	      Redraws the terminal window.

       run <command>
	      Runs a command for the marked tracks OR the selected one if none

	      By default file names are	appended to the	command. If the
	      command contains {} it is	replaced with list of filenames.

	      Note: In view 1 you can run a command for	all files in the
	      selected album or	artist.

       save [-e]  [-l] [-L] [-p] [-q]  [file]  (:w)
	      Saves the	contents of a view to a	playlist file. In extended
	      mode (-e), also saves track metadata.

	      -l     save library views

	      -L     save filtered library views

	      -p     save playlist view

	      -q     save queue	view

	      If no view is specified, the current one is used.

	      If no filename given the old filename is used. "-" outputs to
	      stdout (works only remotely).

	      Enters backwards search mode. Cannot be used directly from
	      command mode.

	      See search-start.

       search-next (n)
	      If there is an active search, goes to the	next match in the
	      current view. See	SEARCHING above.

       search-prev (N)
	      If there is an active search, goes to the	previous match in the
	      current view. See	SEARCHING above.

	      Enters search mode. Cannot be used directly from command mode.

	      This is similar to live-filter, except it	is temporary and only
	      selects the current match	rather than filtering the entire view.

       seek [+-](<num>[mh] | [HH:]MM:SS)
	      Seeks to an absolute or relative position, which can be given in
	      seconds, minutes (m), hours (h) or HH:MM:SS format where HH: is

	      Seek 1 minute backward
		     :seek -1m

	      Seek 5 seconds forward
		     :seek +5

	      Seek to absolute position	1h
		     :seek 1h

	      Seek 90 seconds forward
		     :seek +1:30

       set <option>=<value>
	      Sets the value of	an option. See OPTIONS.

       set <option>
	      Display option value. Vim	compatible set <option>? is also

       shell <command>
	      Executes a command via /bin/sh -c.

       showbind	<context> <key>
	      Shows a key binding.

	      Reshuffles the shuffle lists for both library and	playlist

       source <filename>
	      Reads and	executes commands from <filename>.

       toggle <option>
	      Toggles the value	of a toggle-able option	(all booleans and
	      tristate aaa_mode).

       tqueue [NUM]
	      Queues NUM (default 1) random tracks from	the library. See also

       unbind [-f] <context> <key>
	      Removes a	key binding. Use tab to	cycle through bound keys.

		     Don't throw an error if the binding is not	known

	      Unmarks all tracks (see mark).

       update-cache [-f]
	      Updates the track	metadata cache ($XDG_CONFIG_HOME/cmus/cache).
	      By default, only deletions or files with a changed modification
	      time are updated.

		     Update all	files. Same as quit, rm	-f
		     $XDG_CONFIG_HOME/cmus/cache, start	cmus.

	      Prints the version information.

       view <name or 1-7>
	      Changes the active view.

       vol [+-]NUM[%] [[+-]NUM[%]]
	      Changes the volume.

	      If a single argument is provided,	both channels are changed.
	      Otherwise, the first/second values are for the left/right
	      channels respectively.

	      To increase or decrease volume prefix the	value with - or	+,
	      otherwise	value is treated as absolute volume.

	      Both absolute and	relative values	can be given as	percentage
	      units (suffixed with %) or as internal values (hardware may have
	      volume in	range 0-31 for example).

	      See quit.	Intended for use while in command mode.

       win-activate (enter)
	      In views,	1-3 plays the selected track. In view 5	starts,	the
	      selected file or changes to the selected directory. In view 6,
	      activates	the selected filters. In settings view (7), changes a
	      binding or variable.

       win-add-l [-n] (a)
	      Adds the currently marked	or selected track(s) (views 3-4), or
	      the currently selected file/directory (view 5), to the library.

	      Analogous	to :add	-l

		     Don't move	the selection to the next item.

       win-add-p [-n] (y)
	      Adds the currently marked	or selected track(s) (views 1-2, 4),
	      or the currently selected	file or	directory (view	5), to the
	      marked playlist.

	      Analogous	to :add	-p

		     Don't move	the selection to the next item.

       win-add-Q [-n] (E)
	      Prepends the currently marked or selected	track(s) (views	1-3),
	      or the currently selected	file or	directory (view	5), to the
	      play queue.

	      Analogous	to :add	-Q

		     Don't move	the selection to the next item.

       win-add-q [-n] (e)
	      Adds the currently marked	or selected track(s) (views 1-3), or
	      the currently selected file or directory (view 5), to the	play

	      Analogous	to :add	-q

		     Don't move	the selection to the next item.

       win-bottom (G, end)
	      Goes to bottom of	the current window.

       win-down	[NUM] (j, down)
	      Goes down	NUM (default 1)	rows in	the current window.

       win-half-page-down (^D)
	      Goes down	half a page in the current window.

       win-half-page-up	(^U)
	      Goes up half a page in the current window.

       win-mv-after (p)
	      Moves the	marked tracks below the	selected track.	If no tracks
	      are selected, selects the	previous track.	If no tracks are
	      marked, moves the	selected track up by one. This command works
	      in the playlist and queue	views.

       win-mv-before (P)
	      Moves the	marked tracks above the	selected track.	If no tracks
	      are selected, selects the	previous track.	If no tracks are
	      marked, moves the	selected track down by one. This command works
	      in the playlist and queue	views.

       win-next	(tab)
	      Activates	the next window	(i.e. tree/list). Only relevant	in
	      view 1.

	      Goes to the bottom of the	visible	part of	the current window.

       win-page-down (^F, page_down)
	      Goes to down one page in the current window.

	      Goes to the middle of the	visible	part of	the current window.

	      Goes to the top of the visible part of the current window.

       win-page-up (^B,	page_up)
	      Goes up one page in the current window.

       win-remove (D, delete)
	      Removes the selected entry. For tracks, no confirmation is
	      required.	For playlists (view 3),	files (view 5),	filters	(view
	      6) and bindings (view 7) user must confirm the action.

       win-scroll-down (^E)
	      Scrolls the current window one row downwards.

       win-scroll-up (^Y)
	      Scrolls the current window one row upwards.

       win-sel-cur (i)
	      Selects the current track	(position in library or	playlist, not
	      necessarily same as the currently	playing	track).	Works only in
	      views 1-3, does nothing in other views.

       win-toggle (space)
	      Expands albums in	library	view (1), marks	tracks in views	2-4,
	      sets the marked playlist in view 3, toggles selection of a
	      filter in	view 6,	or toggles a variable's	value in view 7.

       win-top (g, home)
	      Goes to top of the current window.

       win-up [NUM] (k,	up)
	      Goes up NUM (default 1) rows in the current window.

       win-update (u)
	      Checks the modification time of the files	in the library,	and
	      updates metadata for changed files. Removes non-existent files
	      from the library.

	      Reloads contents of directory in the browser view.

	      Only works in views 1-2 and 5, does nothing in other views.

       win-update-cache	[-f]
	      Same as update-cache, but	only for marked	/ selected tracks.
	      Only works in views 1-2, does nothing in other views.

	      See quit.	Intended for use from command mode.

       This section describes configuration options used by cmus.

       These options can be changed using the set and toggle commands. Default
       values are (parenthesized), and the possible values are in [brackets].

       auto_expand_albums_follow, auto_expand_albums_search,
       auto_expand_albums_selcur (true)
	      Always expand an artist and select the album when	following the
	      currently	played track or	performing actions such	as "search" or
	      "go to current track". This option is tightly coupled to the
	      show_all_tracks option. Any "auto_expand_albums_*	= false"
	      implies "show_all_tracks = true".

       auto_reshuffle (true)
	      Reshuffle	a playlist when	the end	of a shuffled list is reached.

       aaa_mode	(all) [all, artist, album]
	      Defines what tracks should be played in the library view.	Not
	      used in the other	views.

	      For example, if set to artist, the player	behaves	like there
	      were only	the files of the currently playing artist in the

       altformat_current [Format String]
	      Alternative format string	for the	line displaying	currently
	      playing track.

	      Note: If empty, format_current is	used instead.

       altformat_playlist [Format String]
	      Alternative format string	for the	list views (2-4).

	      Note: if empty, format_playlist is used instead.

       altformat_title [Format String]
	      Alternative format string	the for	terminal title.

	      Note: not	all terminals support changing window title.

	      Note: if empty, format_title is used instead.

       altformat_trackwin [Format String]
	      Alternative format string	for the	tree view's (1)	track window.

	      Note: if empty, format_trackwin is used instead.

       buffer_seconds (10) [1-300]
	      Size of the player buffer	in seconds.

       color_cmdline_bg	(default) [Color]
	      Command line background color.

       color_cmdline_fg	(default) [Color]
	      Command line foreground color.

       color_cmdline_attr (default) [Attributes]
	      Command line attributes.

       color_error (lightred) [Color]
	      Color of error messages displayed	on the command line.

       color_info (lightyellow)	[Color]
	      Color of informational messages displayed	on the command line.

       color_separator (blue) [Color]
	      Color of the separator line between windows in view (1).

       color_statusline_bg (gray) [Color]
	      Status line background color.

       color_statusline_fg (black) [Color]
	      Status line foreground color.

       color_statusline_attr (default) [Attributes]
	      Status line attributes.

       color_titleline_bg (blue) [Color]
	      Background color of the line displaying currently	playing	track.

       color_titleline_fg (white) [Color]
	      Foreground color of the line displaying currently	playing	track.

       color_titleline_attr (default) [Attributes]
	      Attributes of the	line displaying	currently playing track.

       color_win_bg (default) [Color]
	      Window background	color.

       color_win_cur (lightyellow) [Color]
	      Color of currently playing track.

       color_win_cur_attr (default) [Attributes]
	      Currently	playing	track attributes.

       color_win_cur_sel_bg (blue) [Color]
	      Background color of the selected row which is also the currently
	      playing track in active window.

       color_win_cur_sel_fg (lightyellow) [Color]
	      Foreground color of the selected row which is also the currently
	      playing track in active window.

       color_win_cur_sel_attr (default)	[Attributes]
	      Attributes of the	selected row which is also the currently
	      playing track in active window.

       color_win_dir (lightblue) [Color]
	      Color of directories in browser.

       color_win_fg (default) [Color]
	      Window foreground	color.

       color_win_attr (default)	[Attributes]
	      Window attributes.

       color_win_inactive_cur_sel_bg (gray) [Color]
	      Background color of the selected row which is also the currently
	      playing track in inactive	window.

       color_win_inactive_cur_sel_fg (lightyellow) [Color]
	      Foreground color of the selected row which is also the currently
	      playing track in inactive	window.

       color_win_inactive_cur_sel_attr (default) [Attributes]
	      Attributes of the	selected row which is also the currently
	      playing track in inactive	window.

       color_win_inactive_sel_bg (gray)	[Color]
	      Background color of selected row in inactive window.

       color_win_inactive_sel_fg (black) [Color]
	      Foreground color of selected row in inactive window.

       color_win_inactive_sel_attr (default) [Attributes]
	      Attributes of selected row in inactive window.

       color_win_sel_bg	(blue) [Color]
	      Background color of selected row in active window.

       color_win_sel_fg	(white)	[Color]
	      Foreground color of selected row in active window.

       color_win_sel_attr (default) [Attributes]
	      Attributes of selected row in active window.

       color_win_title_bg (blue) [Color]
	      Background color of window titles	(topmost line of the screen).

       color_win_title_fg (white) [Color]
	      Foreground color of window titles	(topmost line of the screen).

       color_win_title_attr (default) [Attributes]
	      Attributes of window titles (topmost line	of the screen).

       color_trackwin_album_bg (default) [Color]
	      Background color of the album row	shown in the track window.

       color_trackwin_album_fg (default) [Color]
	      Foreground color of the album row	shown in the track window.

       color_trackwin_album_attr (bold)	[Attributes]
	      Attributes of the	album row shown	in the track window.

       confirm_run (true)
	      Ask for confirmation before executing :run

       continue	(true)
	      Continue playing after current track finishes.

       continue_album (true)
	      Continue playing next album after	current	album finishes.

       device (/dev/cdrom)
	      CDDA device file.

       display_artist_sort_name	(false)
	      If enabled, always displays artist names used for	sorting
	      instead of regular ones in tree view (e.g. "Artist, The" instead
	      of "The Artist"),	so that	artists	column looks alphabetically

       follow (false)
	      If enabled, always select	the currently playing track on track

       format_current [Format String]
	      Format string for	the line displaying currently playing track.

       format_playlist [Format String]
	      Format string for	the list views (2-4).

       format_playlist_va [Format String]
	      Format string for	the list views (2-4), if a track is assumed to
	      be a part	of compilation (see LIBRARY VIEW SORTING for details).

	      Note: If empty, format_playlist is used instead.

       format_statusline [Format String]
	      Format string for	status line.

       format_title [Format String]
	      Format string for	terminal title.

	      Note: Not	all terminals support changing window title.

       format_trackwin [Format String]
	      Format string for	the tree view's	(1) track window.

       format_trackwin_album [Format String]
	      Format string for	albums in tree view's (1) track	window.

       format_trackwin_va [Format String]
	      Format string for	the tree view's	(1) track window, if a track
	      is assumed to be a part of compilation (see LIBRARY VIEW SORTING
	      for details).

	      Note: If empty, format_trackwin is used instead.

       format_treewin [Format String]
	      Format string for	the tree view's	(1) tree window.

       format_treewin_artist [Format String]
	      Format string for	artists	in tree	view's (1) tree	window.

       smart_artist_sort (true)
	      If enabled, makes	the tree view sorting ignore "The" in front of
	      artist names, preventing artists starting	with "The" from
	      clumping together. Real artistsort tags override this option, if

       id3_default_charset (ISO-8859-1)
	      Default character	set to use for ID3v1 and broken	ID3v2 tags.

	      Note: This is used only if the tag is not	valid UTF-8.

       icecast_default_charset (ISO-8859-1)
	      Default character	set to use for non-UTF-8 icecast stream

	      Note: This is used only if the metadata is not valid UTF-8.

       lib_add_filter [Filter]
	      Apply filter when	adding files to	the library. See FILTERS.

       lib_sort	(artist	album discnumber tracknumber title filename) [Sort
	      Sort keys	for the	sorted library view (2).

       mouse (false)
	      Enable mouse support.

	      Note: Mouse wheel	scrolling can lag if cmus is compiled with old
	      version of ncurses.

       mpris (true)
	      Enable MPRIS support. See	D-Bus Interface	(MPRIS)

	      Note: This flag has no effect if cmus was	compiled without MPRIS

       output_plugin [roar, pulse, alsa, arts, oss, sndio, sun,	coreaudio]
	      Name of output plugin.

       pl_sort () [Sort	Keys]
	      Sort keys	for the	playlist view (3). Empty value disables
	      sorting and enables manually moving tracks.

       play_library (true)
	      Play tracks from the library instead of playlist.

       play_sorted (false)
	      Play tracks from the library in the sorted view (2) order
	      instead of tree view (1) order. Used only	when play_library is

       repeat (false)
	      Repeat after all tracks played.

       repeat_current (false)
	      Repeat current track forever.

       replaygain (disabled) [track, album, track-preferred, album-preferred]
	      Enable Replay Gain.

       replaygain_limit	(true)
	      Use replay gain limiting when clipping.

       replaygain_preamp (0.0)
	      Replay gain preamplification in decibels.

       resume (false)
	      Resume playback on startup.

       rewind_offset (5) [-1-9999]
	      If the position of the current track is smaller than
	      rewind_offset, player_prev jumps to the previous track.
	      Otherwise, player_prev jumps to the beginning of the current
	      track. If	rewind_offset=-1, player_prev always jumps to the
	      previous track.

       scroll_offset (2) [0-9999]
	      Minimal number of	screen lines to	keep above and below the

       show_all_tracks (true)
	      Display all tracks of the	artist when the	artist is selected in
	      the tree view. This option is tightly coupled to the
	      auto_expand_albums_\ options. "show_all_tracks = false" implies
	      "auto_expand_albums_* = true".

       show_hidden (false)
	      Display hidden files in browser.

       show_current_bitrate (false)
	      Display current bitrate in the status lines.

       show_playback_position (true)
	      Display elapsed (or remaining) time in the status	line. Can be
	      disabled to e.g. not trigger tmux's activity monitor.

       show_remaining_time (false)
	      Display remaining	time instead of	elapsed	time.

       shuffle (false)
	      Play in shuffled order. Shuffle works in the library views (1-2)
	      and playlist view	(3).

       skip_track_info (false)
	      Don't load metadata when adding tracks. Useful when using
	      network file system and having huge amount of files. Tags	can be
	      loaded using 'update-cache' or 'win-update-cache'	commands.

       softvol (false)
	      Use software volume control.

	      Note: You	should probably	set this to false when using ao	as
	      output_plugin to output to wav files.

       softvol_state (100 100)
	      Used to save left	and right channel values for software volume
	      control. Two integers in range 0..100 separated by a space. This
	      option is	not usually changed directly since vol command does
	      same thing if softvol is true.

       start_view (tree) [tree,	sorted,	playlist, queue, browser, filters,
	      Specify the view that gets shown when cmus starts.

       status_display_program () [command]
	      This command, if set, is run for every status change. It can be
	      used to display currently	playing	track on desktop background or
	      panel for	example. See

       stop_after_queue	(false)
	      Stop playback when end of	play queue is reached.

       time_show_leading_zero (true)
	      Pad durations of less than 10 minutes with a leading 0.

       tree_width_percent (33) [1-100]
	      Percentage of the	window width to	use for	left pane.

       tree_width_max (0) [0-9999]
	      Restrict the size	calculated from	tree_width_percent. 0 disables
	      this option.

	      This affects the tree in the library view	and the	playlist list
	      in the playlist view.

	      Note that	this value will	be further constrained by the window
	      width and/or the minimum tree size.

	      For example, to set a fixed size of 60 columns:

		     set tree_width_percent=100
		     set tree_width_max=60

	      Or, to be	33% wide, but at most 60 columns

		     set tree_width_percent=33
		     set tree_width_max=60

	      Or, to always be 33% wide	where possible (the default behavior):

		     set tree_width_percent=33
		     set tree_width_max=0

       wrap_search (true)
	      Controls whether the search wraps	around the end.

       Color is	an integer in range -1..255.

       The following color names are recognized:

       Terminal's default color, -1

       Fg & bg,	0..7
	      black, red, green, yellow, blue, magenta,	cyan, gray

       Fg, 8..15
	      darkgray,	lightred, lightgreen, lightyellow, lightblue,
	      lightmagenta, lightcyan, white

       Attributes is a set of names "standout|bold":

       default does nothing, if	you put	it with	other attributes the other
       attributes will be used.

       standout	makes the text standout.

       bold makes the text bold.

       reverse reverses	the text colors.

       underline underlines the	text.

       blink makes the text blink.

   Format Strings
       Format strings control display of tracks	in library, playlist and play
       queue views.

       Note: altformat_* options are used when there are no tags available.

       Special Keys:

	      %a  %{artist}
	      %A  %{albumartist}
	      %l  %{album}
	      %D  %{discnumber}
	      %n  %{tracknumber}
	      %X  %{play_count}
	      %t  %{title}
	      %g  %{genre}
	      %c  %{comment}
	      %y  %{date}
	      %d  %{duration}
	      %f  %{path}
	      %F  %{filename}
		     start align right (use at most once)
		     literal %
		     literal ?

       You can use printf style	formatting (width, alignment, padding).	As an
       extension, the width can	have a %-suffix, to specify a percentage of
       the terminal width.
       To see current value of an option type :set option=<TAB>.

       Note: With %{bitrate}, you'll have to append the	unit yourself, as
       mentioned in the	example	below.

       You can use conditional operator	%{?CONDITION?A[?B]}. CONDITION has the
       same syntax as filters, except for unsupported short and	simple
       expressions and supported keys comparison (e.g. artist=albumartist).
       Its keys	are:
	      format strings' special keys
	      configuration options
	      keyword stream [boolean] (returns	true if	track is a stream)
	      keyword va [boolean] (returns true if track's album is
       Else part can be	skipped. A and B can contain string literals in	" or
       '. A and	B can be empty.


	      :set format_trackwin= %02n. %t %{?y?(%y)}%= %d
	      :set format_current= %n. %-30t %40F (%y)%= %d
	      :set format_current= %a -	%l - %02n. %t%=	%{bitrate}Kbps %g %y
	      :set format_playlist= %f%= %6{rg_track_gain} dB  %8{rg_track_peak}
	      :set format_playlist= %-25%a %-15%l %3n. %t%= %y %d

   Sort	Keys
       Sort option (lib_sort, pl_sort) value is	space separated	list of	the
       following sort keys:

	      artist, album, title, tracknumber, play_count, discnumber, date,
	      originaldate, genre, comment, albumartist, filename, filemtime,
	      bpm, bitrate, codec, media, codec_profile, rg_track_gain,
	      rg_track_peak, rg_album_gain, rg_album_peak

       Note: Adding a '-' in front of the key will reverse the sort order.

	      PCM device for ALSA plugin, usually "default".
	      Mixer channel for	ALSA Plugin, usually "pcm", "master" or
	      "headphone". To see all possible values run "alsamixer" or

	      Mixer device for ALSA plugin, usually "default".

	      Restore the volume at startup using PulseAudio. Otherwise, cmus
	      sets the volume to 100%, which does not mix well with "flat
	      volumes" feature of PA. Defaults to "1"; set to "0" to turn off.
	      The audio	buffer size; defaults to 16kB, but you may want	to try
	      bigger values if you experience buffer under-runs.
	      Device interface for libao plugin	to request a specific playback
	      device/sink/output. This name will be in a format	determined by
	      the specific driver backend.
	      Output driver for	libao plugin. Example values: "alsa09",	"esd",
	      "irix", "oss", "sun", "aixs", "wav".

	      Note: of the file	output drivers only "wav" is supported.
	      Counter used for making filename.	Used only if is
	      "wav". For example if this is 1 and is
	      "/home/user" then	PCM data is outputted to "/home/user/01.wav".
	      This counter is incremented every	time playback is stopped.

	      Note: You	probably want to set continue to false (press C),
	      otherwise	playback is not	stopped	between	tracks and all PCM
	      data is outputted	to one wav file	(useful	if you want to join
	      files).c Also unsetting shuffle and repeat might be good idea.
	      Output directory for libao plugin; default to the	home
	      directory. Used only if is "wav".

	      Device for Core Audio output. Leave empty	for default.

	      Set hog mode for the device. The default value is	false.

	      Synchronize the device sample rate with the player, so no
	      interpolation will be applied to the stream.

	      Connect to jackd with this name. Leave empty for default.

	      The re-sampling quality. 0 is low	quality	but fast, 1 is medium
	      quality, 2 (default) is high quality but more CPU	intensive.
	      This option is only available if cmus was	compiled with
	      libsamplerate support.

	      CDDB URL (default: Uses HTTP if
	      prefixed with "http://" (e.g.:	Set to an
	      empty string to disable CDDB lookup completely.

	      Sets the priority	of the input plugin. If	multiple plugins can
	      play a file, the plugin with the higher priority is chosen. If
	      the priority is 0, the plugin is disabled.

	      PCM device for OSS plugin, usually /dev/dsp.
	      Mixer channel for	OSS Plugin, "pcm" or "master".

	      Mixer device for OSS plugin, usually /dev/mixer.

	      Address of RoarAudio server. Defaults to internal	defaults. Can
	      be UNIX, TCP/IP or DECnet	address.

       dsp.roar.role [music, background_music, ...]
	      Role for stream. May be used by the server to apply additional

	      PCM device for Sun plugin, usually /dev/audio.
	      Mixer channel for	Sun Plugin, usually "master".

	      Mixer device for Sun plugin, usually /dev/mixer.

       If the cdio input plugin	is enabled, CDs	and CD images can be played by
       setting the device option to a device file (e.g.	/dev/cdrom) or an
       image file (e.g.	~/cd.cue). Then, add a new track using the CDDA	URL

	      :add cdda://2

       To add the entire disc, use cdda:// (without track number). This	only
       works for audio discs, not images. Adding track ranges is also possible

       To add images without changing the device option, include the image
       path in the URL:

	      :add cdda:///path/to/cd.cue/2-5

       The metadata will be read from CD-Text, and if not available, looked up
       from a CDDB server (see input.cdio.cddb_url).

       Filters are used	mostly for filtering contents of library views (1 &
       2). Filters do not change the actual library content, i.e. the :save
       command will still save all tracks to playlist file whether they	are
       visible or not.

       There are three types of	filter expressions, each offering more

	      simple e.g. beatles

	      short  e.g. ~a beatles (!~y1960-1965 | ~d>600)

	      long   e.g. artist="*beatles*"&album="R*"

       Simple expressions are only available using live-filter.	For other
       filter commands the type	is auto-detected, so both short	and long
       expressions can be used.

       Long expressions	are lists of built-in filters or user defined filters
       separated with &	(and) or | (or). Parenthesises can be used group
       subexpressions and ! negates result of the expression following it. The
       same is true for	short expressions, but they can	only consist of
       built-in	filters. Also, (and)-grouping is done implicitly.

       long   filename,	artist,	albumartist, album, title, genre, comment,
	      codec, codec_profile, media
	      Comparators: = and != (not equal)

       short  ~f, ~a, ~A, ~l, ~t, ~g, ~c
	      Comparators: none

       long   discnumber, tracknumber, date (year), originaldate (year),
	      duration (seconds), bitrate
	      Comparators: <, <=, =, >=, >, !=

       short  ~D, ~n, ~y, ~d
	      Comparators: <, >
	      Ranges: a-b (>=a&<=b), -b	(<=b), a- (>=a)

       tag (true if track has tags), stream (true if track is a	stream)
       For short expressions: ~T and ~s

   Defining Filters
       Filters can be defined with the fset command. User defined filters
       appear in the filters view (6).

       Create a	new filter which name is ogg and value filename="*.ogg"
	      :fset ogg=filename="*.ogg"

       Filter ogg and mp3 files	from the 90s. Note the use of user defined
       filter ogg.
	      :fset 90s-ogg-mp3=date>=1990&date<2000&(ogg|filename="*.mp3")

   Activating Filters
       factivate changes the visible contents of the library (views 1-2).

       Activate	user defined filters ogg and missing-tags
	      :factivate ogg missing-tags

       Like above but negate value of ogg filter.
	      :factivate !ogg missing-tags

       Alternatively, you can filters by pressing space	in view	6, then
       activate	them by	pressing enter.

   Throw-away Filters
       The live-filter and filter commands are useful when you want to use a
       filter without saving it. It changes the	visible	contents of the
       library (views 1-2). filter unactivates all filters in the filters
       view, while live-filter is applied in addition to all currently
       activated filters. It persists even after leaving command mode.

       Filter all rock (anything with rock in genre tag) music from 80s-
	      :filter date>=1980&genre="*rock*"
	      :filter ~y1980-~grock

       Filter all artists/albums/titles	containing "sleepwalking"
	      :live-filter sleepwalking

   Selecting Tracks Matching a Filter
       Mark (select) all tracks	with duration less than	2 minutes
	      :mark duration<120

       Mark (select) all tracks	which have been	played at least	once
	      :mark play_count>=1

       These commands work in views 2-4.

       cmus reads its configuration from 3 different places in the following

	      This file	is automatically created and overwritten by cmus on
	      exit, so it should not be	modified by hand.

	      This file	contains the default configuration.

	      If the autosave file did exist, this file	is read	instead.

	      This file	is the static configuration file.

	      This file	is read	immediately after the autosave file, and is
	      never modified by	cmus. You can override auto-saved settings in
	      this file. This file is not limited to options; it can contain
	      other commands too.

   Color Schemes
       Color schemes (*.theme) are located in /usr/local/share/cmus or
       $XDG_CONFIG_HOME/cmus. You can switch them using	the :colorscheme
       command with the	basename of the	theme file.

       Note: Colors are	not automatically updated when the theme file changes
       since they are saved in the autosave file.

       Example status display scripts (see status_display_program) can be
       found in	/usr/local/share/examples/cmus.

	      Override the character set used by cmus (default:	`locale

	      Override the config directory (default: $XDG_CONFIG_HOME/cmus).

	      Override the socket path (default:

	      Full path	of the user's home directory.

	      URI of the proxy to use for HTTP requests.

	      Name of the user running cmus.

	      Fallback for USER.

D-Bus Interface	(MPRIS)
       cmus provides a D-Bus interface following the Media Player Remote
       Interfacing Specification (MPRIS) v2:

       It exposes the /org/mpris/MediaPlayer2 object path with the interfaces
       org.mpris.MediaPlayer2 and org.mpris.MediaPlayer2.Player. The unique
       bus name	is org.mpris.MediaPlayer2.cmus.

       Metadata	fields follow the naming convention of the specification:
       Additionally, the cmus:stream_title field is exposed if appropriate.

       The file	exists only if you configured cmus with	the maximum debug
       level (./configure DEBUG=2).

       After a crash, the last lines of	~/cmus-debug.txt may contain useful

       Feature requests	and bug	reports	should go to the GitHub	issue tracker:

       cmus-tutorial(7), cmus-remote(1)

       cmus was	mainly written by Timo Hirvonen	<>. Other
       contributors are	listed in the AUTHORS file.

       This man	page was written by Frank Terbeck <>,
       Timo Hirvonen <>, Clay	Barnes
       <>,	and Patrick Gaskin <>.

cmus				  31/01/2010			       CMUS(1)


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

home | help