VITUNES(1)

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

SYNOPSIS
vitunes [-f config-file] [-d database-file] [-p playlist-dir] [-m media-player] [-e command ...]

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

GETTING STARTED
vitunes works by maintaining a database of tagged media files. The database 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 ...]
    This includes creating the initial database, adding, modifying, and removing files from the database, and tagging files. See the E-COMMANDS section below for details.

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

To get started using vitunes, you MUST 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

4.  After that, more files or even URL's can be added to the database using the various e-commands. This can even occur while vitunes is running normally, and the new database can be re-loaded at runtime. Otherwise, the changes will be noticed on the next run.

The default location for everything vitunes uses is:
Configuration File: |
~/.vitunes/vitunes.conf
Database File: |
~/.vitunes/vitunes.db
Playlist Directory: |
~/.vitunes/playlists/
Media Player: |
/usr/local/bin/mplayer

Please note that all files added to the database are stored using their absolute pathname, as obtained from realpath(3). If you move any of your media files around after adding them to the database, you will want to remove them from the database and then re-add them.

DOCUMENTATION
Documentation is divided into the following sections. They are, in order,
1.  COMMAND LINE OPTIONS
2.  E-COMMANDS
3.  THE DISPLAY (a brief description)
4.  KEYBINDINGS (a partial list)
5.  RUN-TIME COMMANDS
6.  CONFIGURATION FILE

COMMAND LINE OPTIONS

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

-f config-file
    Specifies the path of the configuration file vitunes should load. See the section about the configuration file for information on what the configuration can contain.

    The default location is ~/.vitunes/vitunes.conf.

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

-m media-player-path
    Specifies the path to the media player to use. Currently only mplayer(1) is supported.

    The default location is /usr/local/bin/mplayer.

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

E-COMMANDS
Below is a brief summary of each e-command available in vitunes. Complete documentation for each e-command can be obtained by using:
    $ 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 provided is scanned for meta-information, specifically: artist, album, title, track number, year, and play-length. TagLib(3) is used for all meta-extraction, so any meta-data-format TagLib(3) supports (most) is supported by vitunes. Directories are searched recursively. Each file encountered with meta information is added to the database.

vitunes -e addurl http://some-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 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.

vitunes -e check [-rsd] file1 [file2 ...]
    Check an individual file to see its meta information and whether or not it's in the database.

vitunes -e rmfile [-f] file/URL
    Remove a file/URL from the database.

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 flush [-t time-format]
    Dump the contents of the database to stdout in an easy-to-parse format.

For the complete documentation for each of the above e-commands, use
    $ vitunes -e help command-name

THE DISPLAY
When run normally as just vitunes, the default display will show 4 windows.

player
    This window occupies the top row of the display. It 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 by default is only 20 characters wide. It shows each playlist that vitunes was able to load from the playlist directory, and two additional pseudo-playlists which are always shown: the LIBRARY, which is a list of all files/URLs in the database, and FILTER, which is where the results of any :filter ... command are temporarily stored. Note that playlists with unsaved changes appear bold.

playlist
    This window is to the right of the library window and occupies most of the display. It shows the contents of whichever playlist has currently been selected in the library window.

KEYBINDINGS
The following is only a partial listing of the keybindings that vitunes supports. Only those keybindings that are different from vi(1) (or specific to vitunes) appear here. See the website for a complete listing of supported keybindings.

Note that for keybindings, '^' denotes 'CONTROL + '.

ENTER
    In the library window, this loads the currently selected playlist. In the playlist window, this begins playing the currently selected file.

TAB In the library window, this switches focus to the playlist window. In the playlist window, this switches focus to the library window.

z / ^p
    Pause playback of the currently playing file, if any.

s   Stop playback.

f / b
    Seek forwards/backwards 10 seconds in the playback of the currently playing file. If a number N is entered before hand (e.g. 5f is typed), then playback will seek N * 10 seconds forwards/backwards.

F / B
    Seek forwards/backwards 1 minute in the playback of the currently playing file. If a number N is entered before hand (e.g. 5F is typed), then playback will seek N minutes forwards/backwards.

m   In the playlist window, this will show/hide the full filename and meta-information for the currently selected file.

RUN-TIME COMMANDS
Below is an alphabetical 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.

:color item=fg,bg
    Change the color of the given item to fg-colored text on a bg-colored background. Available items are:

    tildas
        The tildas in empty rows
    bars
        The bars dividing the windows
    errors
        Error messages in the status window
    messages
        Informational messages in the status window
    status
        The normal status window
    player
        Player window
    library
        Library window
    playlist
        Playlist window
    playing
        Currently playing row in both library and playlist windows
    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
    length
        The play-length column in the playlist window

    Available colors for fg and bg are: white, black, red, green, yellow, blue, magenta, and cyan.

    256 color support is coming.

:display 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 the display-description is a comma separated list of: [-]<field-name>.<size>. Valid field-names are: artist, album, title, track, year, genre, and length. The size field indicates the number of columns. If the field-name 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 are played in the playing playlist in order until the end is reached.

    loop
        Like linear, but when the end of the playlist is reached, playback continues at the top of the playlist.

    random
        Songs are chosen at random from the playing playlist.

:new [name]
    Create a new, empty playlist. If a 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".

:q[!]
    Quit vitunes. If there are playlists with unsaved changes, then you are notified of such and prevented from quitting. You can forcefully quit if '!' is provided, 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. The following properties are available:

    lhide=<bool>
        Valid values for bool are 'true' and 'false'. 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>
        Valid values for bool are 'true' and 'false'. 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>
        Valid values for bool are 'true' and 'false'. 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 given sort description. A sort description is a comma separated list of: [-]<field-name>, where the dash '-', if present, indicates that the field should be 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.

    Valid field-names are: artist, album, title, track, year, genre, and length.

    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.

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

CONFIGURATION FILE
The default configuration file loaded by vitunes is ~/.vitunes/vitunes.conf, and can be overridden with the -f switch. The format of this file 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 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

SEE ALSO
mplayer(1), realpath(3), vi(1).

More information about TagLib can be found on the TagLib website: http://developer.kde.org/~wheeler/taglib.html

Additionally, the vitunes website has more information, such as a complete list of supported vi(1) -like keybindings 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>.