Cmus complete guide

cmus — C* Music Player: Complete Guide

Starting cmus

cmus [options]

Do not use --listen to run multiple instances as the same user — it corrupts the metadata cache.

Step 1: Adding Music

Press 5 to open the file browser. Navigate with arrow keys, Enter to go into a folder, Backspace to go up. Press a on a file or folder to add it to your library.

cmus never moves, duplicates, or modifies your files. It only caches metadata like duration and artist. Adding a large folder can take a moment — watch the total duration counter in the bottom right climb as tracks are indexed.

To save manually: :save. cmus also saves everything automatically on quit.

You can also add directly from the command line:

:add ~/Music
:add -l ~/Music    # add to library explicitly
:add -p ~/Music    # add to playlist
:add -q ~/Music    # append to queue
:add -Q ~/Music    # prepend to queue

Supported formats depend on loaded input plugins. Supported playlist types: plain, .m3u, .pls. Supported URLs: Shoutcast (http://...), CDDA (cdda://...).

Step 2: Views

Press 1–7 to switch views.

Step 3: Playing Tracks

Press 2 to switch to the sorted library view. Use arrow keys to select a track and press Enter to play it.

Playback keys

Pressing z (previous) jumps to the beginning of the current track if the playback position is greater than rewind_offset (default 5 seconds). Set rewind_offset=-1 to always jump to the previous track.

Playback mode toggles

The status bar bottom-right shows active toggles — only “on” toggles are displayed. The full format is:

aaa_mode & play_sorted & play_library | volume | continue follow repeat shuffle

For sequential playback: C on, r off, s off.

r vs Ctrl + r

In cmus (C Musical Player), both r and Ctrl + r deal with repeating your music, but they operate on completely different scopes.

Here is the breakdown of how they work:

r (Toggle Repeat Row)

Pressing the lowercase r key toggles the overall Repeat mode for your current playback.

• What it does: When enabled, it tells cmus what to do when it reaches the end of the current track list, queue, or album. Instead of stopping when the music ends, it will loop back to the beginning of the list and keep playing.
• Visual Indicator: You will see repeat appear (or disappear) in the bottom right corner of your status bar.

Pressing **Ctrl and r** at the same time toggles the Repeat Current Track mode.

• What it does: It locks playback onto the single song currently playing. When the track finishes, it immediately starts over from the beginning, loop-playing that exact same song indefinitely.
• Visual Indicator: You will see aaa (or sometimes 1 depending on your version/theme configuration, though aaa is the standard cmus notation for “repeat artist/album/all track” sub-modes, specifically overriding to the single track) appear in the status bar.

Summary Reference

Volume

Volume can also be set via command: :vol 80%, :vol +5%, :vol -10%. Two arguments set left and right channels separately: :vol 80% 80%.

Step 4: The Queue

The queue lets you decide what plays next without interrupting the current track. It is temporary — once a track plays it is removed, and cmus returns to normal library order. The queue is not affected by shuffle.

When cmus is ready to play the next track and the queue is not empty, it removes the top entry from the queue and plays it. Once the queue is empty, playback resumes from the library or playlist.

Step 5: Playlists

Playlists are like a second library where you control the order manually. They persist across sessions and are useful for mixes, audio books, or any fixed sequence. For a temporary one-off sequence, use the queue instead.

Creating a playlist and adding tracks

1. Press 2 to go to the sorted library view
2. Navigate to a track and press y to add it to the active playlist
3. Press 3 to open the playlist view

Playlist keys (in view 3)

Playlist commands

Saving and loading

cmus auto-saves playlists to ~/.config/cmus/playlists/ on exit.

Playing from a playlist vs library

Changing to view 3 does not automatically make cmus play from the playlist. To switch playback source, press Enter on a playlist track. To switch without interrupting the current track, press M. The status bar shows playlist instead of library when playlist mode is active.

Step 6: Navigation

Step 7: Searching

Press / to search forward, ? to search backward. Type your query and press Enter. Press n for next result, N for previous.

In views 1–4 the query matches artist, album, and title tags. Use //WORDS to search only artists/albums in view 1, or only titles in views 2–4. Use ??WORDS for the same backwards. Files without tags are matched against the filename.

Searching also works in views 5–7.

Step 8: Marking and Editing Tracks

Editing commands affect marked tracks. If no tracks are marked, the selected track is used. You can only mark tracks in list views (2–4).

Examples:

:mark duration<120        # mark all tracks under 2 minutes
:mark play_count>=1       # mark all tracks played at least once
:mark genre="Jazz"        # mark all jazz tracks

Step 9: Filters

Filters temporarily hide tracks in library views (1 and 2) without removing them from the library. The :save command still saves all tracks regardless of active filters.

Filter types

Long expressions use & (and), | (or), ! (not), and parentheses for grouping.

Long filter string keys

Short filter keys

Filter commands

Filter examples

:filter genre="*rock*"&date>=1980
:filter ~y1980-~grock
:live-filter sleepwalking
:fset ogg=filename="*.ogg"
:fset 90s-ogg-mp3=date>=1990&date<2000&(ogg|filename="*.mp3")
:factivate ogg missing-tags
:factivate !ogg missing-tags

Step 10: Customisation

Press 7 to open the settings and keybindings view. Select any item with arrow keys and press Enter to edit it in the command line. Press Space to toggle boolean values directly.

Key binding commands

Valid contexts: common (all views), library (1–2), playlist (3), queue (4), browser (5), filters (6).

Always use -f when setting bindings in rc to avoid conflicts with autosave.

Examples:

:bind -f common q quit
:bind common w push filter artist=

Color scheme

:colorscheme solarized

Color schemes (*.theme) live in /usr/share/cmus/ or ~/.config/cmus/. Colors are saved to autosave — changing a theme file does not update colors automatically; reload with :colorscheme name.

Configuration Options

Set with :set option=value, toggle booleans with :toggle option, view current value with :set option.

Playback

Display

Library

Other

Library View Sorting

The tree view (1) sorts automatically using three levels:

1. Artist — alphanumerically by artist tag (or artistsort tag if present; smart_artist_sort ignores leading “The”)
2. Album — grouped by album name, sorted by date of first track, then alphabetically. Albums without a date appear at the top.
3. Track — by discnumber, then tracknumber, then filename

Compilations are handled specially. If albumartist or the ID3v2 TPE2 tag is set, it is used instead of the track artist. Otherwise cmus checks for compilation markers (Various Artists, VA, V/A, compilation=true, ID3v2 TCMP) and names the artist <Various Artists>. URLs show as <Stream>. Files with no artist/album tags show as <No Name>.

Format Strings

Used with format_current, format_playlist, format_trackwin, format_title, and their altformat_* equivalents (used when tags are absent).

Conditional syntax: %{?CONDITION?A?B} — renders A if condition true, B otherwise (B optional).

Printf-style width/alignment/padding is supported. Width can have a %-suffix for percentage of terminal width.

Examples:

:set format_trackwin= %02n. %t %{?y?(%y)}%= %d
:set format_current= %a - %l%! - %02n. %t%= %{bitrate}Kbps %g %y
:set format_playlist= %-25%a %-15%l %3n. %t%= %y %d

Sort Keys

Used with lib_sort and pl_sort. Space-separated list. Prefix with - to reverse order.

artist, album, title, tracknumber, discnumber, date, originaldate,
genre, comment, albumartist, filename, filemtime, play_count,
bitrate, bpm, codec, media, codec_profile,
rg_track_gain, rg_track_peak, rg_album_gain, rg_album_peak

Examples:

:set lib_sort=artist date album discnumber tracknumber
:set pl_sort=-date artist

Colors and Attributes

Colors are integers −1..255 or named values:

Attributes (combinable with |): default, standout, bold, reverse, underline, italic, blink.

Example:

:set color_win_cur=lightyellow
:set color_statusline_bg=gray
:set color_win_title_attr=bold

Command Reference

All cmus functionality is implemented as commands. Type : to enter command mode, Tab to autocomplete, ↑/↓ for history, Esc to cancel.

Playback

Seeking

Library and Queue

Filters and Marking

Utility

Playing Audio CDs

Requires the cdio input plugin.

:set device=/dev/cdrom
:add cdda://          # entire disc
:add cdda://2         # track 2 only
:add cdda://1-3       # tracks 1 to 3
:add cdda:///path/to/cd.cue/2-5    # from image file

Metadata is read from CD-Text first, then from CDDB (configure with :set input.cdio.cddb_url=...).

Files

The rc file is read on every startup and is the right place for bindings, format strings, and settings you always want applied. The autosave file stores runtime state (volume, position, library paths, shuffle/repeat state) and is overwritten on every quit — edit it only when cmus is closed.

Environment Variables

Relocating the library with pl_env_vars

pl_env_vars lets you store library paths using environment variables, making the library portable across machines or users:

:set pl_env_vars=HOME

Paths are then stored relative to $HOME. Multiple variables can be comma-separated. Takes effect on next restart.

D-Bus / MPRIS

cmus exposes /org/mpris/MediaPlayer2 on the bus name org.mpris.MediaPlayer2.cmus, implementing the MPRIS v2 spec. This allows desktop widgets, status bars, and media key handlers to control cmus.

Enable or disable: :set mpris=true / :set mpris=false

Step 11: Quit

Type :q and press Enter. cmus automatically saves your library, settings, playlists, and queue.

Further Reading

man cmus-remote
https://github.com/cmus/cmus/blob/master/Doc/cmus.txt
https://github.com/cmus/cmus/issues