VITUNES(1) OpenBSD Reference Manual 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. vitunes does not strive to be a full-blown media player, but rather a full-blown media indexer and playlist manager. Further, it does not re- quire write-access to anything outside of its work directory (default is ~/.vitunes/ ). It never touches/modifies anything outside of there. GETTING STARTED Before using vitunes, it's important to understand the following: • vitunes maintains a database of all media files it knows about. • vitunes can only work with media files in this database. • vitunes manages (creates/removes/etc.) its own set of playlists. • The database is managed using "e-commands" to initialize, update, and add media files (or URL's) to the database. • Playback is managed by a fork(2)'ed instance of, currently, mplayer(1). • 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 Management of the vitunes database is described in the documentation for each e-command. A quick reference to get started follows. 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 vitunes normally with $ vitunes 4. Add more files/URLs with $ vitunes -e add ~/music/new/ $ vitunes -e addurl 'http://...' 5. And update your database (after removing/chainging any files) with $ vitunes -e update 6. That's it. Once an initial database is created, vitunes can always be run with just $ vitunes DOCUMENTATION Documentation is divided into sections. They are, in order, 1. Command Line Options and E-Commands. An overview of how to use vitunes from the command line, including using e-commands to setup, manage, and maintain your database. 2. The Display. A brief description of the vitunes user interface. 3. Keybindings. A list of keybindings specific to vitunes. Those shared with vi(1) are omitted for brevity. See website for complete listing. 4. Commands. A complete list of all commands supported by vitunes. 5. The Configuration File. A brief explanation of what may be in the configuration file. COMMAND LINE OPTIONS AND E-COMMANDS -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 op- tion 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 in- formation 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 on- ly mplayer(1) is supported. The default location is /usr/local/bin/mplayer. -e command options This is how one uses the e-commands mentioned above, which are responsible for creating and maintaining the media database used by vitunes. There are 8 commands available. Below is a brief summary of each. For more information on each, use vitunes -e help <command-name> COMMAND DESCRIPTION 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 un- changed. add This command takes any number of files/directo- ries as parameters. Each file provided is scanned for meta-information, specifically: artist, album, title, track number, year, and play-length. TagLib is used for all meta-extrac- tion, so any meta-data-format TagLib supports (most) is supported by vitunes. Directories are searched recursively. Each file encountered with meta information is added to the database. addurl This command is used to add non-files (things like URL's for Internet radio stations) to the database. It can also be used to update the meta-info of an existing URL in the database. update 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. check Check an individual file to see its meta informa- tion and whether or not it's in the database. rmfile Remove a file/URL from the database. tag Add/modify the meta-information tags of raw files. flush Dump the contents of the database to stdout in an easy-to-parse format. Again, see vitunes -e help command-name for more information on each. THE DISPLAY When run normally as just vitunes, the default display will show 4 win- dows. 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 be- haves very similar to the command/status window in vi(1). library This window occupies the left-side of the screen, and by de- fault 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 occu- pies most of the display. It shows the contents of whichever playlist has currently been selected in the library window. KEYBINDINGS The following is a list of keybindings and commands that are specific to vitunes, and not vi(1). Most of the vi(1) keybindings for moving around, searching, yank/delete/paste are supported. See the vitunes website for a complete listing of all keybindings and full description of each. 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 cur- rently playing file. If a number N is entered before hand (e.g. 5F is typed), then playback will seek N minutes for- wards/backwards. m In the playlist window, this will show/hide the full filename and meta-information for the currently selected file. COMMANDS Below is an alphabetical listing of all commands supported by vitunes. 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. display display-description The display command is used to change which columns are dis- played 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-informa- tion 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 re- moved from the current playlist. The list of tokens is simply any list of strings, each possi- bly preceded with an exclamation point. If a token is pre- ceded 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. Howev- er, 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 op- tions. 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 de- fault 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 vi- tunes. 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 mu- sic/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 prompt- ed to save sorts on exit, set this option to 'true'. sort sort-description Sort the currently viewing playlist using the given sort de- scription. 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 (as- cending) 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 com- mand. w[!] [name] Save the currently viewing playlist. If a name is provided, then the playlist will be saved with this new name. If, how- ever, a playlist already exists with that name, then you will be prevented from saving with that name unless '!' is provid- ed, in which case the existing playlist with that name will be deleted. THE 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 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 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 com- plete list of supported vi(1) -like keybindings and up-to-date bug infor- mation. 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>. OpenBSD 4.6 January 20, 2010 7