About

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

vitunes...

• can create, modify, search, filter, and sort playlists in a quick, vi-like fashion.
• doesn't need write-access to anything outside of ~/.vitunes/ (by default).
• uses mplayer to play all media, so it can play anything mplayer can.
• uses TagLib for meta-data extraction, so it supports any format it does (nearly everything).
• Supports undo/redo.
• Supports custom key-bindings.
• Can index non-files (things like URL's)...pretty much anything mplayer can play.
• Has an easily customizable display, including format & color
• Loads more...

News

Documentation

Man Page

The primary source of documentation is the man page, which you can view online here: vitunes(1). Be sure to start with the “Getting Started” section of the man page first, to understand the basics of how vitunes works.

e-Commands

vitunes has its own help system for e-commands, but you can view the help output for each e-command below (i.e. vitunes -e help cmd).

• ▪ init
• ▪ add
• ▪ addurl
• ▪ check
• ▪ rm
• ▪ update
• ▪ flush
• ▪ tag
• ▪ help

Complete List of Keybindings

Legend:      Feature is not working yet.      Feature works, but not as may be expected.

Mailing List

vitunes has a mailing list that you can subscrbe to and ask questions about. You can also search the archives if you have any questions.

• To subscribe, visit: http://www.freelists.org/list/vitunes
• The searchable archives are here: http://www.freelists.org/archive/vitunes

Screenshots

Obligatory. Click each to embiggen.

• Default look.
• With 256 color support.
  From @ok100
• Smaller version.
• Library window hidden.
• On Mac OS X.
  From André Berger
• On Mac OS X.
  From Joshua Conner
• Older version.
• Smaller older version.

Frequently Asked Questions

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

The next time you launch vitunes you will see the changes (or you can issue a :reload db command within vitunes).

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/config-file stored elsewhere?

Yes. Use the -d, -p, and -f flags as described in the man page.

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.

Bugs & Other Questions

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

First, do the following, in this order:

1. Read the man page (humor me)
2. Read the F.A.Q. above
3. Search the mailing list archives to see if your “bug” has popped-up before.
4. Search the Bug/Issue database to see if your bug is already known, and if so, add a comment that you too are experiencing it. Provide as many details as possible.

If you've done the above and haven't found your bug/issue mentioned and resolved elsewhere, then email either the mailing list or me, and include an extremely detailed description of your bug and how to reproduce it.

After a song finishes playing, the next song isn't automatically started.

Most likely you're on a Linux with an older version of mplayer. You need mplayer version 1.0rc3 or greater. Alternatively, any version of mplayer built from a checkout of the source after December 29, 2009 will work.

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,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 & Installation

The current release of vitunes can be downloaded here: vitunes-2.3.tar.gz.
Previous versions can be found here: files/.
You can clone / browse my git repository here:

   $ git clone git@github.com:ryanflannery/vitunes.git

Build Dependencies:

Version 1.0.3 and later: TagLib
Versions prior to 1.0.3: libid3tag, libvorbis, and libmp4v2.

Runtime Dependency:

mplayer (version 1.0rc3 or later, or any version built with a checkout of the source after December 27, 2009)

Building & Installing:

The following should suffice:

         $ make install 

For Linux, use the following instead:

         $ make linux install 

By default, vitunes and its man page are installed under /usr/local/{bin,man}. If you don't like this, edit the relevant variables in the Makefile to your liking first.

Uninstallation:

To uninstall vitunes, simply remove the binary and man page, which are installed by default into:

• /usr/local/bin/vitunes
• /usr/local/man/man1/vitunes.1

Notes for Porting/Porters:

vitunes is developed on OpenBSD, and makes use of a few OpenBSD-specific things such as err(3)/warn(3), fparseln(3), strlcat(3)/strlcpy(3), and strtonum(3).

Most of these are picked-up during the build on Linux & Mac OS X and will be added, if needed.

See also the file config.h for setting the default path to mplayer.

Roadmap (Future Work)

Long term goals (i.e. not for a while!):

• Now that OpenBSD supports UTF8, support that (waiting for ncurses(3) support)
• Now that OpenBSD supports 256 color xterms, support that (coming soon!)
• ASCII-art audio visualization.... f' yeah!

P.S. If you like vitunes...

... then you may also enjoy these fine projects:

• ViTunes - a vim plugin that allows you to control iTunes, by Daniel Choi.
• dwb - a really amazing browser using webkit with strong vi bindings and ... tiling! It rocks. A little buggy still, but it looks promising. Once I finish with a cleanup of vitunes here, I'd like to take some time to hack on this.
• vimprobable - a minimalistic browser using webkit with strong vi-like usage.
• surf - another browser like vimprobable, based on webkit and with a srong vi-like usage. from the great devs of suckless.org.
• vimperator - firefox plugin that make it more vi-like. the first attempt to bring vi to a graphical web browser, and inspiration for vimprobable/surf.
• cmus - another curses based music player similar to vitunes.
• practical music search - a curses front-end for mpd.