cmus - C* Music Player
cmus [options]
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).
Listen to ADDR (UNIX socket) instead of /tmp/cmus-$USER.
|
Note
|
Don't use this option to run multiple instances as same user. That would corrupt track metadata cache. |
List available plugins and exit.
Display usage information and exit.
Display version information and exit.
There are 6 views in cmus. Press keys 1-6 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.
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
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.
In view 5 words are compared to filename without path.
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 copies tracks to the library (1-2)
y copies tracks to the playlist (3)
e appends tracks to the play queue (4)
E prepends tracks to the play queue (4)
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).
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 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.
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 file/dir/url/playlist to the specified view or the current view.
add to library
add to playlist
add play queue
prepend to play queue
URL is a Shoutcast stream (http://…).
Supported playlist: plain, .m3u, .pls.
Add a key binding.
overwrite existing binding
Use tab to expand contexts, keys and commands. Command is any command listed in this section.
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.
clear library
clear playlist
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.
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.
Load a playlist to the specified view or to the current view.
load to library views
load to playlist view
Mark tracks in playlist and queue view by using a filter expression.
Skip to the next track.
Toggle pause.
If stopped, start playing the current song; if already playing seek to beginning of the current song.
Skip to the previous track.
Stop playback.
Exit cmus.
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.
save library views
save playlist view
If no filename given the old filename is used.
If a search pattern has been entered before, search forward for the next match in the current view. See GENERAL USAGE above.
If a search pattern has been entered before, search backwards for the previous match in the current view. See GENERAL USAGE above.
Seek to absolute or relative position. Position can be given in seconds, minutes (m) or hours (h).
:seek -1m
:seek +5
:seek 1h
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.
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).
Remove a key binding. Use tab to cycle through bound keys.
Don't throw an error if the binding is not known
Unmark all tracks (see mark).
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.
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) and filters (view 6) 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.
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.
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 tittle. 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.
Format string for the line displaying currently playing track.
Format string for the list views (2-4).
Format string for terminal tittle.
|
Note
|
not all terminals support changing window title. |
Format string for the tree view's (1) track window.
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.
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).
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.
Color is integer in range -1..255.
The following color names are recognized:
default
black, red, green, yellow, blue, magenta, cyan, gray
darkgray, lightred, lightgreen, lightyellow, lightblue, lightmagenta, lightcyan, white
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 Characters:
artist
album
disc number
track number
title
genre
year
duration
path and filename
filename
start align right (use at most once)
literal %
You can use printf style formatting (width, alignment, padding). To see current value of an option type :set option=<TAB>.
Examples:
:set format_trackwin= %02n. %t (%y)%= %d :set format_current= %n. %-30t %40F (%y)%= %d
Sort option (lib_sort, pl_sort) value is space separated list of the following sort keys:
artist, album, title, tracknumber, discnumber, date, genre, filename
PCM 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".
Buffer size, default is 8192 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.
PCM device for Sun plugin, usually /dev/audio.
Mixer channel for Sun Plugin, usually "master".
Mixer device for Sun plugin, usually /dev/mixer.
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.
Filter expression is list 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.
filename, artist, album, title, genre
Comparators: = and != (not equal)
discnumber, tracknumber, date (year), duration (seconds)
Comparators: <, <=, =, >=, >, !=
tag (true if track has tags), stream (true if track is a stream)
Filters can be defined with fset command. User defined filters appear in the Filters view (6).
:fset ogg=filename="*.ogg"
:fset 90s-ogg-and-mp3=date>=1990&date<2000&(ogg|filename="*.mp3")
:filter date>=1980&genre="*rock*"
: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.
:mark duration<120
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.
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.
Example status display script (See status_display_program option) can be found in /usr/share/doc/cmus/examples.
After a crash last lines of /tmp/cmus-debug might contain useful information. The /tmp/cmus-debug 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 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 <frank.terbeck@rwth-aachen.de>, Timo Hirvonen <tihirvon@gmail.com>, and Clay Barnes <clay.barnes@gmail.com>.