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.


### 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 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 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: linux-xmms,
linux-beep-media-player, linux-amarok, linux-mpg123, linux-mpg123-esd,
linux-amarok, linux-mpg123, linux-mpg123-esd, linux-mpg321,
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
Copyright (c) 2017 by orbea