vitunes

vitunes is a curses-based music player and playlist manager for *nix whose goals are: 1. a minimalistic appearance, 2. strong vi-like bindings, and 3. quick playlist creation/management. vitunes does not strive to be a feature-rich media player, but rather a quick, vi-like media indexer and playlist manager, that just happens to be able to play the music it indexes.

Additionally, vitunes never needs write-access to anything outside of its work directory (default is ~/.vitunes/). It never touches/modifies anything outside of there and doesn't leave junk files anywhere.

Features

News

Documentation

All documentation is in the provided man page, also available online here: vitunes(1).

Keybindings: vitunes-specific
these are subject to change, but easily configurable in `config.h`
key	scope	action
<ENTER>	Library Window	Load currently selected playlist for viewing & switch focus to playlist window
<ENTER>	Playlist Window	Begin playback of currently selected song
<TAB>	Library Window	Switch focus to playlist window
<TAB>	Playlist Window	Switch focus to library window
s	Global	stop playback
z	Global	pause/unpause playback
^p	Global	`" " " "`
nb / nf	Global	Seek backwards/forwards n * 10 seconds in currently playing song
n[ / n]	Global	`" " " "`
nB / nF	Global	Seek backwards/forwards n * 1 minute(s) in currently playing song
n{ / n}	Global	`" " " "`
m	Playlist Window	Show/hide the filename & meta-info for the currently selected file.

Keybindings: Moving-Around & Misc.
key	scope	action
:	Global	Enter command mode. See vitunes(1) for list of all commands.
^l	Global	Erase and redraw display
nj	Global	Move current row down n * 1 lines
n<KEY_DOWN>	Global	Move current row down n * 1 lines
nk	Global	Move current row up n * 1 lines
n<KEY_UP>	Global	Move current row up n * 1 lines
n-	Global	Move current row up n * 1 lines
nh	Global	Horizontally scroll left n * 1 columns
n<KEY_LEFT>	Global	Horizontally scroll left n * 1 columns
n<BACKSPACE>	Global	Horizontally scroll left n * 1 columns
nl	Global	Horizontally scroll right n * 1 columns
n<KEY_RIGHT>	Global	Horizontally scroll right n * 1 columns
n' '	Global	Horizontally scroll right n * 1 columns Note: that's a space.
$	Global	Scroll all the way to the right
'^'	Global	Scroll all the way to the left Note: that's a carrot, not a "CONTROL+"
0	Global	Scroll all the way to the left
n^e	Global	Scroll screen down n * 1 line(s)
n^y	Global	Scroll screen up n * 1 line(s)
n^u	Global	Scroll screen up n * 1 half page(s)
n^d	Global	Scroll screen down n * 1 half page(s)
n^b	Global	Scroll screen up n * 1 full page(s)
n<PAGE_UP>	Global	Scroll screen up n * 1 full page(s)
n^f	Global	Scroll screen down n * 1 full page(s)
n<PAGE_DOWN>	Global	Scroll screen down n * 1 full page(s)
G	Global	Goto last row
nG	Global	Goto row n
n%	Global	Goto the row n% through the total number of rows
nH	Global	Goto the n^th row from the top of current page
M	Global	Goto the middle row of the current page
nL	Global	Goto the n^th row from the bottom of current page

Keybindings: Searching
key	scope	action
/	Global	Get query from user and search forwards in current window for first playlist/file that matches the query. The structure of the query specified is identical to that of the `:filter` command below. See that for more info. Note: In the Library window, only the playlist name is matched against.
?	Global	Get query from user and search backwards in current window for first playlist/file that matches the query. The structure of the query specified is identical to that of the `:filter` command below. See that for more info. Note: In the Library window, only the playlist name is matched against.
n	Global	Jump to the next row in the current window matching the last provided query. If the last query made was done using '`/`', then this search is forwards, otherwise it is backwards.
N	Global	Jump to the next row in the current window matching the last provided query. If the last query made was done using '`/`', then this search is backwards, otherwise it is forwards.

