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

FreeBSD Manual Pages

  
 
  

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

NAME
       cmus - C* Music Player

SYNOPSIS
       cmus [options]

DESCRIPTION
       cmus is a small ncurses based music player.  It supports	various	output
       methods by output-plugins. cmus has completely configurable keybindings
       and can be controlled from the outside via cmus-remote(1).

OPTIONS
       --listen	ADDR
	      Listen to	ADDR (UNIX socket) instead of $CMUS_SOCKET or
	      $XDG_RUNTIME_DIR/cmus-socket. ADDR is either a UNIX socket or
	      host[:port].

	      WARNING: Using host[:port] is insecure even with password! It
	      might be useful though in	LAN if you want	multiple local users
	      to able to control cmus.	Never make cmus	listen to the
	      internet.

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

       --plugins
	      List available plugins and exit.

       --show-cursor
	      Keep cursor always visible.  This	is useful for screen readers.

       --help
	      Display usage information	and exit.

       --version
	      Display version information and exit.

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

       Library view (1)
	      Display all tracks in so-called library. Tracks are sorted
	      artist/album tree.  Artist sorting is done alphabetically.
	      Albums are sorted	by year.

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

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

       Play Queue view (4)
	      Displays queue of	tracks which are played	next. These tracks are
	      played before anything else (i.e.	the playlist or	library).

       Browser (5)
	      Directory	browser.  In this view,	music can be added to either
	      the library, marked playlist or queue from the filesystem.

       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.

COMMAND	LINE
       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 or	to cancel press	ESC or CTRL-C.	Use
       up/down arrows to browse	command	history.  Use TAB to complete commands
       and parameters, you can tab complete almost anything.  You don't	need
       to type full command names if the command is unambiguous	(no other
       commands	starting with the same characters).

       Examples:

	      #	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
	      :player-play

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

SEARCHING
       Search mode works like the command mode,	to enter search	mode press /
       and then	type the search	words and press	ENTER.	Press n	to search next
       or N to search previous match using the same search words.  Type	? to
       search backwards.

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

       Searching works in views	5-7 too	and its	logic should be	pretty
       obvious.

PLAYLIST EDITING
   Selecting Tracks
       Editing commands	affect the currently marked tracks or if there are no
       marked tracks the currently selected track (or selected artist/album in
       view 1).

       Mark selected track by pressing 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 from 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 you	can move tracks	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 then the selected	track
       is moved	down (p) or up (P).

       NOTE: Changing active filters reloads view 2 so it isn't	a good idea to
       manually	order tracks in	the view.

   Removing Tracks
       Press D or delete to remove 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 (will ask for
       confirmation).

STATUS LINE
       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 displayed	only if	play_library
       is true because these are meaningless when playing the playlists	(view
       3).

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

       See CONFIGURATION OPTIONS section for more information about these
       options.

