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"

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.