#barszcz

Barszcz is intended to be a vi-like terminal user-interface (TUI) and music player plugin for beets. It is named after a type of Polish beetroot soup.

Currently, barszcz provides a configurable interface for beets' list command.

• todo list and issue tracker
• mailing list for questions and contributions

#How to use it

Get the source:

git clone https://git.sr.ht/~callum/barszcz

Add it to your PYTHONPATH, for example:

export PYTHONPATH=$PWD/barszcz:$PYTHONPATH

Enable the plugin in your beets configuration by adding barszcz to the plugins option. For more information on using plugins see the beets plugins documentation.

Run barszcz with:

beet barszcz

#Interface

Barszcz is based around lists of so-called "things". A thing could be a representation of a beets' album or item, an attribute of an album or item, or a heading. Different types of things may have their own configuration options, and may be treated differently by commands.

#Commands

The command input line at the bottom of the screen can be brought up by typing a colon (":").

Positional arguments of commands are in [brackets]. Required arguments are CAPITALISED.

#quit

Quit barszcz.

Short form: q

#list [query]

List albums and items matching the [query]. Default: [query] is blank, list all albums and items.

Short form: ls

#lista [query]

List albums matching the [query]. Default: [query] is blank, list all albums.

Short form: lsa

#listi [query]

List items matching the [query]. Default: [query] is blank, list all items.

Short form: lsi

#focus [INDEX]

Change focus to the thing at the given [INDEX]. A negative [INDEX] focuses the last thing. Indices are not displayed; this command is intended for internal use and shortcuts.

#up [n]

Change focus up [n] things (wraps). Default: [n] = 1.

#down [n]

Change focus down [n] things (wraps). Default: [n] = 1.

#more [subset]

Show more information about the focused thing.

If an album or item is focused, its attributes will be listed, and the optional [subset] argument can be used to specify which subset of attributes will be listed: if [subset] is all, all attributes will be listed; if it is set, only attributes with a set (non-blank) value will be listed; if it is config, only attributes specified in the configuration will be listed. Default: [subset] = config.

If an attribute is focused, albums and items with that attribute will be listed using the beets query key:value, and the [subset] argument has no effect.

#blank

A blank command clears the input line and shortcut input.

#Shortcuts

Single and multi-character shortcuts can be used to execute commands without typing them in. A sequence of digits preceding a shortcut can be passed as an argument to commands, for example typing 3 followed by the down arrow key will move the focus three things down (using the default configuration). The current shortcut input can be seen in the bottom right of the screen.

For the default shortcuts and how to define shortcuts, see the Configuration section.

#Configuration

Make a barszcz section in your configuration file. Available attributes are described below.

#Formatting

• format_item determines what information about an item (track) should be displayed, and where. It has two options, left and right, which are both lists of strings which follow the beets path format syntax. Each list entry corresponds to a line on the screen. If a list entry is left blank, a blank line will be displayed, and if left or right is left blank, nothing will be displayed on that side.

• format_album is as above but for albums.

• gap has sub-options regular and small. regular is used for the number of blank lines between each item or album. small is used for the number of blank lines between attributes when viewing more detail about an item or album.

• item_attributes determines which attributes should be displayed (and in what order) when using the more config command on an item.

• album_attributes is as above but for albums.

#Shortcuts

• shortcuts is a collection of key-value pairs of the form shortcut sequence: command. A single pair of curly brackets {} in the command will be replaced by the sequence of digits input immediately prior to the shortcut sequence.

For a list of key constants that can be used for special keys (e.g. KEY_ENTER), see the "Key constant" table on the constants section of the Python curses documentation. In addition to this list, you may also use KEY_ESCAPE, which by default clears the input line and current shortcut by executing a blank command.

A caret followed by a capital letter represents the control character linked to the letter, for example if Control+Q is pressed, the command defined by the ^Q shortcut will be executed. Some control characters are used by the terminal, so be careful or you might break something :).

#Default configuration

barszcz:
	format_item:
		left:
			- $title
			- $album ($year)
			- $artist
		right:
			- $length
	format_album:
		left:
			- $album
			- $albumartist ($year)
		right:
			- $albumtotal tracks
	gap:
		regular: 1
		small: 0
	item_attributes:
		- album
		- artist
		- albumartist
		- composer
		- year
		- original_year
		- genre
		- format
	album_attributes:
		- album
		- albumartist
		- year
		- original_year
		- genre
	shortcuts:
		KEY_UP: up {}
		k: up {}
		KEY_DOWN: down {}
		j: down {}
		f: focus {}
		gg: focus 0
		G: focus -1
		KEY_ENTER: more config
		ma: more all
		ms: more set
		KEY_ESCAPE: ""