- buster 2.7.1+git20160225-2+b2
- buster-backports 2.8.0-2~bpo10+1
- testing 2.8.0-2+b1
- unstable 2.9.1-1
CMUS(1) | General Commands Manual | CMUS(1) |
NAME¶
cmus - C* Music PlayerSYNOPSIS¶
cmus [options]DESCRIPTION¶
cmus is a small ncurses based music player. It supports various output methods by output-plugins. cmus has completely configurable keybindings and can be controlled from the outside via cmus-remote(1).OPTIONS¶
--listen ADDR--plugins
--show-cursor
--help
--version
VIEWS¶
There are 7 views in cmus. Press keys 1-7 to change active view.Library view (1)
Sorted library view (2)
Playlist view (3)
Play Queue view (4)
Browser (5)
Filters view (6)
Settings view (7)
COMMAND LINE¶
Everything in cmus is implemented as commands which can be typed at command line or bound to a key. To enter command mode type :. To execute a command press ENTER or to cancel press ESC or CTRL-C. Use up/down arrows to browse command history. Use TAB to complete commands and parameters, you can tab complete almost anything. You don't need to type full command names if the command is unambiguous (no other commands starting with the same characters).Examples:
# add files, short for ':add ~/music' :a ~/music # change output plugin :set output_plugin=oss # start playing # you could just press 'x' which is the default # binding for this command :player-play # clear current view (library, playlist or play queue) :clear
SEARCHING¶
Search mode works like the command mode, to enter search mode press / and then type the search words and press ENTER. Press n to search next or N to search previous match using the same search words. Type ? to search backwards.In views 1-4 words are compared to artist, album and title tags. Type //WORDS or ??WORDS to search only artists/albums in view 1 or titles in views 2-4. If the file doesn't have tags words are compared to filename without path.
Searching works in views 5-7 too and its logic should be pretty obvious.
PLAYLIST EDITING¶
Selecting Tracks¶
Editing commands affect the currently marked tracks or if there are no marked tracks the currently selected track (or selected artist/album in view 1).Mark selected track by pressing SPACE. Marked tracks appear with a gray background. You can only mark tracks in the list views (2-4).
Copying Tracks Between Views¶
You can copy marked or selected tracks from views 1-5.- a
- copy tracks to the library (1-2)
- y
- copy tracks to the playlist (3)
- e
- append tracks to the play queue (4)
- E
- prepend tracks to the play queue (4)
Moving Tracks¶
In views 2-4 you can move tracks within the list. Note that moving is disabled if the view is auto-sorted (see lib_sort and pl_sort options).Pressing p moves marked tracks to the position immediately after the selected track. P moves them to the position immediately before the selected track. If there are no marked tracks then the selected track is moved down (p) or up (P).
NOTE: Changing active filters reloads view 2 so it isn't a good idea to manually order tracks in the view.
Removing Tracks¶
Press D or delete to remove marked or selected tracks in the current view (1-4). The tracks will be removed immediately from the view without asking for confirmation. In the browser and filters views the same keys are used to remove a file or filter (will ask for confirmation).STATUS LINE¶
Right hand side of the status line (second row from the bottom, black text on a grey background) consists of the following fields:aaa_mode & play_sorted & play_library | continue follow repeat shuffle
NOTE: aaa_mode and play_sorted will be displayed only if play_library is true because these are meaningless when playing the 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.
KEYBINDINGS¶
Here's list of default keybindings. See unbind and bind commands in the COMMANDS section.Common Context¶
q quit -i ^C echo Type :quit<enter> to exit cmus. I echo {} b player-next c player-pause x player-play z player-prev v player-stop ^L refresh n search-next N search-prev . seek +1m l, right seek +5 , seek -1m h, left seek -5 m toggle aaa_mode C toggle continue M toggle play_library o toggle play_sorted r toggle repeat ^R toggle repeat_current t toggle show_remaining_time s toggle shuffle F push filter<space> L push live-filter<space> u update-cache 1 view tree 2 view sorted 3 view playlist 4 view queue 5 view browser 6 view filters 7 view settings ! push shell<space> ] vol +0 +1 [ vol +1 +0 +, = vol +10% } vol -0 -1 { vol -1 -0 - vol -10% enter, mlb_click_selected win-activate E win-add-Q a win-add-l y win-add-p e win-add-q G, end win-bottom down, j, mouse_scroll_down win-down p win-mv-after P win-mv-before tab win-next ^F, page_down win-page-down ^B, page_up win-page-up ^E win-scroll-down ^Y win-scroll-up D, delete win-remove i win-sel-cur space win-toggle g, home win-top k, up, mouse_scroll_up win-up
Browser Context¶
space win-activate backspace browser-up i toggle show_hidden u win-update
LIBRARY VIEW SORTING¶
The library view (the tree-like one; not the sorted library view, for which the sorting is controlled by the user by setting lib_sort - see CONFIGURATION OPTIONS), is sorted automatically by cmus using the information found in the tagging information provided by the audio files.Generally, in the library view cmus uses three levels of sorting: the first level would be the artist name, the second one the album and finally the actual track.
At first, cmus checks if the "filename" looks like an URL, if it does, the item is given the special artist and album name <Stream>.
If it is a file, it is checked if the artist and album tags are set. If not, cmus assigns the special name <No Name> for the unset tag.
As the first level, cmus sorts alphanumerically by the value of the artist tag. (<Stream> and <No Name> will be used as if they where normal names.) If a special sorting tag is available, it's value will be used instead.
For album names, alphanumerical sorting is not the primary method, though. To decide, how the second level should be sorted, cmus looks at the date of the first track of each album. Sorting is done from young to old. Of course, if one artist happens to have more then one album from one year, alphanumerical sorting will be used after sorting by date.
If the date header is not set, the album will be placed on top of the list (in fact, the internal integer value for unset album tags is -1).
The method for third sorting level (the track) is very similar to album sorting. First two numerical values are checked (discnumber and tracknumber). If sorting is still ambiguous, sorting will be done alphanumerically by the value of the track's filename (not track name!).
For simple albums, that is it. There is a special case, though. Albums, that feature various artists, also known as samplers or compilations.
If a track belongs to a compilation is again decided by the existence and value of special tagging information. First, it is checked if cmus should use a special artist name (e.g.: 'Fatboy Slim' for a DJ set). If so, that one will be used instead of the real artist name.
If that special name tag is not set, cmus checks if another tag is set. If that is the case, the album will be given the special artist name <Various Artists>. Albums filed under <Various Artists> are sorted alphanumerically by album name instead of by date.
That way, you do not end up with compilation tracks scattered around your library view.
The problem with compilation tagging is, that there is no generic tag or method, that can be regarded as a standard across all different formats, supported by cmus.
For mp3, the special-name tag would be the id3v2 TPE2 frame. The mark-as-compilation tag is the TCMP frame (which is a user defined id3v2.3 frame, used at least by amarok and apple's iTunes[tm]).
For vorbis style tags (for example in ogg vorbis and flac files), the special-name tag is ALBUMARTIST and the mark-as-compilation tag is COMPILATION. Vorbis tags names are case insensitive.
COMMANDS¶
This section describes cmus' commands. You can bind a key to any of these commands, put these commands to configuration files and execute them in command mode. Also cmus-remote uses these commands in its protocol.Optional parameters are in brackets, obligatory parameters in angle brackets and default key bindings in parenthesis.
add [-l] [-p] [-q] [-Q] <file|dir|url|playlist>
- -l
- add to library
- -p
- add to playlist
- -q
- add play queue
- -Q
- prepend to play queue
bind [-f] <context> <key> <command>
- -f
- overwrite existing binding
browser-up (backspace)
cd [directory]
clear [-l] [-p] [-q]
- -l
- clear library
- -p
- clear playlist
- -q
- clear play queue
colorscheme <name>
echo <arg>...
common I echo {} common ^C echo Type :quit<enter> to exit cmus.
factivate <user-defined-filter>...
filter <filter-expression>
fset <name>=<filter-expression>
invert
live-filter <simple-filter-expression|short-filter-expression>
load [-l] [-p] <playlist>
- -l
- load to library views
- -p
- load to playlist view
lqueue [NUM]
mark <filter-expression>
player-next (b)
player-pause (c)
player-play [filename] (x)
player-prev (z)
player-stop (v)
prev-view
left-view
right-view
push <text>
pwd
quit [-i] (q, :wq)
- -i
- ask before exiting
rand
refresh (^L)
run <command>
save [-e] [-l] [-L] [-p] [-q] [file] (:w)
- -l
- save library views
- -L
- save filtered library views
- -p
- save playlist view
- -q
- save queue view
search-next (n)
search-prev (N)
seek [+-](<num>[mh] | [HH:]MM:SS)
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 <option>
shell <command>
showbind <context> <key>
shuffle
source <filename>
toggle <option>
tqueue [NUM]
unbind [-f] <context> <key>
unmark
update-cache [-f]
view <name or 1-7>
vol [+-]NUM[%] [[+-]NUM[%]]
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)
win-add-l (a)
win-add-p (y)
win-add-Q (E)
win-add-q (e)
win-bottom (G, end)
win-down [NUM] (j, down)
win-half-page-down
win-half-page-up
win-mv-after (p)
win-mv-before (P)
win-next (tab)
win-page-bottom
win-page-down (^F, page_down)
win-page-middle
win-page-top
win-page-up (^B, page_up)
win-remove (D, delete)
win-scroll-down (^E)
win-scroll-up (^Y)
win-sel-cur (i)
win-toggle (space)
win-top (g, home)
win-up [NUM] (k, up)
win-update (u)
win-update-cache [-f]
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)
auto_reshuffle (true)
aaa_mode (all) [all, artist, album]
altformat_current [Format String]
altformat_playlist [Format String]
altformat_title [Format String]
altformat_trackwin [Format String]
buffer_seconds (10) [1-300]
color_cmdline_bg (default) [Color]
color_cmdline_fg (default) [Color]
color_cmdline_attr (default) [Attributes]
color_error (lightred) [Color]
color_info (lightyellow) [Color]
color_separator (blue) [Color]
color_statusline_bg (gray) [Color]
color_statusline_fg (black) [Color]
color_statusline_attr (default) [Attributes]
color_titleline_bg (blue) [Color]
color_titleline_fg (white) [Color]
color_titleline_attr (default) [Attributes]
color_win_bg (default) [Color]
color_win_cur (lightyellow) [Color]
color_win_cur_sel_bg (blue) [Color]
color_win_cur_sel_fg (lightyellow) [Color]
color_win_cur_sel_attr (default) [Attributes]
color_win_dir (lightblue) [Color]
color_win_fg (default) [Color]
color_win_attr (default) [Attributes]
color_win_inactive_cur_sel_bg (gray) [Color]
color_win_inactive_cur_sel_fg (lightyellow) [Color]
color_win_inactive_cur_sel_attr (default) [Attributes]
color_win_inactive_sel_bg (gray) [Color]
color_win_inactive_sel_fg (black) [Color]
color_win_inactive_sel_attr (default) [Attributes]
color_win_sel_bg (blue) [Color]
color_win_sel_fg (white) [Color]
color_win_sel_attr (default) [Attributes]
color_win_title_bg (blue) [Color]
color_win_title_fg (white) [Color]
color_win_title_attr (default) [Attributes]
confirm_run (true)
continue (true)
device (/dev/cdrom)
display_artist_sort_name (false)
follow (false)
format_current [Format String]
format_playlist [Format String]
format_playlist_va [Format String]
format_statusline [Format String]
format_title [Format String]
format_trackwin [Format String]
format_trackwin_album [Format String]
format_trackwin_va [Format String]
format_treewin [Format String]
format_treewin_artist [Format String]
smart_artist_sort (true)
id3_default_charset (ISO-8859-1)
icecast_default_charset (ISO-8859-1)
lib_sort (artist album discnumber tracknumber title filename) [Sort Keys]
mouse (false)
output_plugin [roar, pulse, alsa, arts, oss, sndio, sun, coreaudio]
pl_sort () [Sort Keys]
play_library (true)
play_sorted (false)
repeat (false)
repeat_current (false)
replaygain (disabled)
replaygain_limit (true)
replaygain_preamp (0.0)
resume (false)
rewind_offset (5) [-1-9999]
scroll_offset (2) [0-9999]
show_all_tracks (true)
show_hidden (false)
show_current_bitrate (false)
show_playback_position (true)
show_remaining_time (false)
shuffle (false)
skip_track_info (false)
softvol (false)
softvol_state (100 100)
status_display_program () [command]
wrap_search (true)
Colors¶
Color is integer in range -1..255.The following color names are recognized:
Terminal's default color, -1
Fg & bg, 0..7
Fg, 8..15
Attributes¶
Attributes is a set of names "standout|bold":default does nothing, if you put it with other attributes the other attributes will be used.
standout makes the text standout.
bold makes the text bold.
reverse reverses the text colors.
underline underlines the text.
blink makes the text blink.
Format Strings¶
Format strings control display of tracks in library, playlist and play queue views.NOTE: altformat_* options are used when there are no tags available.
Special Keys:
%A %{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}
%=
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:
configuration options
keyword stream [boolean] (returns true if track is a stream)
keyword va [boolean] (returns true if track's album is compilation)
Examples:
:set format_trackwin= %02n. %t %{?y?(%y)}%= %d :set format_current= %n. %-30t %40F (%y)%= %d :set format_current= %a - %l - %02n. %t%= %{bitrate}Kbps %g %y :set format_playlist= %f%= %6{rg_track_gain} dB %8{rg_track_peak} :set format_playlist= %-25%a %-15%l %3n. %t%= %y %d
Sort Keys¶
Sort option (lib_sort, pl_sort) value is space separated list of the following sort keys:Note: Adding a '-' in front of the key will sort in reverse order
PLUGIN OPTIONS¶
dsp.alsa.devicemixer.alsa.channel
mixer.alsa.device
mixer.pulse.restore_volume
dsp.ao.buffer_size
dsp.ao.device_interface
dsp.ao.driver
dsp.ao.wav_counter
dsp.ao.wav_dir
dsp.coreaudio.device
dsp.coreaudio.enable_hog_mode
dsp.coreaudio.sync_sample_rate
dsp.jack.server_name
dsp.jack.resampling_quality
input.cdio.cddb_url
dsp.oss.device
mixer.oss.channel
mixer.oss.device
dsp.roar.server
dsp.roar.role [music, background_music, ...]
dsp.sun.device
mixer.sun.channel
mixer.sun.device
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.: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.:
The metadata will be read from CD-Text, and if not available, looked up from a CDDB server (see input.cdio.cddb_url).
FILTERS¶
Filters are used mostly for filtering contents of library views (1 & 2). Filters do not change the actual library content, i.e. :save command will still save all tracks to playlist file whether they are visible or not.Types¶
There are three types of filter expressions, each offering more expressiveness:- simple
- e.g. beatles
- short
- e.g. ~a beatles (!~y1960-1965 | ~d>600)
- long
- e.g. artist="*beatles*"&album="R*"
Simple expressions are only available using live-filter. For other filter commands the type is auto-detected, so both short and long expressions can be used.
Long expressions are lists of built-in filters or user defined filters separated with & (and) or | (or). Parenthesis can be used group subexpressions and ! negates result of the expression following it. Same is true for short expressions, but they can only be made of built-in filters. Also (and)-grouping is done implicitly.
Strings¶
- long
- filename, artist, albumartist, album,
title, genre, comment, codec,
codec_profile, media
Comparators: = and != (not equal) - short
- ~f, ~a, ~A, ~l, ~t, ~g,
~c
Comparators: none
Integers¶
- long
- discnumber, tracknumber, date (year), originaldate
(year), duration (seconds), bitrate
Comparators: <, <=, =, >=, >, != - short
- ~D, ~n, ~y, ~d
Comparators: <, >
Ranges: a-b (>=a&<=b), -b (<=b), a- (>=a)
Booleans¶
tag (true if track has tags), stream (true if track is a stream)For short expressions: ~T and ~s
Defining Filters¶
Filters can be defined with fset command. User defined filters appear in the filters view (6).Create a new filter which name is ogg and value filename="*.ogg"
Filter ogg and mp3 files from the 90s. Note the use of user defined filter ogg
Activating Filters¶
factivate changes visible contents of the library (views 1-2).Activate user defined filters ogg and missing-tags
Like above but negate value of ogg filter.
Alternatively you can select the filters by pressing space in view 6 and then activate the selected filters by pressing enter.
Throw-away Filters¶
live-filter and filter commands are useful when you want to use a filter only once and not save it. It changes visible contents of the library (views 1-2). filter unactivates all filters in the filters view, while live-filter is applied in addition to all currently activated filters.Filter all rock (anything with rock in genre tag) music from 80s-
:filter ~y1980-~grock
Filter all artists/albums/titles containing "sleepwalking"
Selecting Tracks Matching a Filter¶
Mark (select) all tracks with duration less than 2 minutesMark (select) all tracks which have been played at least once
These commands work in views 2-4.
FILES¶
cmus reads its configuration from 3 different places.$XDG_CONFIG_HOME/cmus/autosave
/usr/share/cmus/rc
$XDG_CONFIG_HOME/cmus/rc
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.Examples¶
Example status display script (See status_display_program option) can be found in /usr/share/doc/cmus/examples.ENVIRONMENT¶
CMUS_CHARSETCMUS_HOME
CMUS_SOCKET
HOME
http_proxy
USER
USERNAME
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 cmus-devel mailing list:
SEE ALSO¶
cmus-tutorial(7), cmus-remote(1)AUTHORS¶
cmus was mainly written by Timo Hirvonen <tihirvon@gmail.com>. Other contributers are listed in the AUTHORS file.This man page was written by Frank Terbeck <ft@bewatermyfriend.org>, Timo Hirvonen <tihirvon@gmail.com>, and Clay Barnes <clay.barnes@gmail.com>.
31/01/2010 | cmus |