<!doctype linuxdoc system>
  <article>
      <title>GNU xhippo
      <author>Adam Sampson, <tt>azz@gnu.org</tt>
      <date>v3.1, 16th April 2001
	
      <abstract>
	This document gives information about how to use GNU xhippo, a
	GTK-based front-end and playlist manager for sound players.
      </abstract>
      
    <toc>
    
    <sect>Introduction

      <p>GNU xhippo is a generic playlist manager program for a
      variety of UNIX sound players. It's 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 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. xhippo's interface is very
      loosely modelled on the shareware ``HippoPlayer'' player for the
      Amiga.

	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 <tt>getopt_long</tt> is
	available.)  If you're using NetBSD or FreeBSD, a port is
	available---see the Installation section. xhippo will
	optionally integrate with the GNOME desktop, supporting GNOME
	themes and drag-and-drop.

	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 you've installed a previous version of xhippo, read the
	ChangeLog for information on what's changed recently.

	If you are using fvwm2, you may like to read
	README.fvwm2. xhippo uses GNU gettext for
	internationalisation; you can pick the language you want by
	setting your <tt>LANG</tt> environment variable. If your C
	library's gettext support doesn't work, you can give the
	<tt>--with-included-gettext</tt> option to xhippo's configure
	script to make it use the copy of gettext included in the
	package.

	You may wish to read <tt>contrib/README</tt>; it contains information
	about the programs submitted by other xhippo users that can be
	found in the contrib directory.

	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.


    <sect>Installation

      <p>Before reading this section, if you're using NetBSD, FreeBSD or
	(probably) OpenBSD, there's an easier way of doing this, as an
	xhippo port is standard. Simply
	<tscreen>
	  <verb>cd /usr/ports/audio/xhippo
make install</verb>
	</tscreen>
	and xhippo will automatically be downloaded and built for
        you. (However, this may not use the latest version, so you
        may want to consider installing it from the source yourself,
        in which case you should follow the instructions below.)

      <p>xhippo uses GTK+, and requires GTK+ 1.0 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 xhippo's performance. If you have
      libid3 installed (available from <url
      url="http://id3lib.sourceforge.net/">), xhippo will 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

	<tscreen>
	  <verb>./configure
make</verb>
	</tscreen>

	If you want GNOME support, do ``<tt>./configure
--with-gnome</tt>'' instead of ``<tt>./configure</tt>''. If you would
also like the GNOME menubar, do ``<tt>./configure --with-gnome
--with-gnome-menubar</tt>'' If you encounter problems finding GTK
while building, do ``<tt>./configure --help</tt>'' to find out how to
specify where GTK files are stored.  If you want to install into a
different place, do ``<tt>./configure
--prefix=/usr/local/xhippo</tt>'' or wherever. Several other options
are available; try ``<tt>./configure --help</tt>'' for more
information.

	To install the program, do

	<tscreen>
	  <verb>make install</verb>
	</tscreen>

	 The archive includes xhippo.xpm; this is a small transparent
	 xpm image that's suitable for use as an icon in your window
	 manager. It's taken from the HippoPlayer NewIcon on the
	 Amiga. I'll try to find a better xpm; I don't like this one
	 very much. It's not installed anywhere, so you should
	 probably copy it in to <tt>/usr/local/share/pixmaps</tt> or
	 wherever your window manager looks for icons.

	 Each user who wants to use xhippo should create a
	 ``<tt>.xhippo</tt>'' directory in their home
	 directory. xhippo will look for the ``<tt>config</tt>'' and
	 ``<tt>gtkrc</tt>'' files there, and will save its window
	 state into the ``<tt>winstate</tt>'' file there if configured
	 to. Playlists should be kept in a
	 ``<tt>.xhippo/playlists</tt>'' directory.

	Xhippo finds your home directory by looking for the
        <tt>HOME</tt> environment variable. If this is not set by
        default, you should add a line of the form
        <tscreen><verb>export HOME=`pwd`</verb></tscreen> or your
        shell's equivalent to your profile script.


     <sect>Invocation

       <p>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 popup menu.

	 Playlists are files containing names of files to play, one
	 per line. This is compatible with X11Amp/XMMS's playlist
	 format, so if you have an X11Amp playlist called ``Nice'',
	 you could do ``<tt>xhippo $HOME/.x11amp/Nice</tt>'' to use
	 it. (GQmpeg can also ``import'' xhippo playlists.)
	 Alternately, you can generate them with the ``<tt>find</tt>''
	 command; for instance, if you keep your .mp3 files in your
	 ``<tt>$HOME/sound</tt>'' directory, you could do

	<tscreen>
	  <verb>find $HOME/sound -name *.mp3 | sort >$HOME/.xhippo/playlists/mp3
