Command Line Options

See cmus --help for more information.

Remote Control

CMus can be controlled via UNIX-socket using cmus-remote command. This is very useful feature because it allows you control CMus without having to switch to the desktop where CMus window is.

See cmus-remote --help for more information.

Views

There are 6 views in cmus:

• Artist/Album/Track Tree View (1)
• Shuffle List (2)
• Sorted List (3)
• Play Queue (4)
• Directory Browser (5)
• Filter View (6)

To switch between the views use keys '1' - '5'. Views 1-3 display current playlist. View 3 can be sorted (see sort option).

View 4 displays play queue. Tracks in the play queue are played first and removed from the queue immediately after playing starts. After last track from play queue has been played CMus starts playing tracks in the playlist.

View 5 allows you to browse filesystem, add tracks to playlist, enqueue tracks, delete files and even play tracks directly from the browser. You can also 'cd' into a playlist.

View 6 displays user defined Playlist Filters.

Normal Mode

Command Mode

Press ':' any time to enter command mode. The command mode works much like VIM's command mode. Tabulator expansion works for files/dirs, commands and options. There's command history too (up/down arrow keys). Press 'ESC' to leave command mode and return to Normal Mode.

You don't have to type whole command name if it is unambiguous. For example :a some-file.mp3.

:set format_trackwin= %02n. %t (%y)%= %d
:set format_current= %n. %-30t %40F (%y)%= %d

ID3 Tags

Some MP3s encode tags using different character set than specified in the frame. In other words those MP3s are broken but because this is so common problem cmus has an option (mad.charset) to change character set used for those broken MP3s.

You need to edit ~/.config/cmus/config manually, this can't be set using :set command. Default value is ISO-8859-1.

mad.charset = "cp1251"

Note: If you change this option you need to remove ~/.cache/cmus/trackdb.* files because they contain tags encoded in the old character set.

Searching

WORDS is list of words separated by spaces. Search is case insensitive and works in every view.

In views 1-4 words are compared to artist, album and title tags. Use //WORDS and ??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.

Streaming

CMus supports Shoutcast/Icecast streams (Ogg and MP3). To add stream to playlist use :add command or cmus-remote.

:add http://example.com/path/to/stream

Playlist Filters

Add filters using :fset command, select filters with space and then apply selected filters by pressing enter. Only tracks matching the activated filters will be shown in the playlist (views 1-3). Filters do not change the actual playlist content, i.e. :save command will still save all tracks to playlist file whether they are visible or not.

Strings are case insensitive. ? matches exactly one character and * zero or more characters. To match literal '?' or '*' you need to escape it with backslash ('\?' and '\*', to get literal backslash use '\\').

Integers are non-negative and -1 means the value is not set. For example date=-1 tests if date is not set.

Filters are separated with & (and) or | (or). Parenthesis can be used to group expressions and ! (not) inverts expression value.

Filter names are case sensitive and can contain only these characters: a-zA-Z0-9_-

Sometimes you may want to set temporary playlist filter which you only use once (you don't want to add it to the filter list). Use :filter to set temporary filter or disable filtering if no argument given.

:fset ogg=filename="*.ogg"

# use the filter above, user defined filters are like booleans
:fset ogg-rock=ogg&genre="*rock*"

# not 80s music unless artist is Iron Maiden
:fset foo=!(date>=1980&date<1990)|artist="iron maiden"

# regular files, not streams
:fset files=!stream

# temporarily filter ogg files or streams
# 'ogg' is user defined filter (see above)
:filter ogg|stream

# disable any filters
:filter

Running Programs

You can execute external commands for the currently selected files by executing :run command. Playlist view (1, 2 or 3) must be active when running commands. In view 1 you can run any command for files of the selected track, album or artist. In views 2 and 3 command is executed for the only selected file, of course. CMus will ask confirmation if there are more than one selected files unless confirm_run is false.

{} in the command is replaced with the selected files. If the command doesn't contain {} the selected files are automatically appended to the command. /bin/sh compatible quoting are supported (single/double quotes and escaping with \).

Both stdout and stderr are redirected to /dev/null and stdin is closed so you can't run interactive text mode programs. GUI programs should work just fine.

# rm -f file1.ogg file2.ogg
:run rm -f

# tagger -uniq -date 2004 file1.ogg file2.ogg
:run tagger -uniq -date 2004

# cp file1.ogg file2.ogg /tmp
:run cp {} /tmp/

Status Display

CMus can run external program which can be used to display player status on desktop background (using root-tail for example), panel etc.

For example if you use WMI you can write a script that displays currently playing file on the wmi statusbar using wmiremote command:

:set status_display_program=cmus-status-display

To disable status display set status_display_program to empty string.

#!/usr/local/bin/bash
#
# cmus-status-display
#
# Usage:
#   in cmus command ":set status_display_program=cmus-status-display"
#
# This scripts is executed by cmus when status changes:
#   cmus-status-display key1 val1 key2 val2 ...
#
# All keys contain only chars a-z. Values are UTF-8 strings.
#
# Keys: status file url artist album discnumber tracknumber title date
#   - status (stopped, playing, paused) is always given
#   - file or url is given only if track is 'loaded' in cmus
#   - other keys/values are given only if they are available
#  

output()
{
        # write status to /tmp/cmus-status (not very useful though)
        echo "$*" >> /tmp/cmus-status 2>&1

        # WMI (http://wmi.modprobe.de/)
        #wmiremote -t "$*" &> /dev/null
}

while [[ $# -ge 2 ]]
do
  eval _$1=\"$2\"
  shift
  shift
done

if [[ -n $_file ]]
then
        output "[$_status] $_artist - $_album - $_title ($_date)"
elif [[ -n $_url ]]
then
        output "[$_status] $_title"
else
        output "[$_status]"
fi

User Interface Colors

Change color_* options to customize colors.

Example:

:set color_statusline_bg=4

Tip: type :set color_<tab> to cycle through all color option variables.

Keybindings

Use :bind context key command to bind a key and :unbind context key to remove existing keybinding. Use tab to cycle through contexts, keys and functions.

# make control-h toggle showing hidden files
:bind browser ^H toggle_show_hidden

# seek 1 minute back / forward
:bind common H :seek -1m
:bind common L :seek +1m

# remove binding for F1 key (help by default)
:unbind common F1

Files

~/.config/cmus/config

configuration options

~/.config/cmus/filters

playlist filters

~/.config/cmus/keybindings

keybindings

~/.config/cmus/playlist.pl

automatically saved playlist

~/.cache/cmus/trackdb.dat, ~/.cache/cmus/trackdb.idx

cached tags

~/.cache/cmus/ui_curses_cmd_history

command mode history

~/.cache/cmus/ui_curses_search_history

search mode history

You can override location of these files by setting XDG_CONFIG_HOME and/or XDG_CACHE_HOME environment variables.

Bugs

If you configured cmus with DEBUG=2 then debugging information will be written to /tmp/cmus-debug file. After a crash last lines of these files should contain useful information.

Author

Timo Hirvonen <tihirvon AT gmail.com>