Howto: Use cplay like a pro

I’ve been talking big lately, trying to endorse the use of old, outdated computers as torrent slaves or multimedia centers, but I haven’t done much to explain the nuts and bolts of some of the software I’m pushing.

Well, that’s got to change. I’m making a point of using some of the console programs and utilities I mention, and I’m putting together notes to myself (and other folks, of course). It’s only fair: If I’m going to persuade you to use your old 120Mhz Pentium Compaq 1020 as a music station, I need to avoid leaving you at the terminal prompt, without a clue of what to do next.

Console programs aren’t like normal GUI-driven programs, for the most part. If I set you down in front of any generic GTK-style application and give you a mouse, you’d probably have it all figured out — from its mission to its mechanics — in the space of less than an hour. There’s a common look and style between Word and Firefox and Blender and Deluge, and that helps you get comfortable with it.

Terminal-driven applications are much more intimidating. Now, instead of just the mouse and a maybe a menu bar, you’ve got 104 keys you could press, and any one of them might trigger a catastrophe. Plus key combinations, and in some cases, double and triple key combos. No menus sometimes. Sometimes it’s just a blank, black box and a blinking cursor — with no obvious relationship between how it works and how to get it working.

It’s enough to drive a person back to X.

Enough jibba-jabba. I’m using cplay these days, mostly because it’s not as common a choice as mpd plus ncmpc, and it has a little less intuitive layout than mp3blaster. If you need something more versatile, go with the former. If you need something more obvious, go with the latter. cplay falls somewhere in the middle — not ornate, but not as multifaceted either.

cplay is a lightweight and comfortable way of playing tunes without going overboard, and yet at the same time it’s as flexible and comprehensive as you’re willing to make it. cplay is a frontend, which means it doesn’t really do the dirty work of playing your music. Instead, it handles the starting and stopping, the volume control, the sequencing and searching.

The actual grunt work is handled by subordinate programs like ogg123 (part of vorbis-tools) and mpg123 (there are more options on the cplay package page). Unless I’m mistaken, vorbis-tools is installed by default, but you’ll need mpg123 or something like it if you want mp3 playback. So if nothing comes out of the speakers the first time you use it, make sure you have something available that can handle your tunes.

When you start it up, you get this.

Just a directory structure. If you didn’t know any better, you’d think you were using clex or something. And really, it works much the same way. Navigate to your music directory using the enter key to move through folders. The backspace key jumps up to the parent directory.

You might feel that without some sort of directory tree, it can get a little tedious navigating between directories. Pressing “o” lets you jump to a directory, but there’s also a bookmark system to help navigation. Pressing “m” gives you the opportunity to assign a key letter to the directory you’re presently viewing. Jump back to that directory from anywhere by pressing the apostrophe, and repeating the letter. Bookmarks aren’t saved between sessions, though.

After that, cplay is very simple in principle. Press enter on any supported audio title, and cplay will start playing it. When that title is over, it will stop. Pressing enter on another title, while it’s still playing the last one, will cause it to jump to the new title without finishing the old one.

That’s pretty straightforward. Now here’s where cplay goes from functional to flexible. Press the Tab key.

Now you’re looking at a playlist screen. Tab again takes you back to the directory structure. You can add files and directories to the playlist by pressing the “a” key. You can select a specific array of files and folders with the spacebar, and each one is marked with a hash symbol.

You’re free to bounce back and forth between the directory structure and the playlist as much as you want, and add as many songs and directories as are practical.

To manage your playlist, use the “m” and “M” keys to shift things up and down, and “d” to remove a track, “s” to shuffle and “S” to sort it. If you decide to dump it all, press “D” and you start fresh.

Now let’s take it for a spin. Build a playlist and press enter on a song. The tunes should start at the track you highlighted.

You can control playback with “n” and “p” — next and previous. The left and right arrows seek through the song, backward and forward respectively.

The “x” key stops play and the “z” key pauses. They both seem to have the same effect, but they’re slightly different: Where “z” pauses the client program (ogg123 or mpg123 or what have you), “x” actually stops it. Pressing “z” or “x” again causes the audio to pick up at the exact same point, so the effect is the same. But if you watch htop while you’re doing it, you’ll see “x” has a different effect on your process list.

One of the nicest things about cplay is the volume control. Instead of an up-down slider control, the number keys 1 through 0 jump straight to a proportional volume level. By default cplay changes the Master volume control; that I find a little presumptuous, so I usually start cplay with the -v flag, which tells it to use PCM instead.

cplay handles the common m3u playlist format too. To save the current playlist, press “w” and you’ll be prompted for a filename, which is automatically suffixed with m3u, and should be accessible from just about any other common audio player. To open a playlist in cplay, add it like a normal track, by pressing “a” while it’s highlighted in the file list.

And just so you know: Pressing “h” at any time brings up a brief help screen.

cplay does a lot of other things too. Pressing the exclamation point lets you issue a shell command, without interrupting the music and with a “$@” variable for the selected file. I haven’t had a lot of luck with that though, because issuing just about any command tends to kill cplay (but not the client player, so the music goes on πŸ™‚ ). It’s worth noting though, and it might not be a problem if you’re using another distro.

