Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

A package for displaying Cmus current status in notifications

Project Description

Author:Antoine Gagné

1   Requirements

To install this program, you must have the following:

  • python 3.5+
  • The Python library notify2
  • notify-send

2   Installation

To install this program, you can simply run the following command:

python install

This program can also be found on Pypi which means you can install it by downloading the wheel or by using the following command:

pip install cmus-notify

You can check if it installed correctly by doing the following command:

cmus_notify -h

It should display a message.

3   Hooking To Cmus

To hook this program to cmus, you have to create a shell script that have the following lines in it:

#! /bin/sh

cmus_notify "$*" &

Then, you must make the file executable by using the following command (assuming your script’s name is

chmod +x

Finally, once you are in cmus, you can add the hook by using the following command:

:set status_display_program=<path-to-the-shell-script>

4   Customization

If you want you can specify the formatting of the notification by specifying format strings. For example:

#! /bin/sh

cmus_notify --title "Now playing: {title} by {artist}" --body "<b>Album:</b> {album}\n<b>Duration:</b> {duration}" "$*"

You can also specify a configuration to read these values from. By default, the program will search for a configuration file named ~/.cmus-notify. It has the following format:

    application_name = Cmus
    custom_notification = /home/user/.cmus/

    title = Now playing: {title} by {artist}
    body = <b>Album:</b> {album}
           <b>Duration:</b> {duration}

The options accepts the same values as their command-line options equivalent.

5   Options

To view the full options, you can run the following command:

cmus_notify --help

which will display the following prompt:

usage: cmus_notify [-h] [-a APPLICATION_NAME] [-b BODY_FORMAT_STRING]
                   [-c CUSTOM_NOTIFICATION]

Display a notification about Cmus's current status

positional arguments:
  INFORMATION           Parse the given information

optional arguments:
  -h, --help            show this help message and exit
                        The name of the application
                        A format string that can be specified to tell the
                        software how to format the body. The syntax is the
                        same as Python's. The available options are specified
                        at the end of this help message. (i.e. 'Artist:
                        A format string that can be specified to tell the
                        software how to format the title. The syntax is the
                        same as Python's. The available options are specified
                        at the end of this help message. (i.e. 'Now playing:
                        The path to the configuration file. If it is not
                        specified, the program will use the default values of
                        the other options.
                        The path to a custom implementation of the
                        notification class. If it is not specified, the
                        standard implementation will be used (the one using

Format String Parameters

The available arguments to the format strings are the following:

  - album: The song's album
  - artist: The song's artist
  - date: The song's release date
  - discnumber: The song's disc's number
  - duration: The song's duration
  - file: The song's file's path
  - status: Cmus current status
  - title: The song's title
  - tracknumber: The song's track number

6   Documentation

The project’s documentation can be found here.

Release History

This version
History Node


History Node


History Node


Download Files

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

Filename, Size & Hash SHA256 Hash Help File Type Python Version Upload Date
(8.5 kB) Copy SHA256 Hash SHA256
Source None Aug 31, 2017

Supported By

Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Kabu Creative Kabu Creative UX & Design Google Google Cloud Servers Fastly Fastly CDN StatusPage StatusPage Statuspage DigiCert DigiCert EV Certificate