4 stable releases
1.1.1 | Jul 6, 2020 |
---|---|
1.1.0 |
|
1.0.2 | Feb 14, 2020 |
1.0.1 | Dec 5, 2019 |
#2171 in Command line utilities
56KB
1K
SLoC
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
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 wrappedFormatPart
's return string,
truncated to the givenusize
length.Example:
Truncate(Title, 20)
which will return the full title of the song,
if it has less than or exactly20
characters.
If it has less, the title will be truncated to20
characters,
with trailing...
characters. -
HtmlEscape(FormatPart)
Uses thehtmlescape::encode_minimal
function, to escape
any HTML syntax such as<>&
from the wrappedFormatPart
.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 of6
characters. -
Container(Vec<FormatPart>)
This wraps multipleFormatPart
s into a single one.
Useful in combination with otherFormatPart
s.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 evaluatedFormatPart
, if theFormatExpression
returnstrue
.
See the section onFormatExpression
for available expressions.Example:
Container([ If( IsStatus(Playing), Title, ), If( IsStatus(Paused), Text("PAUSED"), ), ])
-
IfElse(FormatExpression, FormatPart, FormatPart)
If the givenFormatExpression
returnstrue
, then
returns the firstFormatPart
, otherwise returns the secondFormatPart
.Example:
Container([ IfElse( IsStatus(Playing), Title, Text("not playing"), ), ])
FormatExpression
enum FormatExpression
A FormatExpression
can be used as the first argument to
If
FormatPart
s. They will always evaluate to either true
or false
.
-
True
Always returnstrue
. -
False
Always returnsfalse
. -
And(FormatExpression, FormatExpression)
Returnstrue
if both of the givenFormatExpression
s evaluate totrue
. -
Or(FormatExpression, FormatExpression)
Returnstrue
if either of the givenFormatExpression
s evaluate totrue
. -
Not(FormatExpression)
Inverts the given expression. -
IsStatus(CmusPlaybackStatus)
Returnstrue
if the givenCmusPlaybackStatus
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)
Returnstrue
if the given tag name is set for the current track. Returnsfalse
if the tag doesn't exist on the track.
License
Distributed under the terms of the MIT license.
Dependencies
~3.5–5.5MB
~99K SLoC