xhippo - A GTK-based playlist manager for various UNIX sound players.
xhippo [ options
GNU ` xhippo
' is a generic playlist manager program for a variety of UNIX
sound players. It's been shown to work with ` mpg123
', ` bplay
', ` mtvp
', and should work with more-or-less anything that can take a
filename on the command line. It is capable of automatically deciding which
player to use depending on a file's extension; the defaults are set in a
config file. It uses textual playlist files, which are easily generated with
the ` find
' or `locate
' utilities. The interface of `
' is very loosely modelled on the shareware `HippoPlayer' player
for the Amiga.
' 3 is firmly in maintainance mode; I will continue to fix bugs
if anyone finds any, but new users are strongly advised to try out the
rewritten `Potamus' branch which will eventually become ` xhippo
available from http://offog.org/code/potamus.html
' was developed under GNU/Linux, but it contains nothing
Linux-specific, so it will probably work on any UNIX-like system where gcc,
glib and GTK are available. (Additionally, it supports GNU long options where
is available.) If you're using NetBSD or FreeBSD, a port is
available---see See Installation
. ` xhippo
' can be compiled as a
GNOME 1 application, and it can be compiled against GTK+ 1.2, 2.0 or 2.2. `
' supports standard drag-and-drop (which works with the GNOME,
KDE and ROX file managers, and any other supporting the standard protocol).
' comes with NO WARRANTY, to the extent permitted by law. You may
redistribute copies of GNU ` xhippo
' under the terms of the GNU General
Public License. For more information about these matters, see the file named
If you've installed a previous version of ` xhippo
', read the
for information on what's changed recently.
' uses GNU gettext for internationalisation; you can pick the
language you want by setting your LANG
environment variable. If your C
library's gettext support doesn't work, you can give the
option to the configure
script to make
it use the copy of gettext included in the package.
If you've downloaded ` xhippo
', please send me some mail to tell me what
you think of it. Suggestions for improvements will be gratefully received.
Before reading this section, check that your operating system distribution
doesn't already contain a package for ` xhippo
'. If it does, then you
will probably be best off using that rather than building it by hand. If it
doesn't, or if you want to use a more recent version, then read on.
' uses `GTK+
', and requires `GTK+ 1.2
' or higher;
it needs ` gtk-config
' in your path in order to build. It uses GNU `
' and `autoconf
', so it will automatically detect some
features of your system that can affect ` xhippo
''s performance. If you
have ` libid3tag
' from the `libmad
' package installed (available
along with the ` madplay
' MPEG audio player, which works well with `
', from http://mad.sourceforge.net/
use it to read ID3 tags. (If you don't have it installed, ` xhippo
will use its own simple implementation which only understands ID3v1.)
To compile, change to the source directory and do
If you want (minimal) GNOME 1 support, do ./configure --with-gnome
instead of ./configure
. If you wish to use ` GTK+ 2.0
higher, do ./configure --with-gtk2
. If you encounter problems finding
GTK while building, do ./configure --help
to find out how to
specify where GTK files are stored. If you want to install into a different
place, do ./configure --prefix=/usr/local/xhippo
Several other options are available; try ./configure --help
To install the program, do
Each user who wants to use ` xhippo
' should create a .xhippo
directory in their home directory. ` xhippo
' will look for the
files there, and will save its window state
into the winstate
file there if configured to. Playlists should be kept
in a .xhippo/playlists/
' finds your home directory by looking for the HOME
environment variable. If this is not set by default, you should add a line of
or your shell's equivalent to your profile script.
To use ` xhippo
', you need to give it at least one playlist. You can
either load a playlist by specifying it on the command line or in the config
file, or you can build a playlist by dropping files from a file manager into
the ` xhippo
' window or using the "Add Song" option on the
Playlists are files containing names of files to play, one per line. This is
compatible with XMMS's playlist format, so if you have an XMMS playlist called
, you could do xhippo $HOME/.x11amp/Nice
to use it.
(GQmpeg can also import ` xhippo
' playlists.) Alternately, you can
generate them with the ` find
' command; for instance, if you keep your
.ogg files in your $HOME/sound
directory, you could do
find $HOME/sound -name *.ogg | sort >$HOME/.xhippo/playlists/ogg
to make a playlist and play it. (With a little trickery, ` xhippo
' can be
persuaded to automatically build playlists from a directory on startup; see
the example config file for more information.)
Playlists can also include other playlists by name; to do this, put a line of
in the playlist. ` xhippo
' will then try to load the file foo
playlist, inserting its entries into the list at that point. If the -i
command-line option or readid3
config-file option are enabled, `
' will try to find ID3 tags in the listed files and will put them
in the list rather than the filenames if found.
To start playing automatically once a playlist is loaded, use the -a
option anywhere on the command line (or the autostart
command in the
You can specify multiple playlists on the command line. Alternatively, you can
specify the -f
option to make `xhippo
' treat command-line
arguments as files to be added to the playlist rather than playlists to load
(for instance, xhippo -f *.ogg
), or -D
to make ` xhippo
treat command-line arguments as directories to be searched for playable files.
or xhippo --help
will give you some simple help
The status line shows a little information about the player; it shows the number
of playlist entries upon startup, and what player is being used to play the
current song (and the PID of the player process, if you use -p
in the config file). To start a song, click on it in the
list, or click "Next" to pick either a random song (see the
config file option below to find out how to control this),
or the next song in the playlist, depending on the setting of the
"Random" checkbox. Clicking on "Prev" will play the
previous song (if the "Random" checkbox is enabled, the last random
song picked). To restart the current song from the beginning, click
"Restart". To stop, click "Stop".
' supports a number of keyboard accelerators: `r
Restart, ` s
' or keypad `/
' for Stop, `p
' or keypad
' for Pause, ` n
', keypad `*
' or keypad `-
Next, ` b
' for Prev, ` `
' for Mini, `h
' for Random,
' for Add File, ` d
' for Add Directory, `l
' for Load
Playlist, ` v
' for Save Playlist, ` o
' for Sort By Name,
' for Sort By Swapped Name, ` t
' for Sort By Mtime, `c
for Clear Playlist, ` 0
' to ` 9
' for user-defined menu entries
and ` q
' for quit.
When the end of a song is reached, ` xhippo
' will pick either a random
one or the next one from the list depending on whether the "Random"
checkbox is set or not. Optionally, ` xhippo
' can scroll the list so
that the randomly-picked song is at the top of the visible section; to enable
this, use the -s
command-line option, or the scroll:1
config-file option below. To quit, use your window manager's close button,
pick Quit from the pop-up menu or send ` xhippo
' a `SIGINT'
If you check the "Mini" checkbox, the list of files will disappear,
making the window smaller; unchecking it will make it reappear. You can make `
' start up in this "minified" state by using the
switch or the startmini:1
option in your config file.
You can drop `file:' URLs (such as files from your file manager) onto the `
' window to add songs to the playlist (if you drop a directory,
it will search the directory for files to add). Other URLs (such as `http:')
are not supported, as there's no simple mechanism that all players understand
to stream a file from a network connection.
Right-clicking on the playlist or the status bar will bring up a pop-up menu,
which allows you to bring up an information window for a song showing the
song's size, location and the date it was last modified, move songs up and
down within the playlist, remove songs from the playlist, add songs or
directories to the playlist, sort the playlist by song name, swapped song name
(the part after the first -
in the name) or song mtime, load and save
playlists, or bring up the preferences dialog. The default directory for
loading and saving playlists is $HOME/.xhippo/playlists
on the status bar will bring up the information window for the song that is
If you use the -w
switch or the savewinstate
config file option, `
' will save its window position and size to your
file when you close the window, and will reload
it on startup.
' searches for its config file as
(or wherever you specified with the
option to ` configure
(in the current directory); all that are present will
Most config-file options have a command-line equivalent; these support both
traditional ( -x
) and GNU-style long (--extended
) options. The
long options have the same name as the config-file options; --option
equivalent to option:1
in the config file (i.e. it forces the option
on). The command-line options override the config file. Invoke `
' as xhippo --help
for more information.
Many config-file options are alterable from within the GUI at runtime through
the Preferences dialog, which can be brought up from the context menu.
A config file line starting with a #
will be ignored.
Lines have the format command:arg1:arg2...
. Arguments can be of several
types: booleans, integers, strings and sort types. Booleans represent on/off
or any non-zero integer will
enable the attribute, and any other value will disable it. For sort types,
(or any other unrecognised value) means don't sort, name
(or, for backwards compatibility, any non-zero numeric value) means sort by
means sort by swapped name, mtime
means sort by
The following configuration commands are accepted:
' encounters a file whose name ends in
, it will use command file
to play it. The
extension is case-insensitive. options
is optional and controls how the
player will be started by ` xhippo
'; if it contains g
player will be started in its own process group (necessary to properly kill
some multithreaded players); if it contains i
then the player will be
started with stdin connected to ` /dev/null
type:mp3:mpg123 -b 1024
About the only requirement that ` xhippo
' has on the players that it uses
is that they must quit cleanly when sent a ` SIGTERM
', and be pauseable
with ` SIGSTOP
' and `SIGCONT
'. Some versions of the
multithreaded ` ogg123
' have the problem that, when sent a `
', the main thread exits immediately but the audio device isn't
closed until the buffer is empty (which could be up to a couple of seconds
later). This means that ` xhippo
' thinks the player has exited before
the audio device is available again. This is merely annoying if your operating
system and hardware permits the audio device to be opened by multiple
processes at once, but if it doesn't, then when a song finishes xhippo will
attempt to start the next and fail, and do this repeatedly until the audio
device is available again. One solution is to use another Vorbis player
instead of ` ogg123
' (such as the somewhat-more-heavyweight
If enabled, `xhippo' will play a random song on
startup. This is equivalent to -a on the command line.
If enabled, `xhippo' will scroll the list when a
random item is selected so that the selected song is visible. This is
equivalent to -s on the command line.
If enabled, `xhippo' will always pick an item that
it hasn't played before from the playlist when asked to pick a random entry.
This continues until it has played all the entries, at which point it will
just pick a random one as before. This is equivalent to -m on the
If enabled, `xhippo' will try to read ID3 tags
from the files listed in the playlists and will use them as the playlist
entries if found. This slows down ` xhippo' startup considerably, so
it's disabled by default. This is equivalent to -i on the command
command will be executed as a shell command (using
/bin/sh) before any further config commands are parsed. For an example
of why I included this, look at the example config file (
playlist will be loaded as a playlist file. This
is equivalent to including playlist on the command line.
If enabled, `xhippo' will save its window
position, size and state (whether it is minified or not) between sessions in
the $HOME/.xhippo/winstate file. If it is zero, `xhippo' will
allow your window manager to place it, will start with a "standard"
(small) size, and won't start minified (unless the next option is specified).
This is equivalent to -w on the command line.
If enabled, `xhippo' will start up in the
"minified" state, as if you'd clicked the "Mini" button
(even if the winstate file says that the window wasn't tinified). This is
equivalent to -t (for "tiny") on the command line.
If enabled, `xhippo' will show the PID of its
player process in the status line when not in mini mode. This is equivalent to
-p on the command line.
If enabled, `xhippo' will start with the
"Random" checkbox turned off. This is equivalent to -o on the
If enabled, `xhippo' will strip the extensions
from the filenames displayed in the playlist. This is equivalent to -S
on the command line.
If enabled, `xhippo' will place the vertical
scrollbar on the left side of the playlist. This looks better with
NeXTStep-like themes. This is equivalent to -l on the command
If enabled, `xhippo' will redirect the output
(stdout and stderr) of child player processes to /dev/null. This is
equivalent to -q on the command line.
sorttype specifies how `xhippo' should sort
playlists when they are loaded. -O on the command line is equivalent to
Use dir as the default directory for loading or
If enabled, `xhippo' will replace _
(underscores) and %20s in song names with spaces on the display. This
is equivalent to -d on the command line.
If enabled and either ordered or
mustplayall are turned on, ` xhippo' will stop when all the
items in the playlist have been played. This is equivalent to -1 on the
If enabled, then `xhippo' will set the window
title to include the name of the current playlist. This is equivalent to
-T on the command line.
If enabled, then `xhippo' will use the basename of
the playlist name when setting the window title if playlisttitle is
set. This is equivalent to -b on the command line.
Normally, when a playlist is loaded, `xhippo' will
check to see whether all the listed files exist and discard them if they
don't. If enabled, then ` xhippo' won't bother checking, which will
make startup significantly faster on large playlists. This is equivalent to
-c on the command line. Note that `xhippo' will read the
information if it's needed at a later time, so if you sort the playlist by
mtime then it'll need to scan all the files to get the mtimes.
If enabled, then `xhippo' will write the name of
the song that is currently playing to $HOME/.xhippo/current_song. (If
the file cannot be written, ` xhippo' will silently ignore it.) This is
equivalent to -W on the command line.
Normally when displaying song names in the playlist,
`xhippo' will use the basename of the file (i.e. it will strip off the
path to the file). If integer is set to something other than zero, `
xhippo' will only strip the first integer elements of the path;
this could be useful if you sort your music collection into albums and want to
display the album names in the playlist. This is equivalent to -k
integer on the command line.
Define a user command. This will add an entry titled
description to the context menu (and assign it a numerical accelerator
starting from `0'); when the entry is picked, command will be run (with
a single instance of %s in the command replaced by the full filename of
the selected song, or the empty string if the menu is invoked while not over a
If enabled, `xhippo' will treat command-line
arguments as songs to add to the playlist rather than playlists to load. This
is equivalent to -f on the command line; you can therefore do something
like xhippo -f *.ogg to start `xhippo' listing all the `.ogg'
files in the current directory.
If enabled, `xhippo' will treat command-line
arguments as directories to search for songs to add to the playlist. This is
equivalent to -D on the command line.
If enabled, `xhippo' will remove songs from the
playlist once they have been played. This is equivalent to -x on the
If enabled, `xhippo' will attempt to load a
playlist from $HOME/.xhippo/saved_playlist on startup (if no other
files are given on the command line), and will save the current playlist to
that file on exit. This is equivalent to -P on the command line.
If enabled, `xhippo' will attempt to guess what
the command-line arguments are. If they have a known extension (one specified
with type above) then they are assumed to be songs; if they are
directories they are assumed to be directories; otherwise they are assumed to
be playlists. You probably want this turned on unless you're in the habit of
calling your playlist playlist.ogg. This is equivalent to -g on
the command line.
If enabled and persistplaylist is also enabled,
`xhippo' will save the current playlist whenever a new song is started.
You may want this if you're in the habit of killing xhippo randomly.
To allow for customised GTK appearances, ` xhippo
' reads a standard gtkrc
file in $HOME/.xhippo/gtkrc
. For more information about gtkrc files,
consult the GTK documentation.
If you want an archive to give to somebody else, invoke make dist
in the ` xhippo
' source directory. This will produce the same
file that I distribute. If you wish to mail me a
modified version, do exactly the same (after removing the doc
directory); I can then ` diff
' it against my last release to see what
you've changed. (Alternately, just send me a diff -Naur
between a clean
distributed ` xhippo
' and your modified version.)
' is far from perfect. Please contact <email@example.com>
if you discover any bugs, or have any suggestions.
' was written by me, Adam Sampson, <firstname.lastname@example.org>. My
other software can always be found at http://offog.org/
' is now a GNU ( http://www.gnu.org/
) application and is
distributed from ftp://ftp.gnu.org/
or from mirror sites.
The original German translation was done by Volker Assmann,
<email@example.com>, who was also responsible for betatesting.
Hubert Feyrer first alerted me to the problems with GTK+-1.0 and 1.1
compatibility, and created the NetBSD package. Rod Taylor created the FreeBSD
port, and Kevin Lo created the OpenBSD port.
Craig Knudsen provided a routine to read ID3 tags.
Joseph Turian suggested the idea of file inclusion in playlists.
Jeff Covey supplied a Perl script which provided the functionality of the
current "Load" button, which encouraged me build the feature in.
Kevin Everets implemented the Pause button, the leftscroll option, translated
the documentation to texinfo and provided patches for or suggested various
Several other people who contributed are credited in the ChangeLog
Adam Sampson <firstname.lastname@example.org> and others; see the section ChangeLog