Keybindings: Yank/Delete/Paste
key	scope	action
nyy	Playlist	Yank the next n rows into the copy buffer
yG	Playlist	Yank the rest of the current playlist into the copy buffer
y	Library	Currently can't yank at all in library window. Note: I don't really see a way of doing this in an intuitive way, so it will probably never be added.
ndd	Playlist	Delete the next n rows and copy them into the copy buffer
dG	Playlist	Delete the rest of the files in the current playlist after copying them into the copy buffer
dd	Library	Delete the currently selected playlist Note: Currently, no n can be applied to this in the library window. I simply do not want to be able to delete all of my playlists accidentally.
p	Playlist	Paste the contents of the copy buffer after the currently selected row.
P	Playlist	Paste the contents of the copy buffer before the currently selected row.
p	Library	Paste the contents of the copy buffer at the end the currently selected playlist.
P	Library	Paste the contents of the copy buffer at the beginning the currently selected playlist.

Screenshots

Frequently Asked Questions

How do I change the meta-information of a file within vitunes?

Use the tag e-command (or another application) followed by an update.

I moved a bunch of my music around. How do I update vitunes?

Use the update e-command to remove any moved files and then simply add your moved files again.

For some songs, the percent-complete in the player window is always negative?

When vitunes extracts the meta-information from songs, including playlength, it uses TagLib. If TagLib isn't able to determine determine the play length of the file, vitunes will attempt to determine the length when loading the file, but this isn't always possible either. In these cases, the percent will be negative.

Note: on OpenBSD, the current port of mplayer has problems with ogg files frequently, and the result is often a negative percent/play-time for those files.

How do I backup the vitunes database?

Just copy the ~/.vitunes/ directory. If you have your database/playlists stored elsewhere, just backup those.

Can I have my database/playlists stored elsewhere?

Yes. Use the -d and -p flags as described here.

I have an old version of vitunes with an existing database. When I run the new version, it tells me to rebuild my database. How do I do this?

I had to slightly change the format of the database for this new version. Also, I never included any “version” information in the previous format. This has now been changed. To upgrade an existing setup, download the most recent version below and 1) remove the existing database, 2) re-init the database, then 3) re-add all of your files. e.g.

         $ rm ~/.vitunes/vitunes.db
         $ vitunes -e init
         $ vitunes -e add /path/to/music/ ...

Adding regular files to the database is easy, but adding URL's is somewhat painful. Is there an easy way to automate this?

Of course! You're using *nix, so use a shell script to add all of your URL's, like this one: add_urls.sh.

When exiting vitunes, it seems to hang for one half-second. Why?

This is intentional. The fork()'d mplayer child will fork() an instance of itself whenever it plays an internet radio stream (or similar) to handle the buffering. As such, vitunes needs to wait for this ‘grandchild’ instance of mplayer to exit before quitting.

I found a bug... what should I do?

Email me, and include an extremely detailed description of your bug and how to reproduce it.

The cursor is always visible, even when I'm not in command mode... what gives?

This is most likely a mis-configured $TERM environment variable. Specifically, it's set to something that does not support this particular feature. See the documentation for your OS & terminal emulator (e.g. xterm/rxvt/etc.) for what this should be set to. Note that “xterm-color” almost always has limitations (see here for more information).
On OpenBSD pre 4.7, your $TERM variable, when using xterm, should always be set to xterm-xfree86. After 4.7, just leave your $TERM variable alone.

Scrolling, redrawing, and resizing are all very slow. Is this normal?

If you're using an actual VT100 (or similar) or if you have 1,000,000+ songs in your library, then yes. Otherwise, no. This is mostly likely a misconfigured $TERM environment variable. See the previous F.A.Q. entry.

What license is vitunes distributed under?

ISC.

Download & Install

The current version of vitunes can be downloaded here: vitunes-1.0.5.tgz.
Previous versions can be found here: files/.

IMPORTANT NOTE: vitunes is developed on OpenBSD. It has been ported to FreeBSD by Dennis Herrmann (Thanks!). No other effort has been made (yet) at porting to other OS's. As such there are probably numerous OpenBSD-isms. If you happen port this to another OS, I would be happy to post/link-to the patch/package.

About