You can also build regex searches, if you’re keen on culling out a certain array of filenames. You can search recursively and invert searches as well. When your playlist or directory list becomes enormous and hard to find things, you can isearch through the names with the CTRL+S and CTRL+R keys.

Press escape to cancel out of the search mode.

So what doesn’t cplay do? Well, it won’t sync with your iPod. It won’t throw up a cutesy album photo of what’s playing, along with the IDv3 info. Streaming audio is beyond its reach. You can’t edit tags on the fly, and I haven’t found any way to control it remotely, such as through a network. And it’s not a music management suite, a la iTunes, which seems to be what the young-uns are all learning these days.

But the biggest selling point for cplay is this:

I’m running cplay in a terminal window there, and as you can see, the processor load is around 0.0 percent of my 1.4Ghz for cplay, with a negligible amount for the ogg123 client processes. And the memory profile is equally svelte: 0.7 percent of my 768Mb for cplay, only four-tenths of a percent for each of the ogg123 processes.

That means the total processor load is under 2 percent, and the memory profile is around 8Mb, sometimes more, sometimes less. By comparison, Audacious — which I consider a lightweight — uses more than 14Mb at a time and needs around 3 percent of my processor, spiking or falling here and there. I don’t want to know what some of the heavyweight “music management” suites need.

Spacewise, cplay is pitifully small. It has almost no dependencies outside the standard framework that comes with Ubuntu, and even if you install it with vorbis-tools and mpg123, you’re downloading less than 275Kb and using under 1.3Mb when installed. If your collection is strictly ogg format, like mine, you’re talking about less than 170Kb for the download and a measly 1Mb occupancy. I’ve written letters to Mom that take up more space than that.

So now, to reinforce my original point: That 166Mhz laptop with 64Mb and the 3Gb hard drive you have in the closet could easily handle the workload. With a very lightweight operating system and a minimal GUI, you could set up Ubuntu to run on a machine of that caliber, give it network (or even local) access to your music collection, and run it into a stereo or a decent pair of laptop speakers … and give it a little more life.

Next: How to whip rtorrent into an automated torrent management frenzy.