KEYBINDINGS
       Here's list of default keybindings.  See	unbind and bind	commands in
       the COMMANDS section.

   Common Context
       q			   quit	-i
       ^C			   echo	Type :quit<enter> to exit cmus.
       I			   echo	{}
       b			   player-next
       c			   player-pause
       x			   player-play
       z			   player-prev
       v			   player-stop
       ^L			   refresh
       n			   search-next
       N			   search-prev
       .			   seek	+1m
       l, right			   seek	+5
       ,			   seek	-1m
       h, left			   seek	-5
       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			   push	filter<space>
       L			   push	live-filter<space>
       u			   update-cache
       1			   view	tree
       2			   view	sorted
       3			   view	playlist
       4			   view	queue
       5			   view	browser
       6			   view	filters
       7			   view	settings
       !			   push	shell<space>
       ]			   vol +0 +1
       [			   vol +1 +0
       +, =			   vol +10%
       }			   vol -0 -1
       {			   vol -1 -0
       -			   vol -10%
       enter, mlb_click_selected   win-activate
       E			   win-add-Q
       a			   win-add-l
       y			   win-add-p
       e			   win-add-q
       G, end			   win-bottom
       down, j,	mouse_scroll_down  win-down
       p			   win-mv-after
       P			   win-mv-before
       tab			   win-next
       ^F, page_down		   win-page-down
       ^B, page_up		   win-page-up
       ^E			   win-scroll-down
       ^Y			   win-scroll-up
       D, delete		   win-remove
       i			   win-sel-cur
       space			   win-toggle
       g, home			   win-top
       k, up, mouse_scroll_up	   win-up

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

LIBRARY	VIEW SORTING
       The library view	(the tree-like one; not	the sorted library view, for
       which the sorting is controlled by the user by setting lib_sort - see
       CONFIGURATION OPTIONS), is sorted automatically by cmus using the
       information found in the	tagging	information provided by	the audio
       files.

       Generally, in the library view cmus uses	three levels of	sorting: the
       first level would be the	artist name, the second	one the	album and
       finally the actual track.

       At first, cmus checks if	the "filename" looks like an URL, if it	does,
       the item	is given the special artist and	album name <Stream>.

       If it is	a file,	it is checked if the artist and	album tags are set. If
       not, cmus assigns the special name <No Name> for	the unset tag.

       As the first level, cmus	sorts alphanumerically by the value of the
       artist tag. (<Stream> and <No Name> will	be used	as if they where
       normal names.) If a special sorting tag is available, it's value	will
       be used instead.

       For album names,	alphanumerical sorting is not the primary method,
       though. To decide, how the second level should be sorted, cmus looks at
       the date	of the first track of each album. Sorting is done from young
       to old. Of course, if one artist	happens	to have	more then one album
       from one	year, alphanumerical sorting will be used after	sorting	by
       date.

       If the date header is not set, the album	will be	placed on top of the
       list (in	fact, the internal integer value for unset album tags is -1).

       The method for third sorting level (the track) is very similar to album
       sorting.	First two numerical values are checked (discnumber and
       tracknumber). If	sorting	is still ambiguous, sorting will be done
       alphanumerically	by the value of	the track's filename (not track
       name!).

       For simple albums, that is it. There is a special case, though. Albums,
       that feature various artists, also known	as samplers or compilations.

       If a track belongs to a compilation is again decided by the existence
       and value of special tagging information. First,	it is checked if cmus
       should use a special artist name	(e.g.: 'Fatboy Slim' for a DJ set). If
       so, that	one will be used instead of the	real artist name.

       If that special name tag	is not set, cmus checks	if another tag is set.
       If that is the case, the	album will be given the	special	artist name
       <Various	Artists>. Albums filed under <Various Artists> are sorted
       alphanumerically	by album name instead of by date.

       That way, you do	not end	up with	compilation tracks scattered around
       your library view.

       The problem with	compilation tagging is,	that there is no generic tag
       or method, that can be regarded as a standard across all	different
       formats,	supported by cmus.

       For mp3,	the special-name tag would be the id3v2	TPE2 frame. The
       mark-as-compilation tag is the TCMP frame (which	is a user defined
       id3v2.3 frame, used at least by amarok and apple's iTunes[tm]).

       For vorbis style	tags (for example in ogg vorbis	and flac files), the
       special-name tag	is ALBUMARTIST and the mark-as-compilation tag is
       COMPILATION. Vorbis tags	names are case insensitive.

COMMANDS
       This section describes cmus' commands.  You can bind a key to any of
       these commands, put these commands to configuration files and execute
       them in command mode.  Also cmus-remote uses these commands in its
       protocol.

       Optional	parameters are in brackets, obligatory parameters in angle
       brackets	and default key	bindings in parenthesis.

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

	      -l     add to library

	      -p     add to playlist

	      -q     add play queue

	      -Q     prepend to	play queue

	      URL is a Shoutcast stream	(http://...) or	a CDDA URL
	      (cdda://...) (see	PLAYING	AUDIO DISCS).

	      Supported	playlist: plain, .m3u, .pls.

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

	      -f     overwrite existing	binding

	      Use tab to expand	contexts, keys and commands.  Command is any
	      command listed in	this section.

	      Valid key	contexts
		     common, 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.

       browser-up (backspace)
	      Change to	parent directory in browser view (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 active.

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

       clear [-l] [-p] [-q]
	      Remove all tracks	from the specified view	or the current view.

	      -l     clear library

	      -p     clear playlist

	      -q     clear play	queue

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

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

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

	      NOTE: unlike with	run the	{} is replaced with only the first
	      selected filename.

	      Default bindings:

		     common  I	 echo {}
		     common  ^C	 echo Type :quit<enter>	to exit	cmus.

       factivate <user-defined-filter>...
	      Select and activate 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 very quickly.  If	no arguments given then	all filters
	      are unactivated.

	      If you prefix a filter name with "!" then	the filter value is
	      negated before activation.

       filter <filter-expression>
	      Use this command when you	want to	temporarily filter contents of
	      the library views	without	having separately define (fset)	and
	      activate the filter.  The	filter is not saved.

       fset <name>=<filter-expression>
	      Define (or replace existing) filter and add it to	filters	view
	      (6).

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

       live-filter <simple-filter-expression|short-filter-expression>
	      Use this command when you	want to	temporarily filter contents of
	      the library views	without	having separately define (fset)	and
	      activate the filter.  The	filter is not saved.

       load [-l] [-p] <playlist>
	      Load a playlist to the specified view or to the current view.

	      -l     load to library views

	      -p     load to playlist view

       lqueue [NUM]
	      Queue NUM	(default 1) random albums from the library. See	also
	      tqueue.

       mark <filter-expression>
	      Mark tracks in playlist and queue	view by	using a	filter
	      expression.

       pl-create <name>
	      Creates a	new playlist.

       pl-export <filename>
	      Exports the currently selected playlist.

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

       pl-rename <name>
	      Renames the selected playlist.

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

       player-pause (c)
	      Toggle pause.

       player-pause-playback
	      Pause if currently playing.

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

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

       player-stop (v)
	      Stop playback.

       prev-view
	      Go to previously used view.

       left-view
	      Go to view "to the left" of current one, e.g. view 4 -> view 3.

       right-view
	      Go to view "to the right"	of current one,	e.g. view 3 -> view 4.

       push <text>
	      Enter command mode with the command line pre-set to text.
	      Example:

		     bind common w push	filter artist=

	      Text can contain spaces and even trailing	spaces will be
	      honored. This command can	only be	bound to a key but not used in
	      the command line directly.

       pwd
	      Prints the current working directory.

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

	      -i     ask before	exiting

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

       refresh (^L)
	      Redraw the terminal window.

       run <command>
	      Run command for the marked tracks	OR the selected	one if none
	      marked.

	      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)
	      Save the specified view's	or the current view's contents to a
	      playlist file. In	extended mode (-e), also save metadata.

	      -l     save library views

	      -L     save filtered library views

	      -p     save playlist view

	      -q     save queue	view

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

       search-next (n)
	      If a search pattern has been entered before, search forward for
	      the next match in	the current view.  See SEARCHING above.

       search-prev (N)
	      If a search pattern has been entered before, search backwards
	      for the previous match in	the current view.  See SEARCHING
	      above.

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

	      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

	      Default bindings:

		     common  ,	    :seek -1m
		     common  .	    :seek +1m
		     common  l	    :seek +5
		     common  h	    :seek -5
		     common  right  :seek +5
		     common  left   :seek -5

       set <option>=<value>
	      Set value	of an option. See OPTIONS.

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

       shell <command>
	      Execute a	command	via /bin/sh.

       showbind	<context> <key>
	      Show key binding.

       shuffle
	      Reshuffle	the shuffle lists for both library and playlist	views.

       source <filename>
	      Read and execute commands	from <filename>.

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

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

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

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

       unmark
	      Unmark all tracks	(see mark).

       update-cache [-f]
	      Update track metadata cache ($XDG_CONFIG_HOME/cmus/cache). Only
	      files with changed modification time or removed files are
	      considered.

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

       view <name or 1-7>
	      Switches active view.

       vol [+-]NUM[%] [[+-]NUM[%]]
	      Set, increase or decrease	volume.

	      If you give vol just one argument	it changes both	channels.  Two
	      values make it possible to change	the left and right channel
	      independently.

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

	      Default bindings:

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

       win-activate (enter)
	      In views 1-3 start playing the selected track.  In view 5	start
	      playing the selected track or change to the selected directory.
	      In view 6	activate the selected filters.	In settings view (7)
	      change binding or	variable.

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

	      Analogous	to :add	-l

       win-add-p (y)
	      Add 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

       win-add-Q (E)
	      Prepend 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

       win-add-q (e)
	      Add 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

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

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

       win-half-page-down
	      Goto down	half a page in the current window.

       win-half-page-up
	      Goto up half a page in the current window.

       win-mv-after (p)
	      If no tracks are marked, move the	selected track down one	row.
	      If any tracks are	marked,	move the marked	tracks after the
	      currently	selected track.	 This command works in unsorted
	      playlist and play	queue view.

       win-mv-before (P)
	      If no tracks are marked, move the	selected track up one row. If
	      any tracks are marked, move the marked tracks before the
	      currently	selected track.	 This command works in unsorted
	      playlist and play	queue view.

       win-next	(tab)
	      Activate next window.  Only relevant in view 1.

       win-page-bottom
	      Goto the bottom of the visible part of the current window.

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

       win-page-middle
	      Goto the middle of the visible part of the current window.

       win-page-top
	      Goto the top of the visible part of the current window.

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

       win-remove (D, delete)
	      Remove the selected entry.  For tracks no	confirmations are
	      made.  For playlists (view 3), files (view 5), filters (view 6)
	      and bindings (view 7) user has to	confirm	the action.

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

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

       win-sel-cur (i)
	      Select 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)
	      Expand albums in library view (1), mark tracks in	views 2-4, set
	      the marked playlist in view 3, toggle selection of a filter in
	      view 6, toggle variable value in view 7.

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

       win-up [NUM] (k,	up)
	      Goto 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.

CONFIGURATION OPTIONS
       This section describes cmus' options that can be	altered	with the set
       and toggle commands. Default values are in parenthesis, possible	values
       in brackets.

       auto_expand_albums_follow, auto_expand_albums_search,
       auto_expand_albums_selcur (true)
	      If enabled, cmus will always open	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	playlist when end of shuffle 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 library.

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

       confirm_run (true)
	      Ask for confirmation before executing :run

       continue	(true)
	      Continue playing after current track 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
	      sorted.

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

       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	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
	      present.

       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
	      metadata.

	      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
       Keys]
	      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.

	      NOTE: This flag has no effect if cmus was	compiled without MPRIS
	      support.

       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
	      true.

       repeat (false)
	      Repeat after all tracks played.

       repeat_current (false)
	      Repeat current track forever.

       replaygain (disabled)
	      Enable Replay Gain. Default is "disabled". Set to	"track",
	      "album", "track-preferred" or "album-preferred".

       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
	      cursor.

       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.

       status_display_program () [command]
	      This command, if not empty, is run every time cmus' status
	      changes. It can be used to display currently playing track on
	      desktop background or panel for example.	See
	      /usr/local/share/examples/cmus/cmus-status-display.

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

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

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

       The following color names are recognized:

       Terminal's default color, -1
	      default

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

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

   Attributes
       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}
		  %{originaldate}
		  %{maxdate}
		  %{bpm}
		  %{bitrate}
		  %{codec}
		  %{codec_profile}
		  %{rg_track_gain}
		  %{rg_track_peak}
		  %{rg_album_gain}
		  %{rg_album_peak}
		  %{arranger}
		  %{composer}
		  %{conductor}
		  %{lyricist}
		  %{performer}
		  %{remixer}
		  %{label}
		  %{publisher}
		  %{work}
		  %{opus}
		  %{partnumber}
		  %{part}
		  %{subtitle}
		  %{media}
	      %=
		     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
	      compilation)
       Else part can be	skipped. A and B can contain string literals in	" or
       '. A and	B can be empty.

       Examples:

	      :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 sort	in reverse order

