My increasingly adequate website

A really quick guide to cmus

A screenshot of the cmus
A shot of cmus.


While reading comments on the blog post announcing the demise of Songbird's Linux client, I found one that stood out. Its author complained that Songbird was too bloated and slow and, as such, was better off dead. This commenter went on to recommend a terminal-based player called cmus. My interest was piqued. I decided to take a look. I'm glad I did.

cmus is one of the most efficient, functional, and friendly pieces of software I've used. You should try it. To encourage and ease your switch to cmus, I've written this page. It has a few reasons why I think cmus excels, as well as brief instructions on getting cmus up and running quickly.

Selling points for cmus

There are many compelling 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, press the : key. Notice that a colon and a blinking text-input prompt have appeared at the bottom of the screen. The program is waiting for instructions. 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 has to read -- but never alter -- the metadata for each track. At this juncture it's worth noting that cmus stores this metadata in /home/username/.cmus/cache. If you change your songs' metadata or filenames but cmus isn't reflecting that or is complaining that a track is missing, you can delete the cache and then re-add your music to your library. This is much better than waiting for Banshee or 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: recently I fired up Rhythmbox for the first time in a few months. It then reverted the metadata of hundreds of my songs back to what was stored in its months-old cache, even though during the interim I had spent many hours tweaking this metadata. Friends don't let friends use Rhythmbox. And we're friends, right?

Once your songs are imported you probably would like to play them. Doing so is as simple as using the arrow keys or the page up and page down keys to navigate through the list of artists and pressing tab to switch to the list of tracks for the artist you've selected. Play a track with the enter key. 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 playing your jams in cmus. Still, you probably want more control. Below are the key commands to do most anything you'd ever need a music player to do.

Useful keys

These are the keys I use most times I run cmus. If you want to do even more with cmus or change the keybindings, read the help I link to in this page's conclusion.

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. If artist mode is on cmus will shuffle only between songs by the playing artist. In album mode cmus will shuffle between songs on the playing album. If all mode is on, cmus will shuffle between every song in your library. 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)

/ - searching cmus works as in many Unix programs. Typing slash, a string, and enter will find the first instance of that string in your library. 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; a search for damned insurrection will return Bulldozer's "Insurrection of the Living Damned" (rad tune).

- - 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. It can also be referenced online here. Fuller documentation is found in cmus's man page, which again can be read by typing man cmus or accessed online at this page. 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.