NAME

vitunes — A curses media indexer and player for vi-users

SYNOPSIS

DESCRIPTION

vitunes 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/.

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 issuing:

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-information 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 information.

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 format 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 specified 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 window.

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 window.

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 background 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 currently viewed playlist that do not match (or do match) the provided list of tokens. A song matches the list of tokens if each token appears somewhere in the song's meta-information or filename.

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 configuration 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 algorithm. This can sometimes be undesirable, particularly 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 (ascending) first, then album-name (descending), then title (ascending).

Note that while most operations on playlists set the "needs-saving" 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 commands can be quickly toggled through using the toggle_forward and toggle_backward keybindings (which default to t and T, respectively).

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 keybindings. 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 prevented 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:

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:

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 current 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 window. 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 buffer.
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 window, 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 windows.
DEFAULT BINDINGS: Tab

show_file_info

Show the file information (including meta-information) 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 colors 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 ALSO

mplayer(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 frequently asked questions, a mailing list, and up-to-date bug information.

http://www.vitunes.org

AUTHORS

vitunes 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.