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. 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 normal- ly. After that, files can be added, modified, or removed from the database, and on the next invocation, vitunes will see the changes (addi- tionally, 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-COM- MANDS 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 or- der, 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 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 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. Com- plete 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 parame- ters. 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-in- formation 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 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 only a partial listing of the keybindings that vitunes supports. Only those keybindings that are different from vi(1) (or spe- cific 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 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. 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 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. 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 April 27, 2010 8