Manual Reference Pages - XHIPPO (1)
xhippo - A GTK-based playlist manager for various UNIX sound players.
xhippo [options] [dir | file ...]
GNU xhippo is a generic playlist manager program for a variety of
UNIX sound players. Its been shown to work with mpg123,
madplay, bplay, s3mod, tracker, xmp,
mtvp, splay, ogg123 and timidity, 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 files 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
xhippo is very loosely modelled on the shareware HippoPlayer
player for the Amiga.
xhippo 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 4,
available from http://offog.org/code/potamus.html.
xhippo 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 getopt_long is available.) If youre 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. xhippo supports standard
drag-and-drop (which works with the GNOME, KDE and ROX file managers,
and any other supporting the standard protocol).
xhippo 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 COPYING.
If youve installed a previous version of xhippo, read the
ChangeLog for information on whats changed recently.
xhippo uses GNU gettext for internationalisation; you can pick
the language you want by setting your LANG environment variable.
If your C librarys gettext support doesnt work, you can give the
--with-included-gettext option to the configure script to
make it use the copy of gettext included in the package.
If youve downloaded xhippo, please send me some mail to tell me
what you think of it. Suggestions for improvements will be gratefully
Before reading this section, check that your operating system
distribution doesnt 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 doesnt, or if you want to use a more recent version,
then read on.
xhippo uses GTK+, and requires GTK+ 1.2 or
higher; it needs gtk-config in your path in order to build. It uses GNU
automake and autoconf, so it will automatically detect
some features of your system that can affect xhippos
performance. If you have libid3tag from the libmad
package installed (available along with the madplay MPEG audio
player, which works well with xhippo, from
http://mad.sourceforge.net/), xhippo will use it to read
ID3 tags. (If you dont 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 or 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 or wherever. Several other options are
available; try ./configure --help for more information.
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
config and gtkrc files there, and will save its window
state into the winstate file there if configured to. Playlists
should be kept in a .xhippo/playlists/ directory.
xhippo finds your home directory by looking for the HOME
environment variable. If this is not set by default, you should add a
line of the form
or your shells 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 XMMSs playlist format, so if you have
an XMMS playlist called Nice, 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 the form
in the playlist. xhippo will then try to load the file
foo as a playlist, inserting its entries into the list at that
point. If the -i command-line option or readid3
config-file option are enabled, xhippo 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 config file).
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.
xhippo -h 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 or showpid:1 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 mustplayall 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".
xhippo supports a number of keyboard accelerators: r for
Restart, s or keypad / for Stop, p or keypad +
for Pause, n, keypad * or keypad - for Next, b
for Prev, for Mini, h for Random, a for Add File,
d for Add Directory, l for Load Playlist, v for Save
Playlist, o for Sort By Name, w 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
managers close button, pick Quit from the pop-up menu or send
xhippo a SIGINT Ctrl-C.
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 xhippo start up in this "minified" state by using the
-t switch or the startmini:1 option in your config file.
You can drop file: URLs (such as files from your file manager) onto
the xhippo 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 theres 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 songs 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. Left-clicking 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, xhippo will save its window position and size to your
$HOME/.xhippo/winstate file when you close the window, and will
reload it on startup.
xhippo searches for its config file as
/usr/local/etc/xhippo.config (or wherever you specified with the
--prefix option to configure), $HOME/.xhippo/config
and xhippo.config (in the current directory); all that are
present will be read.
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 is equivalent to option:1 in the config
file (i.e. it forces the option on). The command-line options override
the config file. Invoke xhippo as xhippo --help for more
Many config-file options are alterable from within the GUI at runtime
through the Preferences dialog, which can be brought up from the
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 conditions; yes, on, true or any non-zero
integer will enable the attribute, and any other value will disable it.
For sort types, none (or any other unrecognised value) means dont
sort, name (or, for backwards compatibility, any non-zero numeric
value) means sort by name, swapped means sort by swapped name,
mtime means sort by mtime.
The following configuration commands are accepted:
When xhippo encounters a file whose name ends in
.extension, 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
then the 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. Examples: 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
SIGTERM, the main thread exits immediately but the audio device
isnt 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 doesnt,
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 mplayer).
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 hasnt 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 its
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 wont 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
youd clicked the "Mini" button (even if the winstate file says that the
window wasnt 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 command line.
If enabled, xhippo will strip the extensions from the filenames
displayed in the playlist. This is equivalent to -S on the
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 line.
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 saving playlists.
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 command line.
If enabled, then xhippo will set the window title to include the
name of the current playlist. This is equivalent to -T on the
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 dont. If
enabled, then xhippo wont 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 its needed at a later time, so if you sort the playlist
by mtime then itll 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 song).
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 command line.
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 youre
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 youre 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 xhippo-VERSION.tar.gz 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 youve changed. (Alternately, just send me a
diff -Naur between a clean distributed xhippo and your
xhippo is far from perfect. Please contact
<firstname.lastname@example.org> if you discover any bugs, or have any
xhippo was written by me, Adam Sampson, <email@example.com>. My
other software can always be found at
http://offog.org/; xhippo 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,
<firstname.lastname@example.org>, 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 other features.
Several other people who contributed are credited in the
Adam Sampson <email@example.com> and others;
see the section ChangeLog for details.
|Version 3.5 ||XHIPPO (1) ||27th August 2007 |
Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.