cmus-tutorial(7)

📦
version 2.12.0 · 3 versions
, in alpine 3.24, arch rolling, debian trixie, nixos 26.05, nixpkgs unstable, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 NAME 💖

cmus — the C* Music Player tutorial, bestie edition ✨

Okay so you wanna learn cmus? Iconic choice, no cap. This is the whole walkthrough, and I'm holding your hand the entire way 🫶

🎀 CONTENTS 🎀

Here's the roadmap, so you know what's coming:

  • Step 1: Starting Cmus
  • Step 2: Adding Music
  • Step 3: Playing Tracks From The Library
  • Step 4: Managing The Queue
  • Step 5: The Playlists
  • Step 6: Find that track
  • Step 7: Customization
  • Step 8: Quit
  • Step 9: Further Reading

✨ Step 1: Starting Cmus ✨

When you first launch cmus — literally just type cmus in a terminal and hit Enter — it opens straight into the album/artist view, and it looks a lil something like this:

+---------------------------------------------------------------------+
| Library                    Empty (use :add)                         |
|                          |                                          |
|                          |                                          |
|                          |                                          |
|                          |                                          |
|                          |                                          |
|                          |                                          |
|                          |                                          |
|                                                                     |
| . 00:00                                       library | 100% | C    |
|                                                                     |
+---------------------------------------------------------------------+

This is the view where your artists and albums are gonna live 💅

🌸 Step 2: Adding Music 🌸

Press 5 to hop over to the file-browser view so we can actually put some music in here. You should see something like:

+---------------------------------------------------------------------+
| Browser - /home/jasonwoof                                           |
| ../                                                                 |
| Desktop/                                                            |
| MySqueak/                                                           |
| audio-projects/                                                     |
| audio/                                                              |
| bin/                                                                |
| config/                                                             |
|                                                                     |
| . 00:00                                       library | 100% | C    |
|                                                                     |
+---------------------------------------------------------------------+

Now vibe your way over to wherever your audio files are stored using the arrow keys, Enter and Backspace. To add music to your cmus library, arrow-key your way to a file or folder, highlight it, and press a. The way that pressing a also bumps you down to the next line?? So you can add a whole bunch of files/folders in a row without lifting a finger 😌 And it kicks off adding the file/folder you pressed a on to your library.

Heads up, this can take a hot minute if you added a folder with a LOT in it. As files get added, you'll see the second time in the bottom right go up — that's the total duration of all the music in your cmus library ⏳

Note: cmus does not move, duplicate or change your files. It just remembers where they are and caches the metadata (duration, artist, etc.)

Just to be safe, bestie, let's save. Type :save and press Enter 💾

Note: Cmus automatically saves your settings and library and everything when you quit, so you probably won't use the save command much.

👑 Step 3: Playing Tracks From The Library 👑

Press 2 to go to the simple library view. Should look a lil like this:

+---------------------------------------------------------------------+
| Library - 31 tracks (1:35:11) sorted by albumartist date album dis… |
| Flying Lizards         . Money (That's What I Want)           02:31 |
| Jason Woofenden        . VoR Theme                       2009 01:20 |
| Keali'i Reichel      06. Wanting Memories                1994 04:28 |
| Molly Lewis            . Tom Cruise Crazy                     03:13 |
| NonMemory              . pista1                          2009 03:18 |
| NonMemory            01. pista1                    2009-04-21 04:13 |
| Ray Charles          06. Halleluja I Love Her So              02:33 |
|                                                                     |
| . 00:00                           artist from library | 100% | C    |
|                                                                     |
+---------------------------------------------------------------------+

Use the up and down arrow keys to pick a track you wanna hear, then press Enter to play it 🎶

Here are the keys for controlling playback:

  • Press c to pause/unpause.
  • Press right/left to seek by 10 seconds.
  • Press </> to seek backwards/forwards one minute.
  • Press z to play the previous track, and b to play the next track.

cmus has some great options for controlling what plays next (if anything) when the track ends. The state of these settings lives in the bottom right corner. The first one shows what collection of tracks we're playing — shown here as artist from library. Press m to cycle through the different options for this setting 🔄

To the right of that (past the volume) cmus shows the state of four toggles. Only toggles that are "on" get shown, so right now we only see the C. Here they are:

  • [C]ontinue — if this is off, cmus will always stop at the end of the track. Toggle this by pressing shift-C.
  • [F]ollow — if this is on, cmus selects the currently playing track on track change. Press f to toggle it.
  • [R]epeat — if this is on (and continue is on), when cmus reaches the end of the group of tracks you're playing (the group you picked with the m key) it starts again from the beginning. Press r to toggle it.
  • [S]huffle or [&]lbum shuffle — if it's S, cmus picks a random order to play all tracks once; & does the same thing but for whole albums. Press s to toggle this option.

🦋 Step 4: Managing The Queue 🦋

Say you're listening to a song and you wanna line up which song plays next without interrupting the one currently playing. No problem, bestie 💅 Just go to the song you want to hear next (in any of the views) and press e. The queue is FIFO, meaning if you queue up another track, it plays after the one you already had queued up. First in, first out, periodt.

Note: The queue is not affected by the "shuffle" option described above.

Press 4 to view/edit the queue. This view works and looks a lot like the simple library view. The main difference? You can change the order of the tracks with the p and P keys. And you can press shift-D to remove a track from the queue.

When cmus is ready to play another track — that's when it's reached the end of a track and the "continue" setting is on — it removes the top entry from the queue and starts playing it ✨

💜 Step 5: The Playlists 💜

Playlists work like another set of libraries (like view 2) except that (like the queue) you manually set the order of the tracks. Super useful if you wanna create a mix of specific tracks, or if you wanna listen to an audio book without having the chapters play when you're playing from the library 🎧

Playlists live on view 3. But before we go there, let's add some tracks. Press 2 to go to the simple library view, go to a track you want, and press y to add it to a playlist. The only visual feedback you'll get that anything happened is that the highlight moves down one row. Add a few more so you've got something to work with.

Now press 3 to go to the playlist. You should see something like:

+---------------------------------------------------------------------+
| Playlist                   Default                            11:32 |
| * Default                | Flying Lizards     . Money (Th...  02:31 |
|                          | Jason Woofenden    . VoR T... 2009 01:20 |
|                          | Keali'i Reichel  06. Wanti... 1994 04:28 |
|                          | Molly Lewis        . Tom Cruis...  03:13 |
|                          |                                          |
|                          |                                          |
|                          |                                          |
|                                                                     |
| . 00:00                                       library | 100% | C    |
|                                                                     |
+---------------------------------------------------------------------+

Just like the queue, you can use the p, P and D keys to move and delete tracks from the playlist.

Note: Changing the view (e.g. by pressing 3) does not affect what cmus will play next. To put cmus into "play from the playlist" mode, press Enter on one of the tracks in the playlist. And to switch modes without interrupting the currently-playing song, you can press shift-M.

🔍 Step 6: Find that track 🔍

This step shows the various ways you can find the track(s) you're looking for, because scrolling forever is not the vibe.

Search: Press 2 to make sure you're on the simple library view, then press / to start a search. Type a word or two from the track you're looking for. cmus will search for tracks that have all those words in them. Press enter to get the keyboard out of the search command, and n to find the next match 🔎

Tree View: Press 1 to select the tree view. Scroll to the artist, press space to show their albums, scroll to the album you want, then press tab so the keyboard controls the right column. Press tab again to get back to the left column 🌳

Filters: See the reference manual (see Further Reading below) for a detailed description on how to quickly (and temporarily) hide most of your music.

🎀 Step 7: Customization 🎀

Cmus has some very cool settings you can tweak, like changing the way tracks are displayed (e.g. to display disk numbers), enabling replaygain support, or changing the keybindings 💅

Press 7 for a quick overview of the current keybindings and settings.

To change a setting or keybind, just select it (up/down keys) and press enter. This puts the command for the current setting in the command line (bottom left of your screen), which you can edit to put in a new value/key ✏️

Please see the reference manual (see Further Reading below) for a detailed description of all the commands and settings available.

🌈 Step 8: Quit 🌈

When you're done, type :q and press Enter to quit. This will save your settings, library, playlist and queue 💾✨

✨ Step 9: Further Reading ✨

okay bestie so you've got the basics DOWN and honestly? proud of you 🫶 but cmus has a whole entire reference manual and now that you know what's what, it's actually gonna make sense. no cap.

try running this in your terminal:

man cmus

if that one isn't installed on your system, no stress — just crack open cmus.txt from the Doc directory instead 💖 or like, read the freshest version online:

https://github.com/cmus/cmus/blob/master/Doc/cmus.txt

and listen, there is SO much more waiting for you that we didn't even get to in this tutorial — like loading and saving playlists, and controlling cmus remotely with cmus-remote, etc. the lore goes deep, iykyk 💅✨

go forth and slay your music library, you absolute icon 👑

this lil tutorial is cmus, from the cmus-tutorial(7) manual page — last touched on 14/02/2010 💜 so yeah she's vintage, but she ate and left no crumbs.

📦 where this page comes from