cmus-status-line

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

TODO: Build and upload binaries!
Binaries for Linux and Windows are available from the GitHub releases page.

Install from [crates.io]

TODO: Upload to 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

• 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"), ), ])

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, ]), ),

License

Distributed under the terms of the MIT license.