New plugin announcement: stylize

[kergoth]

Stylize Plugin for Beets

The stylize plugin adds style and color to the list command and other commands that need to print out items, by adding three template functions for use in beets track and album listings. It is intended for use with the format_item and format_album configuration options.

• stylize: Add color and formatting to your formatted items and albums.
• nocolor: Show the supplied text only when color is disabled. This is useful to add separators between fields when color is unavailable.
• link: Create clickable links in the terminal. This has no effect on an unsupported terminal. This lets you play a track or navigate to an album folder with a click.

Installation

As the beets documentation describes in Other plugins, to use an external plugin like this one, there are two options for installation:

• Make sure it’s in the Python path (known as sys.path to developers). This just means the plugin has to be installed on your system (e.g., with a setup.py script or a command like pip or easy_install). For example, pip install beets-stylize.
• Set the pluginpath config variable to point to the directory containing the plugin. (See Configuring) This would require cloning or otherwise downloading this repository before adding to the pluginpath.

Configuring

First, enable the stylize plugin (see Using Plugins). Colors for use with the stylize function may be defined using the colors option under UI Options in your beets configuration. For example:

ui:
  colors:
    artist: ["bold", "green"]

Using

The stylize function accepts a named color as the first argument, the text to be stylized as the second, and an optional third argument for the text to be used if color is disabled.

Example usage in your beets configuration, based on the default format_item and format_album configuration options:

ui:
  color: true
  colors:
    # Field colors for use in the item and album formats.
    album: ["blue", "bold"]
    albumartist: ["yellow"]
    artist: ["bold", "yellow"]
    title: ["normal"]

format_item: "%stylize{artist,$artist} %nocolor{- }%stylize{album,$album} %nocolor{- }%stylize{title,$title}"
format_album: "%stylize{albumartist,$albumartist} %nocolor{- }%stylize{album,$album}"

With this configured, we see listings like this:

And this:

If no color is available, such as due to redirection, or setting the NO_COLOR environment variable, we see a listing like this due to the use of %nocolor to add the separator:

As an example of how to use %link, this would make the entire line a clickable link to the file path:

format_item: "%link{file://$path,$artist - $album - $title}"

As we see here, in the Visual Studio Code terminal:

[kergoth]

Example listings from my personal config:

[kergoth]

Updated to add %color as an alternative to %stylize (same result), and to add %urlencode, which can be useful in combination with %link. A new personal config example with the associated configuration is now in the readme at Example Usage From My Personal Configuration, which includes usage of %urlencode in its lsf alias.

[Serene-Arc]

Hey! It's wonderful that there's a new plugin! Would you mind adding an enhancement request to add this to our plugin page? Just so adding it to the docs doesn't get forgotten.

[alxtrnr]

Thanks for your work on this. I'd like to use the plugin. I'm on package beets 2.0.0, installed using Python 3.12.3. The plugin Requires-Python <3.11,>=3.8

Can you add in 3.12 if it will work with it?

[kergoth]

Sure. I'm certain it'll work fine with it, I think I just mirrored the at-the-time python requirements in the beets project upstream. I'll take a look.

[kergoth]

Should be taken care of now, added support for 3.11 and 3.12 and expanded the tests to include them, seems to work fine. Release version 1.2.1 Should be available via pip from pypi as usual. Apologies for the inaccurate release notes if anyone reads them, I need to stop using the current method of handling my changeling.