Skip to main content

Stylize Plugin for Beets

Project description

Stylize Plugin for Beets

PyPI Status Python Version License

Read the documentation at https://beets-stylize.readthedocs.io/ The Ethical Source Principles Contributor Covenant Tests Codecov

pre-commit Ruff codestyle

Album Listing

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 with the format_item and format_album configuration options.

  • stylize or color: 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.
  • urlencode: URL-encode the supplied text.

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

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:

Album Listing

And this:

Track Listing

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:

Nocolor Listing

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:

Link Listing

Example Usage From My Personal Configuration

Personal Config Listings

This example is more elaborate, and includes usage of alias, savedformats, inline and albumtypes. alias is only used to provide separate commands that use %link, as using it seems to have a performance impact, so I don't want it always used. savedformats is only used to split up the default format strings for readability and maintainability, but is not required. inline can be used instead of savedformats to provide the icon field.

plugins: stylize alias savedformats inline albumtypes

aliases:
  lsl:
    help: List items, linking to their files
    command: ls -f '%link{file://$path,$icon} $format_item'
    aliases: list-linked

  lsf:
    help: List items, with links to play them in foobar2000 (macOS only)
    command: ls -f '%link{shortcuts://run-shortcut?name=Open in foobar2000&input=text&text=%urlencode{$path},$icon} $format_item'
    aliases: list-foobar2k

item_fields:
  icon: '"📄"'
  disc_and_track: |
    if not track or (tracktotal and tracktotal == 1):
      return ''
    elif disctotal > 1:
      return u'%02i.%02i' % (disc, track)
    else:
      return u'%02i' % track

album_fields:
  icon: '"📁"'

item_formats:
  format_item: "%ifdef{id,$format_id }%if{$singleton,,$format_album_title %nocolor{| }}$format_year %nocolor{- }$format_track"

  format_id: "%stylize{id,$id,[$id]}"
  format_album_title: "%stylize{album,$album%aunique{}}%if{$albumtypes,%stylize{albumtypes,%ifdef{atypes,%if{$atypes, $atypes}}}}"
  format_year: "%stylize{year,$year}"

  format_track: "%if{$singleton,,%if{$disc_and_track,$format_disc_and_track %nocolor{- }}}$format_artist$format_title"
  format_disc_and_track: "%stylize{track,$disc_and_track}"
  format_artist: "%stylize{artist,$artist} %nocolor{- }"
  format_title: "%stylize{title,$title}"

album_formats:
  format_album: "%ifdef{id,$format_album_id }%if{$albumartist,$format_albumartist %nocolor{- }}$format_album_title %nocolor{| }$format_year"

  format_album_id: "%stylize{id,$id,[$id]}"
  format_albumartist: "%stylize{albumartist,$albumartist}"
  format_album_title: "%stylize{album,$album%aunique{}}%if{$albumtypes,%stylize{albumtypes,%ifdef{atypes,%if{$atypes, $atypes}}}}"
  format_year: "%stylize{year,$year}"

  # Allow for aliases with `-f '$format_item'` to be used when `-a` is passed
  format_item: "$format_album"

format_album: "$format_album"
format_item: "$format_item"

ui:
  colors:
    album: ["blue", "bold"]
    albumartist: ["yellow", "bold"]
    albumtypes: ["cyan"]
    artist: ["yellow", "bold"]
    id: ["faint"]
    title: ["normal"]
    track: ["green"]
    year: ["magenta", "bold"]

Contributing

Contributions are very welcome. To learn more, see the Contributor Guide.

License

Distributed under the terms of the MIT license, Stylize Plugin for Beets is free and open source software. This software prioritizes meeting the criteria of the Ethical Source Principles, though it does not currently utilize an ethical source license.

Issues

If you encounter any problems, please file an issue along with a detailed description.

Credits

This project is a plugin for the beets project, and would not exist without that fantastic project. This project was generated from @cjolowicz's Hypermodern Python Cookiecutter template.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

beets_stylize-1.2.1.tar.gz (7.5 kB view details)

Uploaded Source

Built Distribution

beets_stylize-1.2.1-py3-none-any.whl (7.5 kB view details)

Uploaded Python 3

File details

Details for the file beets_stylize-1.2.1.tar.gz.

File metadata

  • Download URL: beets_stylize-1.2.1.tar.gz
  • Upload date:
  • Size: 7.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for beets_stylize-1.2.1.tar.gz
Algorithm Hash digest
SHA256 ee8404df4fc7352bdd2b32174df411426a279d28f8b3e55af87ed1c3a32f9107
MD5 4757617989f5447fe65a4e62f647c3b4
BLAKE2b-256 555342af8362189c3f5fda042f31cb2498cce8a637e6405c4ca3bff15ad1bd02

See more details on using hashes here.

File details

Details for the file beets_stylize-1.2.1-py3-none-any.whl.

File metadata

File hashes

Hashes for beets_stylize-1.2.1-py3-none-any.whl
Algorithm Hash digest
SHA256 14fc0c991f8d309bac184d5ccd665685a8955c160cd7dc82e647f7d1c4931119
MD5 f5f15a93836141c865b0c669a42326de
BLAKE2b-256 5efa5830a4ed246c1cb5c01e3a722377e0a03de38326c37621a4a34a82fa03be

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page