#cmus #music #status

bin+lib cmus-status-line

Prints cmus playback information in a configurable format to stdout

4 stable releases

1.1.1 Jul 6, 2020
1.1.0 Jul 5, 2020
1.0.2 Feb 14, 2020
1.0.1 Dec 5, 2019

#1846 in Command line utilities

26 downloads per month

MIT license


Rust 1K SLoC // 0.0% comments Shell 129 SLoC // 0.2% comments


Table of Contents


Prints the current cmus playback status in a customizable format to stdout.
Example output with default config:

$ cmus-status-line # When PLAYING
 Undertale - Megalovania  <###----->

$ cmus-status-line # When PAUSED
 Underta... <#-->



Binaries for Linux and Windows are available from the GitHub releases page.
Note: Windows binaries are not tested, if there is any problem please let me know by opening an issue!

Install from crates.io

cargo install cmus-status-line


Simply run the command without any arguments
to get the formatted cmus playback status:

$ cmus-status-line
 Undertale - Megalovania  <###----->

For more details, see cmus-status-line --help:

Prints cmus playback information in a configurable format to stdout

    cmus-status-line [OPTIONS] [COMMAND]

    -h, --help       Print this help message and exit.
    -v, --version    Print version information and exit.

        Print the current cmus playback status
        with the format configured in the config.toml file.
        This is the default command, so you may omit this argument.
        Print the default config as TOML to stdout.
        To write the default config to the proper config file, run something like:
            mkdir -p ~/.config/cmus-status-line
            cmus-status-line dump-config > ~/.config/cmus-status-line/config.toml
        Print this help message and exit.


The goal for this project, was to make the status line's format highly configurable.
You can configure the format as a string in the config.toml file.
To get started, run the following to dump the default config to the proper config directory:
(This assumes you are on Linux, for Windows or MacOS find your appropriate config directory here:

mkdir -p ~/.config/cmus-status-line
cmus-status-line dump-config > ~/.config/cmus-status-line/config.toml

The default configuration is in the config.toml file.

Simple configuration example

Here's a small and simple configuration example to get you started,
if you don't want to / don't have the time to read the details:

format = """
%{Title} - %{ProgressBar("<####---->")}

The format key

The configuration has a format key, which is a string.

Any plain text in the string is simply printed in the format,
so a format string with this value:

format = "my cmus status!"

would simply print my cmus status!.
Any new-line characters are ignored.
To add dynamic content, you can use the %{...} syntax to inject information,
for example:

format = "playing song: %{Title}"

would replace the %{Title} part with the currently playing song's title.
We call the Title part a FormatPart.


enum FormatPart
Any of the following format parts can be used
in the format string inside %{...} blocks.
They will be replaced with a string value.

  • Text(String)
    Returns the given string.

  • Title
    Returns the currently playing song's title.
    Any underscores (_) will be replaced with spaces ( ).

  • Status
    Returns the current playback status (CmusPlaybackStatus),
    which can be one of:

    • Playing
    • Paused
    • Stopped
  • Tag(String) Returns the tag meta value for the given tag name
    (such as "artist", "album", "tracknumber").
    Returns nothing if the tag doesn't exist.

    Example: Tag("artist")

  • Truncate(FormatPart, usize)
    Returns the wrapped FormatPart's return string,
    truncated to the given usize length.

    Example: Truncate(Title, 20)
    which will return the full title of the song,
    if it has less than or exactly 20 characters.
    If it has less, the title will be truncated to 20 characters,
    with trailing ... characters.

  • HtmlEscape(FormatPart)
    Uses the htmlescape::encode_minimal function, to escape
    any HTML syntax such as <>& from the wrapped FormatPart.

    Example: HtmlEscape(Title)

  • ProgressBar(String)
    Returns a progress bar for the playback of the currently playing song.
    The given string acts as a config for which characters to use.
    The first and last characters of the string are used as the boundary characters of the bar.
    The second and second to last characters are used as the full and empty characters.
    The total length of the string is the length of the progress bar.

    Example: ProgressBar("<##-->") will use <> as the bar boundary characters,
    the # as the full character, and the - as the empty character.
    The progress bar will have a length of 6 characters.

  • Container(Vec<FormatPart>)
    This wraps multiple FormatParts into a single one.
    Useful in combination with other FormatParts.


        Text("progress: "),
        Text(" title: "),
    ]), 60)

    which will truncate the combined length of the bar,
    the song title, and some static text to 60 characters or less.

  • If(FormatExpression, FormatPart)
    Returns the evaluated FormatPart, if the FormatExpression returns true.
    See the section on FormatExpression for available expressions.


  • IfElse(FormatExpression, FormatPart, FormatPart)
    If the given FormatExpression returns true, then
    returns the first FormatPart, otherwise returns the second FormatPart.


            Text("not playing"),


enum FormatExpression
A FormatExpression can be used as the first argument to
If FormatParts. They will always evaluate to either true or false.

  • True
    Always returns true.

  • False
    Always returns false.

  • And(FormatExpression, FormatExpression)
    Returns true if both of the given FormatExpressions evaluate to true.

  • Or(FormatExpression, FormatExpression)
    Returns true if either of the given FormatExpressions evaluate to true.

  • Not(FormatExpression)
    Inverts the given expression.

  • IsStatus(CmusPlaybackStatus)
    Returns true if the given CmusPlaybackStatus
    is the currently playing song's status. CmusPlaybackStatus can be one of:

    • Playing
    • Paused
    • Stopped


            Text("playing song: "),
  • HasTag(String)
    Returns true if the given tag name is set for the current track. Returns false if the tag doesn't exist on the track.


Distributed under the terms of the MIT license.


~85K SLoC