@title CMUS 1 31/01/2010 cmus

@h1 NAME

cmus - C\* Music Player


@h1 SYNOPSIS

cmus [*options*]


@h1 DESCRIPTION

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

@h1 OPTIONS

--listen ADDR
	Listen on ADDR (UNIX socket) instead of `$CMUS_SOCKET` or
	`$XDG_RUNTIME_DIR/cmus-socket`. ADDR must be a UNIX socket or
	host[:port].

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

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

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

--plugins
	List available plugins and exit.

--show-cursor
	Always display the cursor. 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)
	Displays all tracks in the *library*. Tracks are sorted and displayed in
	a tree grouped by artist/album. Artist sorting is done alphabetically.
	Albums are sorted by year.

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

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

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

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

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 the command line
or bound to a key. To enter command mode type *:*. To execute a command, press
*ENTER*, and to cancel, press *ESC* or *CTRL-C*. Use up/down arrows to browse
the command history. Use *TAB* to complete commands and parameters. You don't
need to type the full command name if it 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
type the query then press *ENTER*. Press *n* to move to the next result or *N*
for the previous one. Type *?* to search backwards.

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

Searching also works in views 5-7.


@h1 PLAYLIST EDITING

@h2 Selecting Tracks

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

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

@h2 Copying Tracks Between Views

You can copy marked or selected tracks in 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, tracks can be moved within the list. Note that moving is disabled
if the view is auto-sorted (see *lib_sort* and *pl_sort* options).

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

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

@h2 Removing Tracks

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


@h1 STATUS LINE

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

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

See the CONFIGURATION OPTIONS section for more information about these options.


@h1 KEYBINDINGS

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


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

B                       player-next-album
Z                       player-prev-album

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

,                       seek -1m
.                       seek +1m

h                       seek -5
l                       seek +5

left                    seek -5
right                   seek +5

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

@h2 Common: Setting Toggles
@pre
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
@endpre

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

!                       push shell<space>
@endpre

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

mouse_scroll_up_title   left-view
mouse_scroll_down_title right-view

tab                     win-next

^L                      refresh
@endpre

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

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

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

mouse_scroll_up         win-up
mouse_scroll_down       win-down
@endpre

@h2 Common: Selection
@pre
i                       win-sel-cur
enter                   win-activate
mlb_click_selected      win-activate

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

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

u                       update-cache
U                       win-update-cache
@endpre

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

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

@h2 File Browser
@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, which is
configured with lib_sort - see `CONFIGURATION OPTIONS`), is sorted automatically
using tags from the audio files.

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

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

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

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

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

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


@h1 COMMANDS

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

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

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

	@li -l
	add to library

	@li -p
	add to playlist

	@li -q
	add play queue

	@li -Q
	prepend to play queue

	Supported files are based on the loaded input plugins.

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

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

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

	@li -f
	overwrite existing binding

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

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

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

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

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

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

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

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

	@li -l
	clear library

	@li -p
	clear playlist

	@li -q
	clear play queue

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

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

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

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

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

	Prefix a filter name with *!* to negate it.

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

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

help
	Shows information about help files.

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

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

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

	@li -l
	load to library views

	@li -p
	load to playlist view

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

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

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

mute
	Toggles mute for the sound output.

pl-create <name>
	Creates a new playlist.

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

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

pl-rename <name>
	Renames the selected playlist.

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

player-next-album (*B*)
	Skips to the next album. If *shuffle*=`tracks` or a playlist is active,
	skips to the next track.

player-pause (*c*)
	Toggles pause.

player-pause-playback
	Pauses if currently playing.

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

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

player-prev-album (*Z*)
	Skips to the previous album. If *shuffle*=`tracks` or a playlist is active,
	skips to the previous track.

player-stop (*v*)
	Stops playback.

prev-view
	Goes to the previously used view.

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

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

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

		bind common w push filter artist=

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

pwd
	Prints the current working directory.

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

	@li -i
	ask before exiting

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

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

refresh (*^L*)
	Redraws the terminal window.

reshuffle
	Reshuffles the shuffle lists for both library and playlist views.

run <command>
	Runs a 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*)
	Saves the contents of a view to a playlist file. In extended mode (-e),
	also saves track metadata.

	@li -l
	save library views

	@li -L
	save filtered library views

	@li -p
	save playlist view

	@li -q
	save queue view

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

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

search-b-start
	Enters backwards search mode. Cannot be used directly from command mode.

	See *search-start*.

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

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

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

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

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

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

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

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

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

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

toggle <option>
	Toggles the value of a toggle-able option (all booleans and the options
	*shuffle*, *aaa_mode*, and *replaygain*).

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

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

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

unmark
	Unmarks all tracks (see *mark*).

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

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

version
	Prints the version information.

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

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

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

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

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

w
	See *quit*. Intended for use while in command mode.

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

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

	Analogous to *:add -l*

	-n
		Don't move the selection to the next item.

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

	Analogous to *:add -p*

	-n
		Don't move the selection to the next item.

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

	Analogous to *:add -Q*

	-n
		Don't move the selection to the next item.

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

	Analogous to *:add -q*

	-n
		Don't move the selection to the next item.

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

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

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

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

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

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

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

