cmus-status-line

Table of Contents

• Description
• Installation
  • Binaries
  • Install from crates.io
• Usage
• Configuration
  • Simple configuration example
  • The format key
  • FormatPart
  • FormatExpression
• License

---

Description

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... <#-->

Installation

Binaries

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

Usage

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

USAGE:
    cmus-status-line [OPTIONS] [COMMAND]

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

COMMANDS:
    status
        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.
    dump-config
        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
    help
        Print this help message and exit.

Configuration

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:
https://docs.rs/dirs/2.0.2/dirs/fn.config_dir.html)

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.

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.

  Example:

  Truncate(Container([
      Text("progress: "),
      ProgressBar("<##-->"),
      Text(" title: "),
      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.

  Example:

  Container([
      If(
          IsStatus(Playing),
          Title,
      ),
      If(
          IsStatus(Paused),
          Text("PAUSED"),
      ),
  ])
  

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

  Example:

  Container([
      IfElse(
          IsStatus(Playing),
          Title,
          Text("not playing"),
      ),
  ])
  

FormatExpression

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

  Example:

  If(
      IsStatus(Playing),
      Container([
          Text("playing song: "),
          Title,
      ]),
  ),
  

• 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.

---

License

Distributed under the terms of the MIT license.