40 thoughts on “Howto: Use cplay like a pro

  1. fareast

    Your site really rocks! And thanks for the tip about Jamendo; I have already gotten three nice albums from them. Still haven’t been able to figure out how to unpack your speed for Feisty guide, but I’m a relative Linux newb, so getting the answer is half the fun. Cheers!

  2. K.Mandla Post author

    Thanks! πŸ˜€ I was just tinkering with the widget and trying to put those files into the sidebar. If you check that page again, I relinked them with the proper names, so they should be easier to decompress now. Cheers!

  3. Pingback: Howto: Use rtorrent like a pro « Motho ke motho ka botho

  4. Pingback: Terminally Incoherent » Blog Archive » A day without X

  5. Geoff

    I was pushing cplay through a CRT TV and it works a charm. However, with the guilt of global warming weighing heavily upon me, I’ve ditched the idea of yet another device sucking at the sockets.

  6. Pingback: test 07/29/2007 « Strange Kite

  7. Pingback: My daily readings 07/30/2007 « Strange Kite

  8. Sy Ali

    I finally got cplay working on my Zaurus. It’s awesome. =) I even got mikmod working too.

    I wish it had sidplay support. I might have to hack that in one day.. once I get a sidplayer working on my Zaurus.

  9. james

    Is there a way to add the whole directory to the playlist to play the music in the directory in shuffle mode?

    Thanks for the article!

  10. K.Mandla Post author

    Hi James. I believe if you select the directory with the spacebar, you can add the entire substructure with the ‘a’ key. From there, check the help screen for the shuffle key (I’ve forgotten it, since I don’t shuffle up my tunes very often). Have fun!

  11. james

    Hi K.Mandla,

    Thanks for your quick reply!

    Selecting the directory is an option, another possibility which comes in handy here is “i” for selecting the inverse. This way I can select a few songs/directories/.m3us I don’t want to hear and then select the inverse – which is what i want to add.

    Shuffling the playlist is s when the playlist is displayed.

  12. Erkkimon

    A really good howto! Cplay can be used remotely using ssh and screen.
    1. Log in on the target computer using ssh. Note that the target computer needs to have ssh daemon running and you must have ssh installed on your client computer.
    2. Start cplay in screen, like “screen cplay”. Note that you must have screen installed on the target computer. Then close your terminal emulator.
    3. Now your player should still play music. If you want to edit playlist or something, log in again on your target computer and attach the screen in your terminal emulator commanding for example “screen -rx”.

    I’m not sure if I got what you meant with remote control in the howto but hopefully this helps you and people who read this howto!

  13. Pingback: links for 2007-09-14 « Stand on the shoulders of giants

  14. DukeXC

    Hey, I ran across your site looking for a bittorrent client, and although I eventually changed clients, rTorrent was very useful for a while as I re-organized my RAM priorities.

    On linking to cplay and trying it I was simply amazed by the power its direct, no-nonsense interface provided, and had been using it quite happily until I very recently ran into sound quality troubles with the program – understandable as this guide is for weaker machines, but for an audiophile that slight hiss and crackle is a serious killer.

    While cplay is an incredible player, I’d suggest also giving cmus or moc a try. moc (music on console) is extremely similar to cplay but with some added functionality, a slightly more attractive interface and pristine sound quality. cmus, although not to my tastes, is actually a full-fledged music library app in curses, with some very interesting customizeability options.

    I love the site, I’ve found a plethora of useful apps here – I just thought I’d add my two cents, as I have since noticed a huge number of underappreciated terminal apps.

  15. Pingback: Tiled window manager « Motho ke motho ka botho

  16. Pingback: Howto: Install cplay for the XO « Motho ke motho ka botho

  17. Andreas

    Actually, cplay can play streaming audio just fine. As it is just a frontend, it can pass on the URL to a stream to a command line program that can play it, such as mplayer. This way you can play any file format you like. It wouldn’t be hard to let cplay display ID3 tags, but it would make things unnecessarily slow, file names should simply be descriptive enough!

  18. lynucs

    i personally use cplay for some spontanious audio play of 1-2 files which are not in the main music folder (yet).

    for “organized” music playing i’m really happy with mpd+ncmpc, maybe worth to try for all who also liked cplay.

    really nice articles here, btw.

  19. Matt

    Cplay accepts commands via local UNIX sockets, but this feature has not been documented well. There are however some hints in the following file found on recent Debian or Ubuntu distributions.

    $ cat /usr/share/doc/cplay/examples/lircrc | grep cplay-control
    config = echo “next” > ${TMPDIR-/tmp}/cplay-control-$USER
    config = echo “prev” > ${TMPDIR-/tmp}/cplay-control-$USER
    config = echo “backward” > ${TMPDIR-/tmp}/cplay-control-$USER
    config = echo “forward” > ${TMPDIR-/tmp}/cplay-control-$USER
    config = echo “play” > ${TMPDIR-/tmp}/cplay-control-$USER
    config = echo “stop” > ${TMPDIR-/tmp}/cplay-control-$USER
    config = echo “volup” > ${TMPDIR-/tmp}/cplay-control-$USER
    config = echo “voldown” > ${TMPDIR-/tmp}/cplay-control-$USER
    config = echo “quit” > ${TMPDIR-/tmp}/cplay-control-$USER

    So I can enter a command such as

    $ echo “next” > /tmp/cplay-control-matt

    to tell a running cplay to advance to the next track. I have found the word “pause” also works, although it is not listed above.

    I have taken advantage of this feature by creating some Openbox window bindings such as the following.

    sh -c ‘echo “pause” > ${TMPDIR-/tmp}/cplay-control-$USER’

    This allows me to pause cplay at any time by pressing logo+z.

    Your comment above suggests you wish to contact a running cplay over the network, however. If you have configured public key authentication on your hosts, you should be able to do something like the following.

    $ ssh user@machine-running-cplay sh -c ‘echo “stop” > /tmp/cplay-control-user’

    I have not tested that last command.

  20. Pingback: Back to BMP « Motho ke motho ka botho

  21. Pingback: My Desk |

  22. cambridge

    I use cplay as a frontend to madplay wich gives me 32 bit depth on my HD audio soundcard !!!

  23. Gerrit

    Does anybody know how to get cplay dislpay cyrillic letters. At the moment i get only question marks instead of real letters.

  24. Pingback: Tools for a CLI environment < green and black and grey all over

  25. Daniel Michalik

    I’m probably one of the last persons in the life of cplay that wrote a patch to improve some functionality. Yesterday night I was wondering whether this project will ever come back into more development – and one of the things I wanted to address was improving external actions. You already know about the cplay control FIFO, but I miss things. Such as adding files by calling cplay with a list of filenames as argument. Or such as giving the control fifo any control over the playlist. I’d be curious to see if anyone besides me is still using cplay.

    1. K.Mandla Post author

      I say take the ball and run with it, Daniel. In a situation where even the home page is gone, I think it’s probably safe to say that the project is abandoned. Grab the source code and take over development. Judging from your patch, you’re more than qualified for the job … πŸ˜‰

      And when you have an update for it, let me know. I would like to see something fresh in cplay. πŸ™‚

  26. Pingback: No, terminal apps are not dying « Motho ke motho ka botho

  27. Pingback: Audio players for the console « Motho ke motho ka botho

  28. Paul Clark


    I have found cplay really useful … am using it as part of the 3MX Ultra distro on an Elonex one-T. cplay is version 1.49 but I don’t know which release of 1.49 it is I am afraid.

    But I can’t get the random or shuffle functions to work. It totally ignores both requests although I do get an error message “shuffle … Oops” when I press the “s” key.

    Anyone know why it doesn’t work for me, please?



  29. Pingback: Audio Media Player Application of the Year - Page 2

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s