My increasingly adequate website

cmus, a really quick guide

cmus in a terminal window.
Artists listed on left, tracks on right.
A screenshot of cmus.


Reading a post about the demise of Songbird's Linux client, one comment stood out. Its author complained that Songbird was too bloated and slow and, as such, was better off dead. This commenter recommended a terminal-based player called cmus. I decided to take a look. I'm glad I did.

cmus is efficient, functional, and friendly. To ease your switch to cmus, I've written this page. It has a few reasons why I think cmus excels, as well as instructions on getting cmus up and running quickly.

Selling points for cmus

There are many reasons to use cmus:

Getting cmus up and running in 90 seconds

Start cmus by typing cmus at the command line. Once it's running, you'll need to add your music to its library.

We use the keyboard to bend cmus to our will. cmus uses vi-like keybindings. Simple commands require a single key press, while complex directives like adding music from a directory demands a bit more typing. To begin such a complex command, type :. Notice that a colon and a blinking text-input prompt appear at the bottom of the screen. The program is waiting for a command. To add your music, type :add followed by the path to your music, e.g., :add /home/username/music/albums, and press enter.

The time it takes cmus to import your music depends on how many files you have pointed it to, since cmus reads -- but never alters -- the metadata for each track. If you make changes to songs' metadata, do :update inside cmus. If I've added new files, I typically re-do :add /home/username/music/albums followed by :update. This is much better than waiting for Rhythmbox or GNOME Music to eventually, hopefully, notice the new music you've added to your watched folders. (And that kind of inconvenience is just the tip of the iceberg. The last time I made the mistake of opening Rhythmbox, it reverted the metadata of hundreds of songs back to what was stored in its months-old cache, even though the changes existed because I had spent many hours carefully tweaking this metadata.)

Once your songs are imported you probably would like to play them. Doing so is as simple as using the arrow keys, vi-keys, the page up and page down keys to navigate through the list of artists. When you find an artist, press space to open up a list of albums, or press tab to switch to the list of tracks for the selected artist. Use enter to play a track. To change albums or artists, just press tab to switch back to the artist / album pane and begin the process again.

That's really all there is to using cmus in a basic way. Still, you can and should do much more. So let's start by looking at some more keys you can use to command cmus.

Useful keys

I use these keys most times I run cmus. They're configurable, but these are the defaults.

v - stop playback

b - next track

z - previous track

c - pause playback

s - toggle shuffle (read about the m key below if you're going to use shuffle)

m - toggles the "aaa mode." aaa stands for artist, album, or all. Controls whether cmus shuffles between songs from an artist, album, or from all your songs. You can see the currently set "aaa mode" in the bottom right, next to where the display of the continue, repeat, and shuffle settings.

x - restart track

i - jump view to the currently playing track (handy when in shuffle mode and follow is off.)

f - toggle follow. When follow is on, the selection bar will jump to the next playing track. For example, in shuffle mode, this controls whether the selection bar jumps between artists or not. You can manually focus on the playing track by pressing i, as noted above. If follow is on, an 'f' appears in the bottom right, in the area where continue, repeat, and shuffle are displayed.

/ - searching cmus works as in many Unix programs. Typing /, a string, and enter will find the first instance of that string in your current view. Press n to go to the next string, N to go to the previous. cmus's search isn't case sensitive and is quite smart. For example, a search for damned insurrection will return Bulldozer's "Insurrection of the Living Damned".

- - reduce the volume by 10%

+ - increase the volume by 10%

Conclusion: further guidance

There's more cmus to discover. cmus incorporates a file browser, a playlist view, and some other neat stuff.

Because cmus lacks menus and icons, at first it's more involved than using a GUI program. Fortunately, cmus is well-documented. New users should consult the excellent cmus tutorial, only a bit of which is replicated here. This tutorial will walk them through the process of setting up cmus and explains the basic use of most features. This tutorial can be accessed in a terminal by typing man cmus-tutorial. The cmus tutorial is also available online. Fuller documentation is found in cmus's man page, which again can be read by typing man cmus. The cmus man page is also available online. Between these two documents, new users should be well on the way to learning how to use a music player that's ultimately easier and more feature-rich than most alternatives.

P.S. Want something similar to cmus, but even simpler? Try siren: a text-based audio player.