win-page-bottom
	Goes to the bottom of the visible part of the current window.

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

win-page-middle
	Goes to the middle of the visible part of the current window.

win-page-top
	Goes to the top of the visible part of the current window.

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

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

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

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

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

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

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

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

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

	Reloads contents of directory in the browser view.

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

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

wq
	See *quit*. Intended for use from command mode.


@h1 CONFIGURATION OPTIONS

This section describes configuration options used by cmus.

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

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

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

aaa_mode (all) [all, artist, album]
	Defines what tracks should be played in the library view. Not used in
	the other views.
	
	For example, if set to *artist*, the player behaves like there were only
	the files of the currently playing artist in the 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 the for terminal title.

	Note: not all terminals support changing window title.

	Note: if empty, *format_title* is used instead.

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

	Note: if empty, *format_trackwin* is used instead.

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

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

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

color_cmdline_attr (default) [`Attributes`]
	Command line attributes.

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

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

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

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

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

color_statusline_attr (default) [`Attributes`]
	Status line attributes.

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

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

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

color_win_bg (default) [`Color`]
	Window background color.

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

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

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

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

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

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

color_win_fg (default) [`Color`]
	Window foreground color.

color_win_attr (default) [`Attributes`]
	Window attributes.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

confirm_run (true)
	Ask for confirmation before executing *:run*

continue (true)
	Continue playing after current track finishes.

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

device (/dev/cdrom)
	CDDA device file.

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

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

format_clipped_text [`Plain String`]
	String used to lead out any text that is cut off by field limits.

	Note: `Format String` rules are not applied. A plain string such as "..."
	is expected.

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

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

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

	Note: If empty, *format_playlist* is used instead.

format_statusline [`Format String`]
	Format string for status line.

format_title [`Format String`]
	Format string for terminal title.

	Note: Not all terminals support changing window title.

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

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

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

	Note: If empty, *format_trackwin* is used instead.

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

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

smart_artist_sort (true)
	If enabled, makes the tree view sorting ignore "The" in front of artist
	names, preventing artists starting with "The" from clumping together.
	Real `artistsort` tags override this option, if 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.

pause_on_output_change (false)
    Pauses playback when the audio output changes.

    Supported output plugins: pulse.

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) [track, album, track-preferred, album-preferred, smart]
	Enable Replay Gain. The smart setting behaves like track-preferred when
	shuffle is on, or the queue is active, or when playing from a playlist.
	Otherwise, it behaves like 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 (off) [off, tracks, albums]
	@li *off*
	Play all tracks in order. See also *lib_sort* and *pl_sort*.
	@li *tracks*
	Play all tracks in the library or playlist in a shuffled order.
	@li *albums*
	Play each library album to completion before shuffling to the first track
	of another library album. In playlists this option falls back to *tracks*
	behaviour.

	Filters and *aaa_mode* can be used to limit the items available for play.
	Note that *shuffle*=`albums` will have no effect with *aaa_mode*=`album`.

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 set, is run for every status change. 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`.

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

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

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

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

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

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

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

		@pre
		set tree_width_percent=100
		set tree_width_max=60
		@endpre

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

		@pre
		set tree_width_percent=33
		set tree_width_max=60
		@endpre

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

		@pre
		set tree_width_percent=33
		set tree_width_max=0
		@endpre

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

@h2 Colors

Color is an 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
	%!
		prior text is of lower importance and may be shortened if needed (use at most once)
	%=
		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 reverse the sort 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
	The audio buffer size; defaults to 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).c Also
	unsetting shuffle and repeat might be good idea.

dsp.ao.wav_dir
	Output directory for libao plugin; default to the 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 hog mode for the device. The default value is false.

dsp.coreaudio.sync_sample_rate
	Synchronize 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
	The re-sampling quality. 0 is low quality but fast, 1 is medium quality,
	2 (default) is high quality but more CPU intensive. This option is only
	available if cmus was compiled with libsamplerate support.

input.cdio.cddb_url
	CDDB URL (default: freedb.freedb.org:8880). Uses HTTP 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

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

	:add cdda://2

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

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

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

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


@h1 FILTERS

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

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

@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 the *fset* command. User defined filters appear in
the filters view (6).

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

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

@h2 Activating Filters

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

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

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

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

@h2 Throw-away Filters

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

Filter all rock (anything with *rock* in genre tag) music from 80s-
	:filter date>=1980&genre="\*rock\*"
	@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 in the following order:

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

`/usr/share/cmus/rc`
	This file contains the default configuration.

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

`$XDG_CONFIG_HOME/cmus/rc`
	This file is the static configuration file.

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

@h2 Color Schemes

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

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

@h2 Examples

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


@h1 ENVIRONMENT

CMUS_CHARSET
	Override the character set used by cmus (default: \`locale charmap\`).

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

CMUS_SOCKET
	Override the 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

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

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

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
contributors are listed in the `AUTHORS` file.

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