| 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. It has got completely configurable keybindings and it can be controlled from the outside via cmus-remote(1).OPTIONS¶
--listen ADDRListen to ADDR (UNIX socket) instead of
~/.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.
List available plugins and exit.
Keep cursor always visible. This is useful for
screen readers.
Display usage information and exit.
Display version information and exit.
VIEWS¶
There are 7 views in cmus. Press keys 1-7 to change active view.Display all tracks in so-called
library. Tracks are sorted artist/album tree. Artist sorting is done
alphabetically. Albums are sorted by year.
Displays same content as view 1, but as a
simple list which is automatically sorted by user criteria.
Displays editable playlist with optional
sorting.
Displays queue of tracks which are played
next. These tracks are played before anything else (i.e. the playlist or
library).
Directory browser. In this view, music can be
added to either the library, playlist or queue from the filesystem.
Lists user defined filters.
Lists keybindings, unbound commands and
options. Remove bindings with D or del, change bindings and
variables with enter and toggle variables with space.
COMMAND LINE¶
Everything in cmus is implemented as commands which can be typed at command line or bound to a key. To enter command mode type :. To execute a command press ENTER or to cancel press ESC. 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).# 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.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).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 withing the list. Note that moving is disabled if the view is auto-sorted (see lib_sort and pl_sort options).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 repeat shuffle
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 win-activate
E win-add-Q
a win-add-l
y win-add-p
e win-add-q
G, end win-bottom
down, j 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
D, delete win-remove
i win-sel-cur
space win-toggle
g, home win-top
k, 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.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.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://...).
Supported playlist: plain, .m3u, .pls.
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.
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.
Changes the current working directory. Changes
the directory displayed in browser view too.
Remove all tracks from the specified view or
the current view.
- -l
- clear library
- -p
- clear playlist
- -q
- clear play queue
Change color scheme. Color schemes are found
in /usr/share/cmus/ or ~/.cmus/ and have .theme filename
extension.
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.
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.
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.
Define (or replace existing) filter and add it
to filters view (6).
Invert the marking of tracks in playlist and
queue views. See mark and unmark.
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 a playlist to the specified view or to
the current view.
- -l
- load to library views
- -p
- load to playlist view
Queue NUM (default 1) random albums from the
library. See also tqueue.
Mark tracks in playlist and queue view by
using a filter expression.
Skip to the next track.
Toggle pause.
Play the given track, or, if none is
specified, [re]play the current track from the beginning.
Skip to the previous track.
Stop playback.
Go to previously used view.
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.
Exit cmus.
- -i
- ask before exiting
Redraw the terminal window.
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 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).
If a search pattern has been entered before,
search forward for the next match in the current view. See SEARCHING
above.
If a search pattern has been entered before,
search backwards for the previous match in the current view. See
SEARCHING above.
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 value of an option. See
OPTIONS.
Display option value. Vim compatible set
<option>? is also supported.
Execute a command via /bin/sh.
Show key binding.
Reshuffle the shuffle lists for both library
and playlist views.
Read and execute commands from
<filename>.
Toggle value of a toggle-able option (all
booleans and tristate aaa_mode).
Queue NUM (default 1) random tracks from the
library. See also lqueue.
Remove a key binding. Use tab to cycle through
bound keys.
-f
Don't throw an error if the binding is not
known
Unmark all tracks (see mark).
Update track metadata cache
(~/.cmus/cache).
Switches active view.
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%
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.
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
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
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
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
Goto bottom of the current window.
Goto down one row in the current window.
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.
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.
Activate next window. Only relevant in view
1.
Goto down one page in the current
window.
Goto up one page in the current window.
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.
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.
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.
Goto top of the current window.
Goto up one row in the current window.
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.
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.Reshuffle playlist when end of shuffle list is
reached.
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.
Alternative format string for the line
displaying currently playing track.
Alternative format string for the list views
(2-4).
Alternative format string for terminal title.
NOTE: not all terminals support changing window title.
Alternative format string for the tree view's
(1) track window.
Size of player buffer in seconds.
Command line background color.
Command line foreground color.
Color of error messages displayed on the
command line.
Color of informational messages displayed on
the command line.
Color of the separator line between windows in
view (1).
Status line background color.
Status line foreground color.
Background color of the line displaying
currently playing track.
Foreground color of the line displaying
currently playing track.
Window background color.
Color of currently playing track.
Background color of the selected row which is
also the currently playing track in active window.
Foreground color of the selected row which is
also the currently playing track in active window.
Color of directories in browser.
Window foreground color.
Background color of the selected row which is
also the currently playing track in inactive window.
Foreground color of the selected row which is
also the currently playing track in inactive window.
Background color of selected row in inactive
window.
Foreground color of selected row in inactive
window.
Background color of selected row in active
window.
Foreground color of selected row in active
window.
Background color of window titles (topmost
line of the screen).
Foreground color of window titles (topmost
line of the screen).
Ask for confirmation before executing
:run
Continue playing after current track
finishes.
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.
Format string for the line displaying
currently playing track.
Format string for the list views (2-4).
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).
Format string for terminal title.
NOTE: not all terminals support changing
window title.
Format string for the tree view's (1) track
window.
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).
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.
Default character set to use for ID3v1 and
broken ID3v2 tags.
NOTE: This is used only if the tag is not
valid UTF-8.
Sort keys for the sorted library view
(2).
Name of output plugin.
Sort keys for the playlist view (3). Empty
value disables sorting and enables manually moving tracks.
Play tracks from the library instead of
playlist.
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 after all tracks played.
Repeat current track forever.
Enable Replay Gain. Default is
"disabled". Set to "track", "album",
"track-preferred" or "album-preferred".
Use replay gain limiting when clipping.
Replay gain preamplification in
decibels.
Resume playback on startup.
Display hidden files in browser.
Display remaining time instead of elapsed
time.
Play in shuffled order. Shuffle works in the
library views (1-2) and playlist view (3).
Use software volume control.
NOTE: You should probably set this to false
when using ao as output_plugin to output to wav files.
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.
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.
Colors¶
Color is integer in range -1..255.default
black, red, green, yellow, blue, magenta,
cyan, gray
darkgray, lightred, lightgreen, lightyellow,
lightblue, lightmagenta, lightcyan, white
Format Strings¶
Format strings control display of tracks in library, playlist and play queue views.%a %{artist}
%A %{albumartist}
%l %{album}
%D %{discnumber}
%n %{tracknumber}
%t %{title}
%g %{genre}
%c %{comment}
%y %{date}
%d %{duration}
%f %{path}
%F %{filename}
%{bitrate}
%{codec}
%{rg_track_gain}
%{rg_track_peak}
%{rg_album_gain}
%{rg_album_peak}
%=
%{bitrate}
%{codec}
%{rg_track_gain}
%{rg_track_peak}
%{rg_album_gain}
%{rg_album_peak}
start align right (use at most once)
%%
literal %
:set format_trackwin= %02n. %t (%y)%= %d
:set format_current= %n. %-30t %40F (%y)%= %d
:set format_current= %a - %l - %02n. %t%= %{bitrate}Kbps %g %y
:set format_playlist= %f%= %6{rg_track_gain} dB %8{rg_track_peak}
:set format_playlist= %-25%a %-15%l %3n. %t%= %y %d
Sort Keys¶
Sort option (lib_sort, pl_sort) value is space separated list of the following sort keys:artist, album, title, tracknumber, discnumber,
date, genre, comment, albumartist, filename, filemtime, bitrate, codec,
rg_track_gain, rg_track_peak, rg_album_gain, rg_album_peak
PLUGIN OPTIONS¶
dsp.alsa.devicePCM device for ALSA plugin, usually
"default".
Mixer channel for ALSA Plugin, usually
"pcm", "master" or "headphone". To see all
possible values run "alsamixer" or "amixer".
Mixer device for ALSA plugin, usually
"default".
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.
Buffer size, default is 16kB (but you may want
to try bigger values if you experience buffer under-runs).
Output driver for libao plugin. Example
values: "alsa09", "esd", "irix",
"oss", "sun", "aixs", "wav".
NOTE: of the file output drivers only
"wav" is supported.
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.
Output directory for libao plugin, default is
your home directory. Used only if dsp.ao.driver is
"wav".
PCM device for OSS plugin, usually
/dev/dsp.
Mixer channel for OSS Plugin, "pcm"
or "master".
Mixer device for OSS plugin, usually
/dev/mixer.
Address of RoarAudio server. Defaults to
internal defaults. Can be UNIX, TCP/IP or DECnet address.
Role for stream. May be used by the server to
apply additional defaults.
PCM device for Sun plugin, usually
/dev/audio.
Mixer channel for Sun Plugin, usually
"master".
Mixer device for Sun plugin, usually
/dev/mixer.
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*"
Strings¶
- long
- filename, artist, album, title,
genre, comment, codec
Comparators: = and != (not equal)
- short
- ~f, ~a, ~l, ~t, ~g,
~c
Comparators: none
Integers¶
- long
- discnumber, tracknumber, date (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)Defining Filters¶
Filters can be defined with fset command. User defined filters appear in the filters view (6).:fset ogg=filename="*.ogg"
:fset
90s-ogg-mp3=date>=1990&date<2000&(ogg|filename="*.mp3")
Activating Filters¶
factivate changes visible contents of the library (views 1-2).:factivate ogg missing-tags
:factivate !ogg missing-tags
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
date>=1980&genre="*rock*"
:filter ~y1980-~grock
:live-filter sleepwalking
Selecting Tracks Matching a Filter¶
Mark (select) all tracks with duration less than 2 minutes:mark duration<120
FILES¶
cmus reads its configuration from 3 different places.This is the first file cmus loads. cmus saves
its state on exit to this file so you shouldn't edit it.
If the autosave file didn't exist, this file
is read instead.
Static config file. This file is read
immediately after the autosave file, and is never modified by cmus. You can
override auto-saved settings in this file. This file is not limited to
options, it can contain other commands too.
Color Schemes¶
There are some color schemes (*.theme) in /usr/share/cmus. You can switch them using the :colorscheme command. You can put your own color schemes to ~/.cmus.Examples¶
Example status display script (See status_display_program option) can be found in /usr/share/doc/cmus/examples.ENVIRONMENT¶
CMUS_CHARSETOverride cmus character set (default: `locale
charmap`).
Override cmus config directory (default:
$HOME/.cmus).
Full path of the user's home directory.
URI of the proxy to use for HTTP
requests.
Name of the user running cmus.
Fallback for USER.
BUGS¶
After a crash last lines of ~/cmus-debug.txt might contain useful information. The file exists only if you configured cmus with maximum debug level ( ./configure DEBUG=2).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.| 31/01/2010 | cmus |