xhippo $HOME/.xhippo/playlists/mp3</verb>
	</tscreen>
	
	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

	<tscreen>
	  <verb>!foo</verb>
	</tscreen>

	 in the playlist. Xhippo will then try to load the file
	 ``<tt>foo</tt>'' as a playlist, inserting its entries into
	 the list at that point. If the ``<tt>-i</tt>'' command-line
	 option or ``<tt>readid3</tt>'' 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 ``<tt>-a</tt>'' 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 ``<tt>-f</tt>''
	 option to make xhippo treat command-line arguments as files
	 to be added to the playlist rather than playlists to load
	 (for instance, ``<tt>xhippo -f *.ogg</tt>''), or
``<tt>-D</tt>'' to make xhippo treat command-line arguments as
directories to be searched for playable files.

	 ``<tt>xhippo -h</tt>'' or ``<tt>xhippo --help</tt>'' will
	 give you some simple help instructions.


     <sect>GUI

         <p>
	 (If you built with GNOME, you will see a menu bar at the top
	 of the window; this replicates the buttons described below.)

	 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 ``<tt>-p</tt>'' or
	 ``<tt>showpid:1</tt>'' 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 ``<tt>mustplayall</tt>'' 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
	 ``<tt>-s</tt>'' command-line option, or the
	 ``<tt>scroll:1</tt>'' config-file option below. To quit, use
	 your window manager's close button, pick Quit from the popup
	 menu or send xhippo a <tt>SIGINT</tt> (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 ``<tt>-t</tt>'' switch or the
	 ``<tt>startmini:1</tt>'' option in your config file.

	 You can drop <tt>file:</tt> URLs (such as files from
	 <tt>gmc</tt> or <tt>xftree</tt>) 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
	 <tt>http:</tt>) 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 popup 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 ``<tt> - </tt>''
         in the name) or song mtime, or load and save playlists. The
         default directory for loading and saving playlists is
         ``<tt>$HOME/.xhippo/playlists</tt>''.

	 If you use the ``<tt>-w</tt>'' switch or the
	 ``<tt>savewinstate</tt>'' config file option, xhippo will
	 save its window position and size to your
	 ``<tt>$HOME/.xhippo/winstate</tt>'' file when you close the
	 window, and will reload it on startup.

     <sect>Config file

       <p>xhippo searches for its config file as
	 ``<tt>/usr/local/etc/xhippo.config</tt>'' (or wherever you
	 specified with the --prefix option to configure),
	 ``<tt>$HOME/.xhippo/config</tt>'' and
	 ``<tt>xhippo.config</tt>'' (in the current directory); all
	 that are present will be read.

	 Most config-file options have a command-line equivalent;
	 these support both traditional (``<tt>-x</tt>'') and
	 GNU-style long (``<tt>--extended</tt>'') options.  The long
	 options have the same name as the config-file options;
	 ``<tt>--option</tt>'' is equivalent to ``<tt>option:1</tt>''
	 in the config file (i.e. it forces the option on). The
	 command-line options override the config file. Invoke xhippo
	 as ``<tt>xhippo --help</tt>'' for more information.

	 A config file line starting with a ``<tt>#</tt>'' will be ignored.

	 Lines have the format
	 ``<tt>command:arg1:arg2...</tt>''. Arguments can be of
	 several types: booleans, integers, strings and sort
	 types. Booleans represent on/off conditions;
	 ``<tt>yes</tt>'', ``<tt>on</tt>'', ``<tt>true</tt>'' or any
	 non-zero integer will enable the attribute, and any other
	 value will disable it.  For sort types, ``<tt>none</tt>'' (or
	 any other unrecognised value) means don't sort,
	 ``<tt>name</tt>'' (or, for backwards compatibility, any
	 non-zero numeric value) means sort by name,
	 ``<tt>swapped</tt>'' means sort by swapped name,
	 ``<tt>mtime</tt>'' means sort by mtime.

         The following configuration commands are accepted:

	 <descrip>
	   <tag><tt>type:extension:command</tt></tag>

	     When xhippo encounters a file whose name ends in
	     ``<tt>.extension</tt>'', it will use ``command <it>filename</it>''
	     to play it. The extension is case-insensitive.
             Example: <tt>type:mp3:mpg123 -b 1024</tt>

	   <tag><tt>autostart:boolean</tt></tag>

	     If enabled, xhippo will play a
	     random song on startup. This is equivalent to ``<tt>-a</tt>'' on
	     the command line.

	   <tag><tt>scroll:boolean</tt></tag>

	     If enabled, xhippo will scroll the list when a random item is
	     selected so that the selected song is visible. This is
	     equivalent to ``<tt>-s</tt>'' on the command line.

	   <tag><tt>mustplayall:boolean</tt></tag>

	     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 ``<tt>-m</tt>'' on
	     the command line.

	   <tag><tt>readid3:boolean</tt></tag>

	     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 ``<tt>-i</tt>'' on the
	     command line.

	   <tag><tt>exec:command</tt></tag>

	     ``<tt>command</tt>'' will be executed as a shell command
	     (using <tt>/bin/sh</tt>) before any further config
	     commands are parsed.  For an example of why I included
	     this, look at the example config file
	     (<tt>xhippo.config</tt>).

	   <tag><tt>load:playlist</tt></tag>

	     ``playlist'' will be loaded as a playlist file. This is
	     equivalent to including ``<tt>playlist</tt>'' on the
	     command line.

	   <tag><tt>savewinstate:boolean</tt></tag>

	     If enabled, xhippo will save
	     its window position, size and state (whether it's
	     minified or not) between sessions in the
	     ``<tt>$HOME/.xhippo/winstate</tt>'' 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 ``<tt>-w</tt>'' on the command line.

	   <tag><tt>startmini:boolean</tt></tag>

	     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
	     ``<tt>-t</tt>'' (for ``tiny'') on the command line.

	   <tag><tt>showpid:boolean</tt></tag>

	     If enabled, xhippo will show the PID of its player
	     process in the status line when not in mini mode. This is
	     equivalent to ``<tt>-p</tt>'' on the command line.

	    <tag><tt>ordered:boolean</tt></tag>

	    If enabled, xhippo will start
            with the ``Random'' checkbox turned off. This is
            equivalent to ``<tt>-o</tt>'' on the command line.

            <tag><tt>stripextension:boolean</tt></tag>

            If enabled, xhippo will strip
            the extensions from the filenames displayed in the
            playlist. This is equivalent to ``<tt>-S</tt>'' on the
            command line.

            <tag><tt>leftscroll:boolean</tt></tag>

            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 ``<tt>-l</tt>'' on the command line.

            <tag><tt>hideplayeroutput:boolean</tt></tag>

            If enabled, xhippo will
            redirect the output (stdout and stderr) of child player
            processes to /dev/null. This is equivalent to
            ``<tt>-q</tt>'' on the command line.

            <tag><tt>sortonload:sorttype</tt></tag>

            <tt>sorttype</tt> specifies how xhippo should sort playlists
            when they are loaded. ``<tt>-O</tt>''
            on the command line is equivalent to
            ``<tt>sortonload:name</tt>''.

            <tag><tt>playlistdir:dir</tt></tag>

            Use <tt>dir</tt> as the default directory for loading or
            saving playlists.

            <tag><tt>demanglenames:boolean</tt></tag>

            If enabled, xhippo will
            replace underscores and <tt>%20</tt>s in song names
            with spaces on the display. This is equivalent to
            ``<tt>-d</tt>'' on the command line.

            <tag><tt>onetime:boolean</tt></tag>

            If enabled and either
            <tt>ordered</tt> or <tt>mustplayall</tt> are turned
            on, xhippo will stop when all the items in the playlist
            have been played. This is equivalent to ``<tt>-1</tt>''
            on the command line.

            <tag><tt>playlisttitle:boolean</tt></tag>

            If enabled, then xhippo will
            set the window title to include the name of the current
            playlist. This is equivalent to ``<tt>-T</tt>'' on the 
            command line.

            <tag><tt>titlebasename:boolean</tt></tag>

            If enabled, then xhippo will
            use the basename of the playlist name when setting the
            window title if <tt>playlisttitle</tt> is set. This is
            equivalent to ``<tt>-b</tt>'' on the command line.

            <tag><tt>nocheckfiles:boolean</tt></tag>

            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 ``<tt>-c</tt>'' 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.
 
            <tag><tt>writeplaying:boolean</tt></tag>

            If enabled, then xhippo will
            write the name of the song that is currently playing to
            <tt>$HOME/.xhippo/current_song</tt>. (If the file cannot
            be written, xhippo will silently ignore it.) This is 
            equivalent to ``<tt>-W</tt>'' on the command line. 

