VITUNES(1) BSD General Commands Manual VITUNES(1)NAMEvitunes — A curses media indexer and player for vi-users
SYNOPSISvitunes [-c command] [-d database-file] [-e command [argument ...]]
[-f config-file] [-m media-backend] [-p playlist-dir]
DESCRIPTIONvitunes is a curses-based music player and playlist manager for *nix
whose goals are a minimalistic appearance, strong vi-like bindings, and
quick playlist creation/management.
It is not intended to be a feature-rich media player, but rather a quick,
vi-like media indexer and playlist manager that also happens to be able
to play the media it indexes (via mplayer(1) ).
vitunes accepts the following command line options:
-c command Execute the specified command in the currently running
vitunes instance, and exit. This is useful for controlling
vitunes from other windows or scripts.
The commands that may be specified are both those named in
the RUN-TIME COMMANDS section below and keybindings specified
by their keybinding action name, listed in the KEYBINDING
ACTIONS section below.
To execute multiple commands, use this option repeatedly as
$ vitunes-c command1 -c command2 ...
For example, to have the currently running vitunes load and
play a playlist, one could issue:
$ vitunes-c ‘playlist SomePlaylist’ -c media_play
Note that for this to work, when vitunes starts up it
attempts to create a socket at /tmp/.vitunes that are used by
this option to communicate with the original instance. If
this socket cannot be created for any reason, this option
will not work.
-d database-file
Specifies the database containing all known media files and
their meta information that vitunes should use. If you're
using this option in conjunction with an e-command, this
option must be specified before the e-command.
The default location is ~/.vitunes/vitunes.db.
-e command options
Execute one of the available e-commands to manipulate the
database that vitunes uses. See the section below titled
E-COMMANDS for more information.
-f config-file
Specifies the path of the configuration file vitunes should
load. See the section below titled CONFIGURATION FILE for
information on what the configuration may contain.
The default location is ~/.vitunes/vitunes.conf.
-m media-backend
Specify the media backend to use for playback. The current
list of supported media backends are:
mplayer Uses a fork(2) / execvp(3) 'd instance of mplayer(1)
for all playback. Note that the mplayer binary must
be in your PATH environment variable.
Currently only mplayer is supported.
-p playlist-dir
Specifies the directory containing all of the playlists
vitunes will load and use. Any new playlists created while
running vitunes will be created here.
The default location is ~/.vitunes/playlists/.
Getting Started
vitunes works by maintaining a database of tagged media files. The data‐
base must be created and populated before vitunes can be run normally.
After that, files can be added, modified, or removed from the database,
and on the next invocation, vitunes will see the changes (additionally,
the database can be re-loaded at runtime).
· All database management is done using "e-commands", which are always
of the form:
$ vitunes-e command-name [parameters ...]
· Once the database has been created, vitunes can be run normally with
the following:
$ vitunes
· All playlist management is done while vitunes is running normally.
See the E-COMMANDS section below for more information on database manage‐
ment. To get started quickly, simply do the following:
1. Create initial empty database with
$ vitunes-e init
2. Add files to your database with
$ vitunes-e add ~/music/ /path/to/more/music/
3. Then just start normally with
$ vitunes
The Display
When run normally, the default display will show the following 4 windows:
player This window occupies the top row of the display and contains
information about the currently playing song (if any) and the
current play-mode.
command/status
This window occupies the bottom row of the display. It
behaves very similar to the command/status window in vi(1).
library This window occupies the left-side of the screen and shows
each playlist, in addition to the library and filter-buffer.
The filter buffer is where the results of every :filter ...
command are temporarily stored.
Playlists with unsaved changes appear bold and have their
name preceded with a '+'.
playlist This window is to the right of the library window and occu‐
pies most of the display. It shows the contents of whichever
playlist has currently been selected in the library window.
Useful Keybindings
The following is only a partial listing keybindings, but are the most
frequently used.
Enter Load the selected playlist for viewing or begin playback of the
selected file.
Tab Toggle focus between the library and playlist windows.
z Pause playback.
s Stop playback.
f/b Seek forwards/backwards 10 seconds.
F/B Seek forwards/backwards 1 minute.
m In the playlist window, show/hide information for the current
file.
See the KEYBINDING ACTIONS section for a complete listing.
E-COMMANDS
Below is a brief summary of each e-command available in vitunes. More
detailed usage information and examples for each can be obtained by issu‐
ing:
$ vitunes-e help command-name
vitunes-e init
Create the necessary database file and playlist directory used by
vitunes. This command only needs to be run once, when vitunes is
first run. If either of these already exist, they remain
unchanged.
vitunes-e add path1 [path2 ...]
This command takes any number of files/directories as parameters.
Each file is scanned for meta-information and if found, added to
the database. Directories are search recursively.
TagLib(3) is used for all meta-extraction, which includes the
following fields: album, artist, comment, play-length, title,
track number, and year.
vitunes-e addurl url
This command is used to add non-files (things like URL's for
Internet radio stations) to the database, where the meta-informa‐
tion cannot be determined automatically. It can also be used to
update the meta-info of an existing URL in the database.
After executing, you are prompted to enter all of your own infor‐
mation.
vitunes-e check [-rsd] file1 [file2 ...]
Scan the files specified and display their meta-information as
present in the files themselves or in the vitunes database. This
is useful for checking if a file is in the database.
vitunes-e flush [-t time-format]
Dump the contents of the database to stdout in an easy-to-parse
format, optionally with the specified strftime(3) compatible for‐
mat for times.
vitunes-e help command
Display detailed usage information and examples for the e-command
specified by command.
vitunes-e rm [-f] file/url
Remove a file/URL from the database.
vitunes-e rmfile [-f] file/url
Alias for the "rm" e-command.
vitunes-e tag [options] file1 [file2 ...]
Add/modify the meta-information tags of raw files. There are
many options to this e-command. See the help page for more
information:
$ vitunes-e help tag
vitunes-e update [-s]
Load the existing database and check each file to see if its
meta-information has been updated, or if the file has been
removed. The database is updated accordingly.
RUN-TIME COMMANDS
Below is a listing of all run-time commands supported by vitunes.
All commands are entered by typing ':' followed by the command name and
any parameters (just like in vi(1) ).
Note that abbreviations are also supported. That is, entering any non-
ambiguous abbreviation of a command name will also execute the command.
:bind action keycode
This will bind the action specified by action to the keycode
specified by keycode. After this command is issued, entering the
inputting the specified keycode will result in firing the speci‐
fied action.
See the section SPECIFYING KEYCODES for details on how to specify
keycode, and section KEYBINDING ACTIONS for a listing of all
actions vitunes supports.
:color item=fg,bg
Change the color of the given item to fg colored text on a bg
colored background.
Available values for item are:
Item Name Description
bars The bars dividing the various windows.
player The player window.
status The status window.
library The library window.
playlist The playlist window.
errors Error messages in the status window.
messages Informational messages in the status win‐
dow.
tildas-library The tildas in empty rows of the library
window.
tildas-playlist The tildas in empty rows of the playlist
window.
playing-library Currently playing playlist in the library
window.
playing-playlist Currently playing file in the playlist
window.
current-inactive Current row in the inactive window.
artist The artist column in the playlist window.
album The album column in the playlist window.
title The title column in the playlist window.
track The track column in the playlist window.
year The year column in the playlist window.
genre The genre column in the playlist window.
comment The comment column in the playlist win‐
dow.
length The play-length column in the playlist
window.
Available colors for fg and bg are: white, black, red, green,
yellow, blue, magenta, cyan, and default. The color default is
whatever the terminal uses as the default foreground or back‐
ground color.
:display (reset | show | display-description)
The display command is used to change which columns are displayed
in the playlist window, their order, their width, and their
alignment.
The format of display-description is a comma separated list of:
"[-]field.size".
Valid values for field are: album, artist, comment, genre,
length, title, track, and year. The size field indicates the
number of columns. If field is preceded with a - the field will
be right-aligned. As an example, the command:
:display title.10,artist.20,-track.4
would only show the title, artist, and track fields, in that
order, where the title field is 10 columns wide, the artist field
is 20 columns wide, and the track field is 4 columns wide and
right-aligned.
The default display can be restored with:
:display reset
The current display description can be seen with:
:display show
:filter[!] token [token2 ...]
The filter command is used to filter out all songs from the cur‐
rently viewed playlist that do not match (or do match) the pro‐
vided list of tokens. A song matches the list of tokens if each
token appears somewhere in the song's meta-information or file‐
name.
If ":filter" is used, all records not matching the list of tokens
are removed from the current playlist. If ":filter!" is used,
all records that do match the list of tokens are removed from the
current playlist.
The list of tokens is simply any list of strings, each possibly
preceded with an exclamation point. If a token is preceded with
an exclamation point, it will only match a song if it does not
appear anywhere in the song's meta-information or filename.
For example, the following:
:filter nine nails
would match all songs that contained both "nine" and "nails", and
remove all other songs from the current playlist. However,
:filter! nine nails
would remove all songs that DO contain both "nine" and "nails."
The query:
:filter nine !nails
would match all songs that contain "nine" and NOT "nails". All
other songs would be removed from the current playlist.
:mode (linear | loop | random)
Set the current playmode to one of the three available options.
The options are:
linear Songs in a playlist are played in the order they
appear until the end is reached.
loop Like linear, but when the end of the playlist is
reached, playback continues at the beginning of the
playlist.
random Songs are chosen at random from the playlist.
:new [name]
Create a new, empty playlist. If name is provided, the new
playlist will be named accordingly unless a playlist with that
name already exists. If no name is provided, the default is
"untitled".
:playlist name
Load the playlist named by name in the playlist window.
:q[!] Quit vitunes. If there are playlists with unsaved changes, then
you are notified of this and prevented from quitting. You can
forcefully quit by using :q!, and any unsaved changes to any
playlists will be lost.
Note that playlists with unsaved changes appear bold in the
library window.
:reload (db | conf)
The reload command is used to reload either the database or con‐
figuration file while vitunes is running. Handy if you update
your database using an e-command while also running vitunes.
:set property=value
The set command is used to set various properties within vitunes.
For properties that accept a value of bool, valid values are
'true' and 'false'.
The following properties are available:
lhide=bool If set to true, the library window will be hidden
(disappear) when it does not have focus.
lwidth=number
Set the width of the library window to number columns
wide. Note that the number provided must be greater
than 0 and less than the width of the terminal.
match-fname=bool
When searching or filtering a playlist, normally the
filenames are also included in the matching algo‐
rithm. This can sometimes be undesirable, particu‐
larly if, for example, all of your music/media reside
in a directory named "media" and you're trying to
search for a file with the word "media" in the title.
To disable this behavior, set match-fnames to false.
save-sorts=bool
Most operations that change a playlist (such as
paste/cut) set the 'needs-saving' flag on the
playlist, such that you are prompted on exiting
vitunes that there is a playlist with unsaved
changes. By default, sorting a playlist does not do
this.
To change this behavior, and be prompted to save
sorts on exit, set this option to true.
:sort sort-description
Sort the currently viewing playlist using the provided
sort-description, which is a comma separated list of: "[-]field",
specifying which fields to sort by and if they should be sorted
ascending or descending.
Valid values for field are: album, artist, comment, genre,
length, title, track, and year. Each field is sorted ascending
by default, unless the field is preceeded with the dash -, in
which case that field is sorted descending.
As an example, the following command:
:sort artist,-album,title
would sort all records in the current playlist by artist (ascend‐
ing) first, then album-name (descending), then title (ascending).
Note that while most operations on playlists set the "needs-sav‐
ing" flag (so you are prompted when quiting vitunes that the
playlist has unsaved changes), sorting a playlist does not do
this. This is intentional. If you wish this behavior to be
changed, see the "save-sorts" option for the set command.
:toggle register command-list
This command will associate a list of commands specified by
command-list to register register. Once set, the list of com‐
mands can be quickly toggled through using the toggle_forward and
toggle_backward keybindings (which default to t and T, respec‐
tively).
Toggle-lists can be useful to quickly alternate through, for
example, various sorting or display schemes that the user may
prefer.
register is any single lower-case letter (a - z) or uppercase
letter (A - Z). command-list is any list of valid commands
listed here, each separated by a backslash character '/'.
As an example, the following would allow one to quickly toggle
through various sorting schemes:
toggle s sort artist,-year,track / sort artist,album,track / sort
-year
Once issued, the three individual sorts specified above can be
toggled using the s register. With the default keybindings this
would be done using either ts (to toggle forward through the
list) or Ts (to toggle backward through the list).
:unbind (* | action action | key keycode)
This command is used to remove existing keybindings. It has
three forms. The first is simply:
unbind *
which will remove all existing keybindings. This is handy in a
configuration file where you may want to define all custom key‐
bindings. Issuing this at runtime will leave you with an
instance of vitunes that will not respond to any keybdings!
The second form is used to unbind actions:
unbind action action
This will remove any keybindings for the action specified by
action.
The third form is used to unbind keys:
unbind key keycode
This will remove any action currently bound to the key specified
by keycode.
See the section SPECIFYING KEYCODES for details on how to specify
keycode, and section KEYBINDING ACTIONS for a listing of all
actions vitunes supports.
:w[!] [name]
Save the currently viewing playlist. If a name is provided, then
the playlist will be saved with this new name. If, however, a
playlist already exists with that name, then you will be pre‐
vented from saving with that name unless '!' is provided, in
which case the existing playlist with that name will be deleted.
SPECIFYING KEYCODES
This section describes how to specify keycodes used in both the :bind and
:unbind commands.
Keycodes are specified in the following fashion:
[Control] (key | SpecialKey)
Here, key is used to specify the actual, printable character entered
which is case-sensitive (e.g. 'j', 'p', 'P'), and SpecialKey is used to
specify various non-printable characters (such as the Page-Up key).
If the string "Control" is also specified, then the keycode only applies
when the control key is pressed in conjunction with the key or
SpecialKey.
Although key is case-sensitive ('p' and 'P' are treated differently),
both SpecialKey and "Control" are case-insensitive.
The currently supported list of non-printable characters available for
SpecialKey are:
Value Description
PageUp The page-up key.
PageDown The page-down key.
Up The up-arrow key.
Down The down-arrow key.
Left The left-arrow key.
Right The right-arrow key.
Backspace The backspace key.
Enter The enter key.
Space The space key.
Tab The tab key.
Some examples of using keycodes and the :bind run-time command are:
bind paste_after p
bind paste_before P
bind scroll_up_halfpage Control u
bind scroll_down_halfpage Control d
KEYBINDING ACTIONS
The current list of available actions that keys may be bound to is the
following. For each action, the default keys bound to them are also
listed.
Action Name Description
scroll_up Scroll the current row in the current window up by
one line.
DEFAULT BINDINGS: k, -, Up
scroll_down Scroll the current row in the current window down
by one line.
DEFAULT BINDINGS: j, Down
scroll_up_page Scroll the current window up by one line.
DEFAULT BINDINGS: Control y
scroll_down_page Scroll the current window down by one line.
DEFAULT BINDINGS: Control e
scroll_up_halfpage Scroll the current window up one half-page.
DEFAULT BINDINGS: Control u
scroll_down_halfpage Scroll the current window down one half-page.
DEFAULT BINDINGS: Control d
scroll_up_wholepage Scroll the current window up one whole page.
DEFAULT BINDINGS: Control b, PageUp
scroll_down_wholepage Scroll the current window down one whole page.
DEFAULT BINDINGS: Control f, PageDown
scroll_left Scroll the current window to the left one column.
DEFAULT BINDINGS: h, Left, Backspace
scroll_right Scroll the current window to the right one column.
DEFAULT BINDINGS: l, Right, Space
scroll_leftmost Scroll the current window to the left as far as
possible.
DEFAULT BINDINGS: ^, 0, |
scroll_rightmost Scroll the current window to the right as far as
possible.
DEFAULT BINDINGS: $
jumpto_screen_top Move the current line to the first line in the
current window.
DEFAULT BINDINGS: H
jumpto_screen_middle Move the current line to the middle line in the
current window.
DEFAULT BINDINGS: M
jumpto_screen_bottom Move the current line to the bottom line in the
current window.
DEFAULT BINDINGS: L
jumpto_line Jump to either a specified line (if a global input
number is present) or to the last line in the cur‐
rent window's buffer.
DEFAULT BINDINGS: G
jumpto_percent Using the global input number N, jump to the line
N% the way through the current window's buffer.
DEFAULT BINDINGS: %
go Go to a specific location within the current win‐
dow. This is planned to be similar to vim(1) 's
use of the 'g' keybinding, with multiple suffixes.
For now, only 'gg' is supported, and this takes
you to the first line in the current window's buf‐
fer.
DEFAULT BINDINGS: g
search_forward Begin a search for the entered string searching
forward in the current window. The current row
will be updated to the next matching row.
DEFAULT BINDINGS: /
search_backward Begin a search for the entered string searching
backwards in the current The current row will be
updated to the next matching row. window.
DEFAULT BINDINGS: ?
find_next_forward Using the previous search-string, search in the
same direction as the search was input for the
next matching row.
DEFAULT BINDINGS: n
find_next_backward Using the previous search-string, search in the
opposite direction as the search was input for the
next matching row.
DEFAULT BINDINGS: N
cut Remove the following N lines from the current win‐
dow, placing them in the copy buffer, where N is
the global input number. Note that if the library
window is active, only one row (playlist) can be
cut/deleted at a time, and that this action cannot
be undone.
DEFAULT BINDINGS: d
visual Begin visual mode. This is only available in the
playlist window, and once begun, only keybindings
that move the cursor within the current window are
allowed. Visual mode is exited when either a yank
or delete operation has been performed, or when
the Escape key is pressed.
DEFAULT BINDINGS: v, V
yank Copy the following N lines from the current window
into the copy buffer, where N is the global input
number. This action cannot be used in the library
window.
DEFAULT BINDINGS: y
paste_after Paste the contents of the copy buffer after the
current row in the playlist window. This action
cannot be used in the library window.
DEFAULT BINDINGS: p
paste_before Paste the contents of the copy buffer before the
current row in the playlist window. This action
cannot be used in the library window.
DEFAULT BINDINGS: P
undo Undo the previous action on the currently viewed
playlist. This action cannot be used in the
library window.
DEFAULT BINDINGS: u
redo Redo the previously undone action on the currently
viewed playlist. This action cannot be used in
the library window.
DEFAULT BINDINGS: Control r
quit Exit vitunes. If there are unsaved changes in any
playlists you will be prevented from exiting until
you either save those changes or issue a ":q!"
command.
DEFAULT BINDINGS: Control c, Control /
redraw Clear and re-draw the entire display.
DEFAULT BINDINGS: Control l
command_mode Enter command-mode, where the commands listed in
the RUN-TIME COMMANDS section may be issued.
DEFAULT BINDINGS: :
shell Enter a command to be executed outsite of vitunes
and in the current shell environment. The output
of the execution is shown before control and the
display returns to vitunes.
DEFAULT BINDINGS: !
switch_windows Toggle focus between the library and playlist win‐
dows.
DEFAULT BINDINGS: Tab
show_file_info Show the file information (including meta-informa‐
tion) for the current row/file in the playlist
window. This action does not work in the library
window.
DEFAULT BINDINGS: m
load_playlist Load the playlist specified by the current row in
the library window.
DEFAULT BINDINGS: Enter
media_play Begin playing the file specified by the current
row in the playlist window.
DEFAULT BINDINGS: Enter
media_pause Pause playback of any playing media.
DEFAULT BINDINGS: z
media_stop Stop all playback of any playing media.
DEFAULT BINDINGS: s
seek_forward_seconds Seek forwards 10 seconds in any playing media.
DEFAULT BINDINGS: f, ]
seek_backward_seconds Seek backwards 10 seconds in any playing media.
DEFAULT BINDINGS: b, [
seek_forward_minutes Seek forwards 1 minute in any playing media.
DEFAULT BINDINGS: F, }
seek_backward_minutes Seek backwards 1 minute in any playing media.
DEFAULT BINDINGS: B, {
media_next Play the next song in the playlist.
DEFAULT BINDINGS: )
media_prev Play the previous song in the playlist.
DEFAULT BINDINGS: (
volume_decrease Decrease the volume.
DEFAULT BINDINGS: <
volume_increase Increase the volume.
DEFAULT BINDINGS: >
toggle_forward Execute the next command from the toggle list
specified by the provided register.
DEFAULT BINDINGS: t
toggle_backward Execute the previous command from the toggle list
specified by the provided register.
DEFAULT BINDINGS: T
Some examples of using the above actions and keycodes to define the
default keybdings are:
bind paste_after p
bind paste_before P
bind scroll_up_halfpage Control u
bind scroll_down_halfpage Control d
CONFIGURATION FILE
The configuration file loaded by vitunes is relatively straight-forward.
Each line may be one of the following:
· A comment, which starts with a '#'.
· An empty line.
· One of the commands from the RUN-TIME COMMANDS section above.
That's it. As such, review the list of commands above.
An example configuration file that would setup some hideous DOS-like col‐
ors is:
# setup colors
color bars=white,blue
color player=yellow,blue
color library=green,blue
color playlist=white,blue
color status=red,blue
# format for playlist window
display artist.20,album.20,title.20,track.4,year.4
# show most recent work of an artist first in library window
sort artist,-year
# make library window 20 columns wide and hide when not active
set lwidth=20
set lhide=true
FILES
~/.vitunes/vitunes.conf
Default configuration file.
~/.vitunes/vitunes.db
Default database file.
~/.vitunes/playlists/
Default playlist directory.
/tmp/.vitunes
Default location for the socket created on start-up that can be
used to control vitunes.
/usr/local/bin/mplayer
Default path to the mplayer(1) binary.
SEE ALSOmplayer(1), realpath(3), strftime(3), vi(1).
More information about TagLib can be found on the TagLib website:
http://developer.kde.org/~wheeler/taglib.html
The vitunes website has additional information, such as a list of fre‐
quently asked questions, a mailing list, and up-to-date bug information.
http://www.vitunes.org
AUTHORSvitunes was written by Ryan Flannery ⟨ryan.flannery@gmail.com⟩.
BUGS
None known.
If you happen to find any, please send a detailed description to me at
ryan.flannery@gmail.com.
BSD April 28, 2024 BSD
