A curses media indexer and player for vi users

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 (whichs is nearly everything).
• Fast indexing. 10,000+ files indexed in 90 seconds. Checking for updates in less than 5 seconds.
• can index non-files (things like URL's)...pretty much anything mplayer can play.
• has an easily customizable display, including format & color

News

Documentation

All documentation is located in the provided man page, which can be viewed 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.

Below is a complete list of keybindings that vitunes supports.

key	scope	action
vitunes-specific these are subject to change, but easily configurable in config.h
<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.
:	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 nth row from the top of current page
M	Global	Goto the middle row of the current page
nL	Global	Goto the nth row from the bottom of current page
Keybindings: Searching
/	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
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.

Legend:      Feature is not working yet.      Feature works, but not as many would expect.

Screenshots

Obligatory. Click each to embiggen.

• Default look.
• Smaller version.
• Library window hidden.
• Some hideous colors.
• Older version.
• Smaller older version.

Frequently Asked Questions

Click each to show/hide the answer.

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.

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

Bugs & Other Questions

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.

Scrolltng, 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

vitunes has been ported to OpenBSD, FreeBSD, and ArchLinux. On these OS's, simply use your normal port/package installer.

The current version of vitunes can be downloaded here: vitunes-1.0.5.tgz.
Previous versions can be found here: files/.
You can clone / browse my Mercurial repository here:

   $ hg clone http://hg.ryanflannery.net/vitunes

Build Dependencies:

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

Runtime Dependency:

mplayer

Building & Installing

The following should suffice:

         $ make 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 the strl*(3) functions, strtonum(3), and err(3) / warn(3).

None the less, porting to non-OpenBSD systems is still rather straight-forward. If you are interested, I would be happy to help.

Roadmap (Future Work)

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

• 256 color support (coming soon!)
• Add undo/re-do abilities (coming soon!)
• Support for :map & :command
• ASCII-art audio visualization.... f' yeah!

If you like vitunes...

You may also enjoy these fine projects...

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

by Ryan Flannery <ryan.flannery@gmail.com> last edited: 11 August 2010 at 01:08:21 pm
valid: xhtml-1.0-strict | css3


(does not track downloads)