Skip to main content

A curses front-end for various audio players

Project description


cplay is a minimalist music player with a textual user interface written in Python. It aims to provide a power-user-friendly interface with simple filelist and playlist control.

Instead of building an elaborate database of your music library, cplay allows you to quickly browse the filesystem and enqueue directories. Cue-files and other playlists are supported.

The original cplay is no longer maintained. This fork aims to maintaining the original code as well as keeping it up to date with recent developments (e.g. python3) and adding new features.

screenshot of cplay with file browser


For playback, install one or more of the following players:

Other optional components:

  • pyalsaaudio (optional) For Alsa mixer support
  • pulseaudio-utils, specifically the pactl command (optional) For PulseAudio mixer support
  • mutagen (optional) For metadata support (IDv3 etc.)


$ pip install cplay-ng

In Debian/Ubuntu, the following installs a selection of players and optional components:

$ sudo apt-get install mpv gst123 mpg321 vorbis-tools pulseaudio-utils


$ cplay-ng [ file | dir | playlist ] ...

For a full list of command line options, see cplay-ng --help. When in doubt about runtime controls, press ‘h’ for a friendly help page.

Apart from cplay-ng, this distribution also includes the program cnq-ng to remote-control a running cplay-ng.


If you would like to change the default player or the options passed to the players just edit the BACKENDS list at the end of the cplay script.


A playlist can contain URLs, but the playlist itself will have to be local. For mpeg streaming, splay is recommended.

It is also possible to pipe a playlist to cplay-ng, as stdin will be reopened on startup unless it is attached to a tty.

The shell command gets the full path of either all tagged items or the current item as positional arguments.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for cplay-ng, version 3.0.0
Filename, size File type Python version Upload date Hashes
Filename, size cplay_ng-3.0.0-py3-none-any.whl (58.9 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size cplay-ng-3.0.0.tar.gz (32.3 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page