PLUGIN OPTIONS
       dsp.alsa.device
	      PCM device for ALSA plugin, usually "default".

       mixer.alsa.channel
	      Mixer channel for	ALSA Plugin, usually "pcm", "master" or
	      "headphone". To see all possible values run "alsamixer" or
	      "amixer".

       mixer.alsa.device
	      Mixer device for ALSA plugin, usually "default".

       mixer.pulse.restore_volume
	      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.

       dsp.ao.buffer_size
	      Buffer size, default is 16kB (but	you may	want to	try bigger
	      values if	you experience buffer under-runs).

       dsp.ao.device_interface
	      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.

       dsp.ao.driver
	      Output driver for	libao plugin.  Example values: "alsa09",
	      "esd", "irix", "oss", "sun", "aixs", "wav".

	      NOTE: of the file	output drivers only "wav" is supported.

       dsp.ao.wav_counter
	      Counter used for making filename.	 Used only if dsp.ao.driver is
	      "wav".  For example if this is 1 and dsp.ao.wav_dir 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).  Also unsetting shuffle and repeat might be good idea.

       dsp.ao.wav_dir
	      Output directory for libao plugin, default is your home
	      directory. Used only if dsp.ao.driver is "wav".

       dsp.coreaudio.device
	      Device for Core Audio output. Leave empty	for default.

       dsp.coreaudio.enable_hog_mode
	      Set true to set the device to hog	mode. The default value	is
	      false.

       dsp.coreaudio.sync_sample_rate
	      Synchonize the device sample rate	with the player, so no
	      interpolation will be applied to the stream.

       dsp.jack.server_name
	      Connect to jackd with this name. Leave empty for default.

       dsp.jack.resampling_quality
	      Sets the quality of the re-sampling. 0 is	low quality but	fast,
	      1	is medium quality, 2 (default) is high quality but more	CPU
	      intensiv.	This option is only available if cmus was compiled
	      with libsamplerate support.

       input.cdio.cddb_url
	      CDDB URL (default: freedb.freedb.org:8880). Use HTTP protocol if
	      prefixed with "http://" (e.g.:
	      http://freedb.musicbrainz.org:80/~cddb/cddb.cgi).	Set to an
	      empty string to disable CDDB lookup completely.

       input.*.priority
	      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.

       dsp.oss.device
	      PCM device for OSS plugin, usually /dev/dsp.

       mixer.oss.channel
	      Mixer channel for	OSS Plugin, "pcm" or "master".

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

       dsp.roar.server
	      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
	      defaults.

       dsp.sun.device
	      PCM device for Sun plugin, usually /dev/audio.

       mixer.sun.channel
	      Mixer channel for	Sun Plugin, usually "master".

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

PLAYING	AUDIO DISCS
       With the	cdio input plugin enabled, it is possible to play Audio	CDs
       and CD images. Just set the device option to either a device file (e.g.
       /dev/cdrom) or an image file (e.g. ~/cd.cue). Then add a	new track
       using the CDDA URL scheme, e.g.:

	      :add cdda://2

       To add the whole	disc, use cdda:// (without track number). This is
       currently only working for audio	discs, not images. Adding track	ranges
       is also possible	(cdda://1-3). To add images without changing the
       device option, it is possible to	include	the image path in the URL,
       e.g.:

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

   Types
       There are three types of	filter expressions, each offering more
       expressiveness:

	      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).  Parenthesis can be used group
       subexpressions and ! negates result of the expression following it.
       Same is true for	short expressions, but they can	only be	made of
       built-in	filters. Also (and)-grouping is	done implicitly.

   Strings
       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

   Integers
       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)

   Booleans
       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 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 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 select the	filters	by pressing space in view 6
       and then	activate the selected filters by pressing enter.

   Throw-away Filters
       live-filter and filter commands are useful when you want	to use a
       filter only once	and not	save it.  It changes 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.

       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.

