plait/INSTALL

Install Guide for Plait v 1.6.2
===============================

1.  Installation
----------------

Since Plait is glue ware, it has several dependencies.  Follow these
instructions to make it all work.


### Uninstallation

As of Plait 1.5.2, it is possible to install Plait to a directory of
your choice.  Since this could lead to a situation where you have
multiple versions of Plait installed in different directories, it's a
good idea to uninstall any old versions of Plait prior to upgrading.
But if you know you are installing to the same directory as the old
version of Plait, this isn't really necessary.


### Windows/Cygwin prerequisites

Running Plait on Windows requires that you install Cygwin, the open
source UNIX compatibility layer for Windows.  Follow the instructions
at Cygwin.com to download and install Cygwin.  Plait also requires two
optional packages, wget and gawk.  Be sure to select these packages
when you run Cygwin Setup.

For those who are using Winamp, you may need to install it.  Get
Winamp at Winamp.com.

In order to control Winamp, Plait uses a COM object written by John
Adcock.  To install it:

* Download gen_com.zip from www.adcock8.freeserve.co.uk/winamp.htm
* Unzip.
* Copy gen_com.dll into the C:\Program Files\Winamp\Plugins directory.
* Restart Winamp.  Winamp will detect and install the new plugin.

For those using iTunes, a standard installation of that program should
work without any additional steps, but you need to edit the file
~/.plait/config to make iTunes your music player.  Change the line
that defines PLATFORM to read

    PLATFORM=cygwin-itunes


### OS X prerequisites

Running Plait on OS X requires one package that isn't part of the
default install: wget.  You can compile wget from source and install
it yourself, if you know how to do that sort of thing.  The easier
option is to install "fink" and have fink install wget for you:

* Download fink from fink.sourceforge.net.  Follow the instructions
provided there to install it.

* Now install wget.  Type 

        sudo apt-get install wget

    and enter your administrator password when prompted.

(Users of Plait 0.53 and earlier also need to take the following step:

* Install gawk and findutils.  Type

        sudo apt-get install gawk findutils

Newer versions of Plait don't depend on these packages.)


### GNU/Linux prerequisites

On GNU/Linux, Plait works with ogg123, mpg123, mpg321, Xmms, Beep
Media Player, or amaroK.  If you are using Xmms, xmms-shell is also
required.  Installation varies depending on your distro.  Be sure to
install the package esound if you want to play via esd.

Xmms, Beep Media Player, or amaroK will be used if they are present.
If not, Plaiter will be used as a front end to any command line
players that are present.  Otherwise Plait will work in "list only"
mode unless you configure your own player.


### Finishing up (all operating systems)

You now have all the prerequisites to run Plait.  The last step is
installing Plait itself:

* Untar the package:

        tar xvzf plait-x.xx.tar.gz
        cd plait

* Tell `plait` to install itself.  You may run this command as a
  non-root user, in which case Plait will default to installing in
  your home directory; you may run it as root, in which case Plait
  will default to installing in /usr/local; or you may set the install
  directory to anything you like by providing an argument.  Examples:

        su -c "./plait --install"

    or

        sudo ./plait --install

    or

        ./plait --install

    or

        sudo ./plait --install /usr

If you install Plait as a non-root user, you may have to add ~/bin to
your path.

Plait is now ready to run.  The first time you run it, Plait will do
some additional self-installation which involves asking for the
location of your music directory.  You only have to do this once.


### Setting up for XSPF

If you want to use the XSPF web publishing feature, you will need to
install the XSPF Web Music Player
(http://musicplayer.sourceforge.net).  Download and unpack the player
from that address and then copy the file xspf_player.swf to
~/.plait/xspf.

If your music library is located on a web server, you also need to set
the variable BASEURL, for example:

    BASEURL=http://www.example.com/mp3/

Otherwise, leave BASEURL set to the empty string.

If your music directory is laid out as Artist/Album/Song, you're all
set.  Otherwise, you may need to set the three variables ARTISTIDX,
ALBUMIDX, and SONGIDX in the config file.  For Example, if your music
directory is laid out as Artist/Year/Album/Song, set

    ARTISTIDX=1
    ALBUMIDX=3
    SONGIDX=4

If your music directory is laid out as Artist/Artist - Album - Song,
set

    LEVELSEP="(/| - )"
    ARTISTIDX=1
    ALBUMIDX=3
    SONGIDX=4


2.  Uninstallation
------------------

If you installed Plait as root, you must be root to uninstall it;
otherwise you must be the same user as you were during installation.

Type 

    su -c "plait --uninstall"

or

    sudo plait --uninstall

or just

    plait --uninstall

to uninstall Plait.  See the instructions that came with gen_com if
you want to remove that plugin.  To remove wget, gawk or findutils,
follow the package removal technique for Cygwin or Fink, as
appropriate.  If you are updating Plait, and you decide to install it
into a different directory this time, uninstall the old version before
installing the new one.  Otherwise two versions of Plait will be
installed and you can't be sure which one will run.


3.  Customization
------------------

There are a few changes you can make to ~/.plait/config to customize
the behavior of Plait.


#### File types

By default Plait looks for files of type mp3, wav, aif, ogg and flac.
You can change this by setting the variable TYPES, for example:

    TYPES=".ogg .mp3 .flac"

You may need to run `plait --cache` to rebuild the cache after
changing the file types.

As of Plait 1.2, you are advised to set the variable TYPES once to a
very broad set of file types, and then use target devices to customize
your playlists for different devices.  You can either redefine one of
the built-in target devices, or define a new one.  For example, to
define a target device that supports the same file types as an iPod,
add the following line to the config file:

    ipod="m4a M4A mp3 MP3 wav WAV"

In contrast to the TYPES variable, with devices you don't include the
dot in the file extension, and you must repeat each extension twice,
in upper and lower case.  In this list, order is important; thus the
ipod device will prefer mp3 files to wav files.

To use this device to build a playlist, select it on the command line:

    plait britney --device ipod

You can also set the default device in the config file:

    DEVICE="$ipod"

Important note: if you redefine the default device (hifi), you should
then reassign DEVICE to it in the config file, ie:

    hifi="wav WAV flac FLAC"
    DEVICE="$hifi"

Otherwise DEVICE will continue to have the old value of hifi from
before it was redefined.


#### Alternate players

Although there is a default player on each operating system, some OSs
support several players.  You can pick something besides the default
by setting the variable PLATFORM, for example:

    PLATFORM=linux-plaiter

The currently supported platforms are: cygwin-winamp, cygwin-itunes,
osx-itunes, linux-xmms, linux-beep-media-player, linux-amarok,
linux-mpg123, linux-mpg123-esd, linux-mpg321, linux-mpg321-esd,
linux-ogg123, linux-ogg123-esd, linux-plaiter, any-xspf and
any-xspf-copy.  In the interest of accuracy, there are also "unix-"
synonyms for all the "linux-" players.  The "esd" platforms play via
the Enlightened Sound Daemon, which can stream audio across the
network to an esd server.  You specify which server by setting
ESPEAKER, for example:

    ESPEAKER=192.168.1.2:16001

See README.plaiter for information on Plaiter, which is the ideal
platform choice if you currently use a command line player like
mpg123.


Copyright (c) 2005, 2006 by Stephen Jungels