<tag><tt>skippath:integer</tt></tag>
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 <tt>integer</tt> is set to something other than zero, xhippo
will only strip the first <tt>integer</tt> 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
``<tt>-k integer</tt>'' on the command line.

<tag><tt>usercommand:description:command</tt></tag>

Define a user command. This will add an entry titled
<tt>description</tt> to the context menu (and assign it a numerical
accelerator starting from <tt>0</tt>); when the entry is picked,
<tt>command</tt> will be run (with a single instance of <tt>%s</tt> 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).

<tag><tt>commandlinesongs:boolean</tt></tag>

If enabled, xhippo will treat command-line
arguments as songs to add to the playlist rather than playlists to
load. This is equivalent to ``<tt>-f</tt>'' on the command line; you
can therefore do something like ``<tt>xhippo -f *.mp3</tt>'' to start
xhippo listing all the <tt>.mp3</tt> files in the current directory.

<tag><tt>commandlinedirs:boolean</tt></tag>

If enabled, xhippo will treat command-line
arguments as directories to search for songs to add to the playlist.
This is equivalent to ``<tt>-D</tt>'' on the command line.

	 </descrip>

     <sect>gtkrc

       <p>To allow for customised GTK appearances, xhippo reads a
	 standard gtkrc file in ``<tt>$HOME/.xhippo/gtkrc</tt>''. An
	 example gtkrc is included as ``<tt>xhippo.gtkrc</tt>''. For
	 more information about <tt>gtkrc</tt> files, consult the GTK
	 documentation. If you're using GNOME, you can leave this file
	 empty, because xhippo will inherit the GNOME themes like any
	 other GNOME application.

     <sect>Distribution

       <p>If you want an archive to give to somebody else, invoke
	 ``<tt>make dist</tt>'' in the xhippo source directory. This
	 will produce the same ``<tt>xhippo-VERSION.tar.gz</tt>'' 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 <tt>diff</tt> it against my last release to see what
	 you've changed.


    <sect>Contact

      <p>xhippo is far from perfect. Please contact <tt>bug-xhippo@gnu.org</tt>
	if you discover any bugs, or have any suggestions.

	xhippo was written by me, Adam Sampson,
	<tt>azz@gnu.org</tt>. My other software can always be found at
	<url url="http://zenchaos.netpedia.net">; xhippo is now a GNU
	<url url="http://www.gnu.org"> application and is
	distributed from ftp.gnu.org or from mirror sites.

	The original German translation was done by Volker Assmann,
	<tt>volka@bigfoot.de</tt>, who was also responsible for
	betatesting.

	Hubert Feyrer first alerted me to the problems with GTK+-1.0
	and 1.1 compatibility, and also maintains the NetBSD package
	at <url
	url="ftp://ftp.netbsd.org/pub/NetBSD/packages/pkgsrc/audio/xhippo/README.html">
	(or <tt>/usr/ports/audio/xhippo</tt> on your NetBSD system).

	Rod Taylor maintains the FreeBSD port (in
        <tt>/usr/ports/audio/xhippo</tt> on FreeBSD 3.2 and up).

	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 and suggested various other features.
 
	Several other people who contributed are credited in the
	ChangeLog file and the contrib/README file.

  </article>