FILES
       cmus reads its configuration from 3 different places.

       $XDG_CONFIG_HOME/cmus/autosave
	      This is the first	file cmus loads.  cmus saves its state on exit
	      to this file so you shouldn't edit it.

       /usr/local/share/cmus/rc
	      If the autosave file didn't exist, this file is read instead.

       $XDG_CONFIG_HOME/cmus/rc
	      Static config 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
       There are some color schemes (*.theme) in /usr/local/share/cmus.	 You
       can switch them using the :colorscheme command.	You can	put your own
       color schemes to	$XDG_CONFIG_HOME/cmus.

   Examples
       Example status display script (See status_display_program option) can
       be found	in /usr/local/share/examples/cmus.

ENVIRONMENT
       CMUS_CHARSET
	      Override cmus character set (default: `locale charmap`).

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

       CMUS_SOCKET
	      Override cmus socket path	(default:
	      $XDG_RUNTIME_DIR/cmus-socket).

       HOME
	      Full path	of the user's home directory.

       http_proxy
	      URI of the proxy to use for HTTP requests.

       USER
	      Name of the user running cmus.

       USERNAME
	      Fallback for USER.

BUGS
       After a crash last lines	of ~/cmus-debug.txt might contain useful
       information.  The file exists only if you configured cmus with maximum
       debug level (./configure	DEBUG=2).

       Feature requests	and bug	reports	should go to the github	issue tracker:
	      https://github.com/cmus/cmus/issues

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

AUTHORS
       cmus was	mainly written by Timo Hirvonen	<tihirvon@gmail.com>.  Other
       contributers are	listed in the AUTHORS file.

       This man	page was written by Frank Terbeck <ft@bewatermyfriend.org>,
       Timo Hirvonen <tihirvon@gmail.com>, and Clay Barnes
       <clay.barnes@gmail.com>.

cmus				  31/01/2010			       CMUS(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | VIEWS | COMMAND LINE | SEARCHING | PLAYLIST EDITING | STATUS LINE | KEYBINDINGS | LIBRARY VIEW SORTING | COMMANDS | CONFIGURATION OPTIONS | PLUGIN OPTIONS | PLAYING AUDIO DISCS | FILTERS | FILES | ENVIRONMENT | BUGS | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=cmus&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help