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).
--listen ADDR
Listen to ADDR (UNIX socket) instead of
$CMUS_SOCKET or $XDG_RUNTIME_DIR/cmus-socket. ADDR is either a
UNIX socket or host[:port].
WARNING: Using host[:port] is insecure even with
password! It might be useful though in LAN if you want multiple local users to
able to control cmus. Never make cmus listen to the internet.
NOTE: Don't use this option to run multiple instances as
same user. That would corrupt the track metadata cache.
--plugins
List available plugins and exit.
--show-cursor
Keep cursor always visible. This is useful for screen
readers.
--help
Display usage information and exit.
--version
Display version information and exit.
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 playlist 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, 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.
Everything in cmus is implemented as commands which can be typed
at command line or bound to a key. To enter command mode type :. To
execute a command press ENTER or to cancel press ESC or
CTRL-C. Use up/down arrows to browse command history. Use TAB
to complete commands and parameters, you can tab complete almost anything.
You don't need to type full command names if the command is unambiguous (no
other commands starting with the same characters).
Examples:
# add files, short for ':add ~/music'
:a ~/music
# change output plugin
:set output_plugin=oss
# start playing
# you could just press 'x' which is the default
# binding for this command
:player-play
# clear current view (library, playlist or play queue)
:clear
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.
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).
You can copy marked or selected tracks from views 1-5.
- a
- copy tracks to the library (1-2)
- y
- copy tracks to the playlist (3)
- e
- append tracks to the play queue (4)
- E
- prepend tracks to the play queue (4)
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.
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).
Right hand side of the status line (second row from the bottom,
black text on a grey background) consists of the following fields:
aaa_mode & play_sorted & play_library | continue follow repeat shuffle
NOTE: aaa_mode and play_sorted will be displayed
only if play_library is true because these are meaningless
when playing the playlist (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.
Here's list of default keybindings. See unbind and
bind commands in the COMMANDS section.
q quit -i
^C echo Type :quit<enter> to exit cmus.
I echo {}
b player-next
c player-pause
x player-play
z player-prev
v player-stop
^L refresh
n search-next
N search-prev
. seek +1m
l, right seek +5
, seek -1m
h, left seek -5
m toggle aaa_mode
C toggle continue
M toggle play_library
o toggle play_sorted
r toggle repeat
^R toggle repeat_current
t toggle show_remaining_time
s toggle shuffle
F push filter<space>
L push live-filter<space>
u update-cache
1 view tree
2 view sorted
3 view playlist
4 view queue
5 view browser
6 view filters
7 view settings
! push shell<space>
] vol +0 +1
[ vol +1 +0
+, = vol +10%
} vol -0 -1
{ vol -1 -0
- vol -10%
enter, mlb_click_selected win-activate
E win-add-Q
a win-add-l
y win-add-p
e win-add-q
G, end win-bottom
down, j, mouse_scroll_down win-down
p win-mv-after
P win-mv-before
tab win-next
^F, page_down win-page-down
^B, page_up win-page-up
^E win-scroll-down
^Y win-scroll-up
D, delete win-remove
i win-sel-cur
space win-toggle
g, home win-top
k, up, mouse_scroll_up win-up
space win-activate
backspace browser-up
i toggle show_hidden
u win-update
The library view (the tree-like one; not the sorted library view,
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.
This section describes cmus' commands. You can bind a key to any
of these commands, put these commands to configuration files and execute
them in command mode. Also cmus-remote uses these commands in its
protocol.
Optional parameters are in brackets, obligatory parameters in
angle brackets and default key bindings in parenthesis.
add [-l] [-p] [-q] [-Q] <file|dir|url|playlist>
Add file/dir/url/playlist to the specified view or the
current view.
- -l
- add to library
- -p
- add to playlist
- -q
- add play queue
- -Q
- prepend to play queue
URL is a Shoutcast stream (http://...) or a CDDA URL
(cdda://...) (see PLAYING AUDIO DISCS).
Supported playlist: plain, .m3u, .pls.
bind [-f] <context> <key> <command>
Add a key binding.
- -f
- overwrite existing binding
Use tab to expand contexts, keys and commands. Command is
any command listed in this section.
Valid key contexts
common, library (1-2), playlist (3), queue (4), browser
(5), filters (6)
There's one context for each view. Common is a special
context on which bound keys work in every view.
You can override specific keys in common context for a
view. For example i selects the current track in views 1-3 but in
browser it is overridden to toggle showing of hidden files.
browser-up (backspace)
Change to parent directory in browser view (5). This
command only makes sense to be bound to the browser key context
although it's possible to use this even if browser view is not active.
cd [directory]
Changes the current working directory. Changes the
directory displayed in browser view too.
clear [-l] [-p] [-q]
Remove all tracks from the specified view or the current
view.
- -l
- clear library
- -p
- clear playlist
- -q
- clear play queue
colorscheme <name>
Change color scheme. Color schemes are found in
/usr/share/cmus/ or $XDG_CONFIG_HOME/cmus/ and have .theme
filename extension.
echo <arg>...
Display arguments on the command line.
If the arguments contain {} it is replaced with
file name of the first selected track.
NOTE: unlike with run the {} is replaced
with only the first selected filename.
Default bindings:
common I echo {}
common ^C echo Type :quit<enter> to exit cmus.
factivate <user-defined-filter>...
Select and activate the given user defined filters
(displayed in the filters view). Filter names are separated by spaces. This
command is mostly useful when bound to a key, to change active filters very
quickly. If no arguments given then all filters are unactivated.
If you prefix a filter name with "!" then the
filter value is negated before activation.
filter <filter-expression>
Use this command when you want to temporarily filter
contents of the library views without having separately define (fset) and
activate the filter. The filter is not saved.
fset <name>=<filter-expression>
Define (or replace existing) filter and add it to filters
view (6).
invert
Invert the marking of tracks in playlist and queue views.
See mark and unmark.
live-filter
<simple-filter-expression|short-filter-expression>
Use this command when you want to temporarily filter
contents of the library views without having separately define (fset) and
activate the filter. The filter is not saved.
load [-l] [-p] <playlist>
Load a playlist to the specified view or to the current
view.
- -l
- load to library views
- -p
- load to playlist view
lqueue [NUM]
Queue NUM (default 1) random albums from the library. See
also tqueue.
mark <filter-expression>
Mark tracks in playlist and queue view by using a filter
expression.
player-next (b)
Skip to the next track.
player-pause (c)
Toggle pause.
player-play [filename] (x)
Play the given track, or, if none is specified, [re]play
the current track from the beginning.
player-prev (z)
Skip to the previous track.
player-stop (v)
Stop playback.
prev-view
Go to previously used view.
left-view
Go to view "to the left" of current one, e.g.
view 4 -> view 3.
right-view
Go to view "to the right" of current one, e.g.
view 3 -> view 4.
push <text>
Enter command mode with the command line pre-set to text.
Example:
bind common w push filter artist=
Text can contain spaces and even trailing spaces will be
honored. This command can only be bound to a key but not used in the command
line directly.
pwd
Prints the current working directory.
quit [-i] (q, :wq)
Exit cmus.
- -i
- ask before exiting
rand
Randomizes (shuffles) the tracks in the library, playlist
or queue view.
refresh (^L)
Redraw the terminal window.
run <command>
Run command for the marked tracks OR the selected one if
none marked.
By default file names are appended to the command. If the
command contains {} it is replaced with list of filenames.
NOTE: In view 1 you can run a command for all files in
the selected album or artist.
save [-e] [-l] [-L] [-p] [-q] [file] (:w)
Save the specified view's or the current view's contents
to a playlist file. In extended mode (-e), also save metadata.
- -l
- save library views
- -L
- save filtered library views
- -p
- save playlist view
- -q
- save queue view
If no filename given the old filename is used.
"-" outputs to stdout (works only remotely).
search-next (n)
If a search pattern has been entered before, search
forward for the next match in the current view. See SEARCHING
above.
search-prev (N)
If a search pattern has been entered before, search
backwards for the previous match in the current view. See SEARCHING
above.
seek [+-](<num>[mh] | [HH:]MM:SS)
Seek to absolute or relative position. Position can be
given in seconds, minutes (m), hours (h) or HH:MM:SS format where HH: is
optional.
Seek 1 minute backward
:seek -1m
Seek 5 seconds forward
:seek +5
Seek to absolute position 1h
:seek 1h
Seek 90 seconds forward
:seek +1:30
Default bindings:
common , :seek -1m
common . :seek +1m
common l :seek +5
common h :seek -5
common right :seek +5
common left :seek -5
set <option>=<value>
Set value of an option. See OPTIONS.
set <option>
Display option value. Vim compatible set
<option>? is also supported.
shell <command>
Execute a command via /bin/sh.
showbind <context> <key>
Show key binding.
shuffle
Reshuffle the shuffle lists for both library and playlist
views.
source <filename>
Read and execute commands from <filename>.
toggle <option>
Toggle value of a toggle-able option (all booleans and
tristate aaa_mode).
tqueue [NUM]
Queue NUM (default 1) random tracks from the library. See
also lqueue.
unbind [-f] <context> <key>
Remove a key binding. Use tab to cycle through bound
keys.
-f
Don't throw an error if the binding is not known
unmark
Unmark all tracks (see mark).
update-cache [-f]
Update track metadata cache
($XDG_CONFIG_HOME/cmus/cache). Only files with changed modification time or
removed files are considered.
-f
Update all files. Same as quit, rm -f
$XDG_CONFIG_HOME/cmus/cache, start cmus.
view <name or 1-7>
Switches active view.
vol [+-]NUM[%] [[+-]NUM[%]]
Set, increase or decrease volume.
If you give vol just one argument it changes both
channels. Two values make it possible to change the left and right channel
independently.
To increase or decrease volume prefix the value with
- or +, otherwise value is treated as absolute volume.
Both absolute and relative values can be given as
percentage units (suffixed with %) or as internal values (hardware may
have volume in range 0-31 for example).
Default bindings:
common = :vol +10%
common + :vol +10%
common - :vol -10%
common [ :vol +1% +0%
common ] :vol +0% +1%
common { :vol -1% -0%
common } :vol -0% -1%
win-activate (enter)
In views 1-3 start playing the selected track. In view 5
start playing the selected track or change to the selected directory. In view
6 activate the selected filters. In settings view (7) change binding or
variable.
win-add-l (a)
Add the currently marked or selected track(s) (views
3-4), or the currently selected file or directory (view 5) to the
library.
Analogous to :add -l
win-add-p (y)
Add the currently marked or selected track(s) (views 1-2,
4), or the currently selected file or directory (view 5) to the
playlist.
Analogous to :add -p
win-add-Q (E)
Prepend the currently marked or selected track(s) (views
1-3), or the currently selected file or directory (view 5) to the play
queue.
Analogous to :add -Q
win-add-q (e)
Add the currently marked or selected track(s) (views
1-3), or the currently selected file or directory (view 5) to the play
queue.
Analogous to :add -q
win-bottom (G, end)
Goto bottom of the current window.
win-down [NUM] (j, down)
Goto down NUM (default 1) rows in the current
window.
win-half-page-down
Goto down half a page in the current window.
win-half-page-up
Goto up half a page in the current window.
win-mv-after (p)
If no tracks are marked, move the selected track down one
row. If any tracks are marked, move the marked tracks after the currently
selected track. This command works in unsorted playlist and play queue
view.
win-mv-before (P)
If no tracks are marked, move the selected track up one
row. If any tracks are marked, move the marked tracks before the currently
selected track. This command works in unsorted playlist and play queue
view.
win-next (tab)
Activate next window. Only relevant in view 1.
win-page-bottom
Goto the bottom of the visible part of the current
window.
win-page-down (^F, page_down)
Goto down one page in the current window.
win-page-middle
Goto the middle of the visible part of the current
window.
win-page-top
Goto the top of the visible part of the current
window.
win-page-up (^B, page_up)
Go up one page in the current window.
win-remove (D, delete)
Remove the selected entry. For tracks no confirmations
are made. For 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, 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.
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)
When enabled, cmus will always open an artist and select
the album when following the currently played track or performing actions such
as "search" or "go to current track". This option is
tightly coupled to the show_all_tracks option. Any
"auto_expand_albums_ = false" implies "show_all_tracks =
true".
auto_reshuffle (true)
Reshuffle playlist when end of shuffle list is
reached.
aaa_mode (all) [all, artist, album]
Defines what tracks should be played in the library view.
Not used in the other views. For example if set to artist the player
behaves like there were only the files of the currently playing artist in the
library.
altformat_current [Format String]
Alternative format string for the line displaying
currently playing track.
NOTE: if empty, format_current is used
instead.
altformat_playlist [Format String]
Alternative format string for the list views (2-4).
NOTE: if empty, format_playlist is used
instead.
altformat_title [Format String]
Alternative format string for terminal title.
NOTE: not all terminals support changing window
title.
NOTE: if empty, format_title is used
instead.
altformat_trackwin [Format String]
Alternative format string for the tree view's (1) track
window.
NOTE: if empty, format_trackwin is used
instead.
buffer_seconds (10) [1-300]
Size of player buffer in seconds.
color_cmdline_bg (default) [Color]
Command line background color.
color_cmdline_fg (default) [Color]
Command line foreground color.
color_cmdline_attr (default) [Attributes]
Command line attributes.
color_error (lightred) [Color]
Color of error messages displayed on the command
line.
color_info (lightyellow) [Color]
Color of informational messages displayed on the command
line.
color_separator (blue) [Color]
Color of the separator line between windows in view
(1).
color_statusline_bg (gray) [Color]
Status line background color.
color_statusline_fg (black) [Color]
Status line foreground color.
color_statusline_attr (default) [Attributes]
Status line attributes.
color_titleline_bg (blue) [Color]
Background color of the line displaying currently playing
track.
color_titleline_fg (white) [Color]
Foreground color of the line displaying currently playing
track.
color_titleline_attr (default) [Attributes]
Attributes of the line displaying currently playing
track.
color_win_bg (default) [Color]
Window background color.
color_win_cur (lightyellow) [Color]
Color of currently playing track.
color_win_cur_sel_bg (blue) [Color]
Background color of the selected row which is also the
currently playing track in active window.
color_win_cur_sel_fg (lightyellow) [Color]
Foreground color of the selected row which is also the
currently playing track in active window.
color_win_cur_sel_attr (default) [Attributes]
Attributes of the selected row which is also the
currently playing track in active window.
color_win_dir (lightblue) [Color]
Color of directories in browser.
color_win_fg (default) [Color]
Window foreground color.
color_win_attr (default) [Attributes]
Window attributes.
color_win_inactive_cur_sel_bg (gray) [Color]
Background color of the selected row which is also the
currently playing track in inactive window.
color_win_inactive_cur_sel_fg (lightyellow) [Color]
Foreground color of the selected row which is also the
currently playing track in inactive window.
color_win_inactive_cur_sel_attr (default) [Attributes]
Attributes of the selected row which is also the
currently playing track in inactive window.
color_win_inactive_sel_bg (gray) [Color]
Background color of selected row in inactive
window.
color_win_inactive_sel_fg (black) [Color]
Foreground color of selected row in inactive
window.
color_win_inactive_sel_attr (default) [Attributes]
Attributes of selected row in inactive window.
color_win_sel_bg (blue) [Color]
Background color of selected row in active window.
color_win_sel_fg (white) [Color]
Foreground color of selected row in active window.
color_win_sel_attr (default) [Attributes]
Attributes of selected row in active window.
color_win_title_bg (blue) [Color]
Background color of window titles (topmost line of the
screen).
color_win_title_fg (white) [Color]
Foreground color of window titles (topmost line of the
screen).
color_win_title_attr (default) [Attributes]
Attributes of window titles (topmost line of the
screen).
confirm_run (true)
Ask for confirmation before executing :run
continue (true)
Continue playing after current track finishes.
device (/dev/cdrom)
CDDA device file.
display_artist_sort_name (false)
If enabled, always displays artist names used for sorting
instead of regular ones in tree view (e.g. "Artist, The" instead of
"The Artist"), so that artists column looks alphabetically
sorted.
follow (false)
If enabled, always select the currently playing track on
track change.
format_current [Format String]
Format string for the line displaying currently playing
track.
format_playlist [Format String]
Format string for the list views (2-4).
format_playlist_va [Format String]
Format string for the list views (2-4), if a track is
assumed to be a part of compilation (see LIBRARY VIEW SORTING for
details).
NOTE: if empty, format_playlist is used
instead.
format_statusline [Format String]
Format string for status line.
format_title [Format String]
Format string for terminal title.
NOTE: not all terminals support changing window
title.
format_trackwin [Format String]
Format string for the tree view's (1) track window.
format_trackwin_album [Format String]
Format string for albums in tree view's (1) track
window.
format_trackwin_va [Format String]
Format string for the tree view's (1) track window, if a
track is assumed to be a part of compilation (see LIBRARY VIEW SORTING
for details).
NOTE: if empty, format_trackwin is used
instead.
format_treewin [Format String]
Format string for the tree view's (1) tree window.
format_treewin_artist [Format String]
Format string for artists in tree view's (1) tree
window.
smart_artist_sort (true)
If enabled, makes tree view sorting ignore
"The" in front of artist names, preventing artists starting with
"The" from clumping together. Real artistsort tags override
this option, when 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_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.
output_plugin [roar, pulse, alsa, arts, oss, sndio, sun,
coreaudio]
Name of output plugin.
pl_sort () [Sort Keys]
Sort keys for the playlist view (3). Empty value disables
sorting and enables manually moving tracks.
play_library (true)
Play tracks from the library instead of playlist.
play_sorted (false)
Play tracks from the library in the sorted view (2) order
instead of tree view (1) order. Used only when play_library is true.
repeat (false)
Repeat after all tracks played.
repeat_current (false)
Repeat current track forever.
replaygain (disabled)
Enable Replay Gain. Default is "disabled". Set
to "track", "album", "track-preferred" or
"album-preferred".
replaygain_limit (true)
Use replay gain limiting when clipping.
replaygain_preamp (0.0)
Replay gain preamplification in decibels.
resume (false)
Resume playback on startup.
rewind_offset (5) [-1-9999]
If the position of the current track is smaller than
rewind_offset, player_prev jumps to the previous track. Otherwise, player_prev
jumps to the beginning of the current track. If rewind_offset=-1, player_prev
always jumps to the previous track.
scroll_offset (2) [0-9999]
Minimal number of screen lines to keep above and below
the cursor.
show_all_tracks (true)
Display all tracks of the artist when the artist is
selected in the tree view. This option is tightly coupled to the
auto_expand_albums_ options. "show_all_tracks = false" implies
"auto_expand_albums_ = true".
show_hidden (false)
Display hidden files in browser.
show_current_bitrate (false)
Display current bitrate in the status lines.
show_playback_position (true)
Display elapsed (or remaining) time in the status line.
Can be disabled to e.g. not trigger tmux's activity monitor.
show_remaining_time (false)
Display remaining time instead of elapsed time.
shuffle (false)
Play in shuffled order. Shuffle works in the library
views (1-2) and playlist view (3).
skip_track_info (false)
Don't load metadata when adding tracks. Useful when using
network file system and having huge amount of files. Tags can be loaded using
'update-cache' or 'win-update-cache' commands.
softvol (false)
Use software volume control.
NOTE: You should probably set this to false when using
ao as output_plugin to output to wav files.
softvol_state (100 100)
Used to save left and right channel values for software
volume control. Two integers in range 0..100 separated by a space. This option
is not usually changed directly since vol command does same thing if
softvol is true.
status_display_program () [command]
This command, if not empty, is run every time cmus'
status changes. It can be used to display currently playing track on desktop
background or panel for example. See
/usr/share/doc/cmus/examples/cmus-status-display.
wrap_search (true)
Controls whether the search wraps around the end.
Color is integer in range -1..255.
The following color names are recognized:
Terminal's default color, -1
default
Fg & bg, 0..7
black, red, green, yellow, blue, magenta, cyan,
gray
Fg, 8..15
darkgray, lightred, lightgreen, lightyellow, lightblue,
lightmagenta, lightcyan, white
Attributes is a set of names "standout|bold":
default does nothing, if you put it with other attributes
the other attributes will be used.
standout makes the text standout.
bold makes the text bold.
reverse reverses the text colors.
underline underlines the text.
blink makes the text blink.
Format strings control display of tracks in library, playlist and
play queue views.
NOTE: altformat_* options are used when there are no tags
available.
Special Keys:
%a %{artist}
%A %{albumartist}
%l %{album}
%D %{discnumber}
%n %{tracknumber}
%X %{play_count}
%t %{title}
%g %{genre}
%c %{comment}
%y %{date}
%d %{duration}
%f %{path}
%F %{filename}
%{originaldate}
%{maxdate}
%{bpm}
%{bitrate}
%{codec}
%{codec_profile}
%{rg_track_gain}
%{rg_track_peak}
%{rg_album_gain}
%{rg_album_peak}
%{arranger}
%{composer}
%{conductor}
%{lyricist}
%{performer}
%{remixer}
%{label}
%{publisher}
%{work}
%{opus}
%{partnumber}
%{part}
%{subtitle}
%{media}
%=
start align right (use at most once)
%%
literal %
%?
literal ?
You can use printf style formatting (width, alignment, padding).
As an extension, the width can have a %-suffix, to specify a percentage of
the terminal width.
To see current value of an option type :set option=<TAB>.
Note: With %{bitrate}, you'll have to append the unit yourself, as
mentioned in the example below.
You can use conditional operator %{?CONDITION?A[?B]}. CONDITION
has the same syntax as filters, except for unsupported short and
simple expressions and supported keys comparison (e.g. artist=albumartist).
Its keys are:
format strings' special keys
configuration options
keyword stream [boolean] (returns true if track is a stream)
keyword va [boolean] (returns true if track's album is compilation)
Else part can be skipped. A and B can contain string literals in
" or '. A and B can be empty.
Examples:
:set format_trackwin= %02n. %t %{?y?(%y)}%= %d
:set format_current= %n. %-30t %40F (%y)%= %d
:set format_current= %a - %l - %02n. %t%= %{bitrate}Kbps %g %y
:set format_playlist= %f%= %6{rg_track_gain} dB %8{rg_track_peak}
:set format_playlist= %-25%a %-15%l %3n. %t%= %y %d
Sort 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
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.
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.
With the cdio input plugin enabled, it is possible to play Audio
CDs and CD images. Just set the device option to either a device file
(e.g. /dev/cdrom) or an image file (e.g. ~/cd.cue). Then add a new track
using the CDDA URL scheme, e.g.:
:add cdda://2
To add the whole disc, use cdda:// (without track number). This is
currently only working for audio discs, not images. Adding track ranges is
also possible (cdda://1-3). To add images without changing the device
option, it is possible to include the image path in the URL, e.g.:
:add cdda:///path/to/cd.cue/2-5
The metadata will be read from CD-Text, and if not available,
looked up from a CDDB server (see input.cdio.cddb_url).
Filters 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.
There are three types of filter expressions, each offering more
expressiveness:
- simple
- e.g. beatles
- short
- e.g. ~a beatles (!~y1960-1965 | ~d>600)
- long
- e.g. artist="*beatles*"&album="R*"
Simple expressions are only available using live-filter. For
other filter commands the type is auto-detected, so both short and long
expressions can be used.
Long expressions are lists of built-in filters or user defined
filters separated with & (and) or | (or). Parenthesis can be
used group subexpressions and ! negates result of the expression
following it. Same is true for short expressions, but they can only be made
of built-in filters. Also (and)-grouping is done implicitly.
- long
- filename, artist, albumartist, album,
title, genre, comment, codec,
codec_profile, media
Comparators: = and != (not equal)
- short
- ~f, ~a, ~A, ~l, ~t, ~g,
~c
Comparators: none
- long
- discnumber, tracknumber, date (year), originaldate
(year), duration (seconds), bitrate
Comparators: <, <=, =, >=, >,
!=
- short
- ~D, ~n, ~y, ~d
Comparators: <, >
Ranges: a-b (>=a&<=b), -b (<=b), a-
(>=a)
tag (true if track has tags), stream (true if track is a
stream)
For short expressions: ~T and ~s
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")
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.
live-filter and filter commands are useful when you want
to use a filter only once and not save it. It changes visible contents of
the library (views 1-2). filter unactivates all filters in the
filters view, while live-filter is applied in addition to all
currently activated filters.
Filter all rock (anything with rock in genre tag) music from
80s-
:filter date>=1980&genre="*rock*"
:filter ~y1980-~grock
Filter all artists/albums/titles containing
"sleepwalking"
:live-filter sleepwalking
Mark (select) all tracks with duration less than 2 minutes
:mark duration<120
Mark (select) all tracks which have been played at least once
:mark play_count>=1
These commands work in views 2-4.
cmus reads its configuration from 3 different places.
$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.
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.
Example status display script (See status_display_program
option) can be found in /usr/share/doc/cmus/examples.
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.
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 cmus-devel
mailing list:
http://lists.sourceforge.net/lists/listinfo/cmus-devel
cmus-tutorial(7), cmus-remote(1)
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>.