@title CMUS 1 31/01/2010 cmus

@h1 NAME

cmus - C\* Music Player


@h1 SYNOPSIS

cmus [*options*]


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

@h1 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.

--passwd PASSWD
	Set the password for TCP/IP connections.  Must be set if you are listening
	from host[:port].  Used in conjunction with --listen.

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


@h1 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*.

@h1 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:

	@pre
	# 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
	@endpre


@h1 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.


@h1 PLAYLIST EDITING

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

@h2 Copying Tracks Between Views

You can copy marked or selected tracks from views 1-5.

@li *a*
copy tracks to the library (1-2)

@li *y*
copy tracks to the marked playlist (3)

@li *e*
append tracks to the play queue (4)

@li *E*
prepend tracks to the play queue (4)

@h2 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.

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


@h1 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:

@pre
aaa_mode & play_sorted & play_library | continue follow repeat shuffle
@endpre

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.


@h1 KEYBINDINGS

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


@h2 Common Context
@pre
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
/                           search-start
?                           search-b-start
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                           toggle follow
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
@endpre

@h2 Browser Context
@pre
space          win-activate
backspace      browser-up
i              toggle show_hidden
u              win-update
@endpre


@h1 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.


@h1 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.

	@li -l
	add to library

	@li -p
	add to playlist

	@li -q
	add play queue

	@li -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.

	@li -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.

	@li -l
	clear library

	@li -p
	clear playlist

	@li -q
	clear play queue

colorscheme <name>
	Change color scheme.  Color schemes are found in `/usr/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:

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

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.

	@li -l
	load to library views

	@li -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.

	@li -i
	ask before exiting

raise-vte
	Raise the virtual terminal emulator window.  Works only in X session.

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.

	@li -l
	save library views

	@li -L
	save filtered library views

	@li -p
	save playlist view

	@li -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:

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

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.

version
	Print the version information.

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:

		@pre
		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%
		@endpre

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 (*^D*)
	Goto down half a page in the current window.

win-half-page-up (*^U*)
	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.


@h1 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_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.

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. See *D-Bus Interface (MPRIS)*

	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.

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

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/share/doc/cmus/examples/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.

@h2 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

@h2 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.

@h2 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}		@br
	%A  %{albumartist}	@br
	%l  %{album}		@br
	%D  %{discnumber}	@br
	%n  %{tracknumber}	@br
	%X  %{play_count}	@br
	%t  %{title}		@br
	%g  %{genre}		@br
	%c  %{comment}		@br
	%y  %{date}		@br
	%d  %{duration}		@br
	%f  %{path}		@br
	%F  %{filename}		@br
	    %{albumduration}    @br
	    %{originaldate}	@br
	    %{maxdate}		@br
	    %{bpm}		@br
	    %{bitrate}		@br
	    %{codec}		@br
	    %{codec_profile}	@br
	    %{rg_track_gain}	@br
	    %{rg_track_peak}	@br
	    %{rg_album_gain}	@br
	    %{rg_album_peak}	@br
	    %{arranger}		@br
	    %{composer}		@br
	    %{conductor}	@br
	    %{lyricist}		@br
	    %{performer}	@br
	    %{remixer}		@br
	    %{label}		@br
	    %{publisher}	@br
	    %{work}		@br
	    %{opus}		@br
	    %{partnumber}	@br
	    %{part}		@br
	    %{subtitle}		@br
	    %{media}		@br
	%=
		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. @br
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 @br
	configuration options @br
	keyword *stream* [boolean] (returns true if track is a stream) @br
	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:

	@pre
	: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
	@endpre

@h2 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


@h1 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.

@h1 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*).


@h1 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.

@h2 Types

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

	@li *simple*
	`e.g.` beatles

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

	@li *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.

@h2 Strings

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

@li short
*~f*, *~a*, *~A*, *~l*, *~t*, *~g*, *~c*
@br
Comparators: none

@h2 Integers

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

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

@h2 Booleans

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

@h2 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")

@h2 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*.

@h2 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\*"
	@br
	:filter ~y1980-~grock

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

@h2 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.


@h1 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/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.

@h2 Color Schemes

There are some color schemes (\*.theme) in `/usr/share/cmus`.  You can switch
them using the *:colorscheme* command.  You can put your own color schemes to
$XDG_CONFIG_HOME/cmus.

@h2 Examples

Example status display script (See *status_display_program* option) can be
found in `/usr/share/doc/cmus/examples`.


@h1 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*.

@h1 D-Bus Interface (MPRIS)

cmus provides a D-Bus interface following the Media Player Remote Interfacing Specification (MPRIS) v2:
	https://www.freedesktop.org/wiki/Specifications/mpris-spec/

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:
	https://www.freedesktop.org/wiki/Specifications/mpris-spec/metadata/
Additionally, the `cmus:stream_title` field is exposed if appropriate.

@h1 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


@h1 SEE ALSO

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


@h1 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>.
