README for Plait v 1.6.2

========================

0. Introduction

---------------

Plait (pronounced "play") can do two things for you: find and play

music from your personal music library, and find and play Shoutcast

radio streams. In order to actually play the music it finds, Plait

hands off a play list to one of the supported music players (iTunes,

Winamp, Beep Media Player, Xmms, amaroK, mpg123, ogg123, mpg321, XSPF

Web Music Player, or Plaiter). The end result is that you can type,

for example,

plait "miles davis"

and any music by Miles Davis that you own will begin playing in your

music player. More complex commands allow you to play mixes of

several albums or artists, read complex mixes from files, reorder the

play list according to one of several patterns, select a certain

number of tracks, queue tracks, send commands to the music player, and

more.

I wrote Plait because I was looking for an alternative to tedious

point and click digging through my music library, on the one hand, and

tedious typing of long file names, on the other. The solution used by

Plait is based on "hints", which are basically fragments of song

titles, artist's names, or album names. You specify as many hints as

needed to get exactly the music you want. For example, rather than

typing out the complete file name

"/music/Billie Holiday/Ken Burns Jazz/Solitude.wav"

or digging through a file requester to find this file, with Plait one

types

plait billie solitude

When you already know exactly what you want to hear, this is really

the quickest and easiest way to let the computer know (and when you

don't know exactly what you want to hear, Plait has an interactive

mode that allows you to browse tracks, albums, artists, and radio

streams.)

Even though it searches the entire music library every time it creates

a play list, Plait is optimized for these types of queries (it caches

your music directory) and can perform them very quickly. With a

medium sized music collection of about 3,000 tracks, queries take less

than a second. On Cygwin, which can be slow, queries take a little

longer-- about 2.5 seconds on a 700 mhz system.

0.1 What's new

---------------

Release 1.6.2 is a security upgrade which cleans up all security flaws

related to temp files.

Release 1.6.1 is a maintenance release to track recent changes in the

Shoutcast.com web site. You will need it if you want to continue

running stream queries.

1. About that name...

----------------------

"Plait" is French for "it pleases," because it is so pleasing to use.

It also suggests the soundalike English word "play," which describes

what it actually does. You might say it's a plait on words. At one

point in the misty past, Plait was known as "play," but that name was

taken.

2. Searching your music library

-------------------------------

Plait doesn't make any assumptions about the layout of your music

library, but the better organized it is, the more useful the searches

you can do. Ideally your file paths contain artists, albums, and song

titles. In that case you can provide a hint about an artist and get

all the material by that artist:

plait mingus

You can provide a hint which matches just one album:

plait "kind of blue"

Or you can match a single song

plait "blue in green"

(Although examples like these will typically "just work," keep in mind

that Plait doesn't actually know that "Kind of Blue" is an album or

Mingus is an artist. If you have a song named "Mingus", it will play

also. Other options were considered, but this method is the easiest

to use, and it seems to work very well. In fact, it is almost always

possible to create a hint that picks exactly the music you want. See

the section on advanced hinting for more information.)

Because Plait scans your entire music library when matching hints, you

are not limited to results from one directory. So if you have a

compilation album that is distributed by artist throughout your

collection, you can play the whole thing by searching for the album

name. Similarly, you can play an entire album series, as in

plait --random "ken burns jazz"

This type of matching is also useful when you want to play several

cover versions of the same song.

Querying the entire music library for songs rather than finding files

by directory also helps resolve some problems of categorization that

come up when ripping a CD collection. If you rip Cecilia Bartoli's

"Vivaldi Album," for example, do you store that as

/music/Vivaldi/The Vivaldi Album feat. Cecilia Bartoli

so that you can play it as Vivaldi music, or

/music/Cecilia Bartoli/The Vivaldi Album

so that you can play it as Cecilia Bartoli music? With Plait, it

doesn't matter because, either way, the album will turn up when you

type `plait cecilia` or `plait vivaldi`.

Sometimes one hint is not enough to say exactly what you mean, so

Plait does not place any limit on the number of hints you can specify.

This comes in handy when you have a song title that is used by more

than one artist. In my music collection, for example, if I type

plait "walk on"

I will hear "Walk On" by Neil Young, "Walk On" by U2, and the album

"Walk On" by John Hiatt (which includes a song named "Walk On").

Additional hints allow me to disambiguate:

plait "walk on" neil # Neil Young's version

plait "walk on" u2 # by u2

plait "walk on/" # the album by John Hiatt

plait "walk on[.]" hiatt # just the song

(The last two examples are a little tricky. They work by matching the

path separator or the dot in ".mp3". See the section on advanced

hinting for more ideas.)

This feature also comes in handy when you want to avoid typing a long

song title, but the short hints available are ambiguous. If I use the

hint "someday" for example, I get "Someday" by the Strokes, and

"Someday We'll All Be Free" by Charlie Hunter. The command

plait charlie someday

gives me exactly what I want. Feel free to use hints that are easy to

remember rather than trying to be efficient. That is one of the

purposes of hinting, beyond just putting you on a first name basis

with your favorite artists (or you could type `plait someday be` and

save a few keystrokes; it's up to you).

There is an implicit logical "and" between the hints in these

commands, although you do not need to think of it that way if you are

a non-programmer. In any case, you get just the songs that match

*all* the hints, rather than any of the hints. (As we will see later,

there is another type of search in which there is an implicit "or" and

you get songs that match *any* of the hints.)

Sometimes positive assertions about the music you want to hear are not

sufficient to say exactly what you mean. For these situations the

`not` keyword, which allows you to exclude songs that match a hint, is

provided. As an example, the following command plays some music by

Herbie Hancock, leaving out one track that I set aside for special

occasions:

plait herbie not rockit

You can use as many "not" hints as you like, but you have to make at

least one positive assertion about the music you want to hear, and it

has to be the first hint on the command line. Therefore

plait not miles

will look for a song named "not" by Miles Davis. This is intentional.

If you really want to hear random selections from almost your entire

collection, you can just use a very broad positive assertion, as in

plait --random ".*" not miles

(".*" is a regular expression that matches anything. See the section

on advanced hinting.)

The features explained so far allow you to pick out a particular

track, artist, album, or series, but sometimes you are interested in

mixing together material from several artists or albums. In that case

you will want the `--mix` option, which picks tracks that match *any*

of your hints rather than all of them. For example

plait --mix metheny hunter "tj kirk" "broun fellinis"

will create a play list with a selection of jazz artists. Because it

allows me to do something that would be totally impractical with CDs,

the ability to make mixes has changed my listening habits more than

any other feature of Plait.

3. Playing radio streams

-------------------------

Plait can search the Shoutcast web site, find stations matching your

query, and play them in your music player. If you are interested in

hearing trance music, for example, you might try

plait --stream trance

You can use a hint that contains spaces by enclosing it in quote

marks, as in

plait --stream "modern jazz"

As of Plait 0.53, stream queries support multiple hints and the `not`

keyword, just like music library queries. This allows you to search

for radio stations much more selectively than before. The `--mix`

keyword is also supported, but not the `as` keyword or mix files. The

current thinking is that these features would be of limited usefulness

with streams.

Genre hints work well, because the Shoutcast directory includes a

genre in the description of each radio station, but you can try other

types of search, including by station name, call letters, artist or

country.

By default, you get the most popular stations matching your query, but

if you don't like the popular stations in a certain genre, you can mix

things up with the `--random` option (see below). For performance

reasons, Plait limits you to ten streams (because they take a while to

load into the music player), but you can request more with the

`--tracks` option. In interactive mode, the number of streams is

unlimited.

Examples:

plait --stream --random --tracks 5 jazz not smooth

plait --stream 70s

plait --stream bachata

plait --stream NPR -i

4. Mix Files

-------------

As you make more complex mixes you may begin to use so many hints that

they become inconvenient to type. At this point you will be ready for

mix files. Once you have created an appropriate mix file with a hint

for each jazz artist in your collection, for example, you can type

plait --mixfile jazz --random

to play random selections from your entire jazz collection. Creating

mix files is easy because they are just text files with lists of

hints, but Plait is also capable of creating mix files for you. First

let's look at creating a mix file by hand. Mix files are stored in a

subdirectory of your music directory. Specifically, if your music

directory is /music, the mixfiles are at /music/.plait/mixfiles.

(Storing them here rather than in plait's working directory allows you

to continue using your mix files when you are accessing your music

collection as a guest on someone else's computer.) To create a mix

file for jazz, then, you might type the following into

/music/.plait/mixfiles/jazz:

"billie" "blakey" "brubeck" "coltrane" "dolphy" "getz"

"hunter" "metheny" "miles" "mingus" "ornette" "rollins"

"scofield" "stanton" "surman" "thelonious"

(The hints should be separated by spaces or line feeds. It is only

necessary to enclose a hint in quote marks if it contains a space.)

That's all there is to it.

Plait also has a simple syntax for creating mix files automatically,

using the `as` keyword. For example, the following command creates a

mix file and plays some cuts from it simultaneously:

plait --mix galactic "scott amendola" "oranj symphonette"

as postjazz

The `as` keyword also comes in handy when you need to maintain mix

files. Let's say you have a jazz mix file and you acquire some new

music by Herbie Hancock. You can add him to the jazz mix as follows:

plait --mixfile jazz herbie as jazz

If Herbie Hancock were already in your jazz mix, no harm would be

done--Plait makes sure that each hint occurs exactly once.

You can use more than one mix file with a `plait` command. This allows

you to create a "mix of mixes," for example:

plait --mixfile jazz --mixfile postjazz as alljazz

In general, you can combine mix files and hints freely on the command

line, allowing you to play variations on a given mix depending on your

mood:

plait --mixfile jazz not miles not ornette

Because they are based on hints, mix files have some of the features

of play lists and some of the features of genres. As with play lists,

a given artist can be included in as many mix files as you like. This

allows you to create free form, overlapping categories for artists,

rather than being forced to assign each artist to a single fixed

category. As with genres, on the other hand, once an artist belongs

to a mix, any new music you purchase by that artist is automatically

added to the mix. In this sense mix files are more dynamic than play

lists.

(By the way, nothing said here should be taken to mean that mix files

always have to consist of artist hints. That is probably the typical

case, but there is nothing to prevent you from using album hints or

song hints in your mix files.)

Since you create mix files yourself, they require a little more work

than genres, which can probably be assigned using automated tools.

But it really doesn't take long to create mix files, and you will find

that the added flexibility is worth the effort.

5. Playlist optimization

-------------------------

When you create a mix featuring two artists, it is most likely that

you would like to hear approximately the same number of tracks from

each artist. But if, for example, you have 6 albums by artist A and

only 2 by artist B, tracks by artist A will dominate the playlist

Plait creates. As of Plait 1.2 there is a playlist optimizer which

addresses this problem by balancing the playlist. It has other nice

features as well.

You need to enable the playlist balancer by setting a track count with

the `--tracks` option; otherwise you get the old behavior where Plait

selects all the tracks that match your hints. There are special

symbolic track counts which control the behavior of the playlist

balancer. Some examples will clarify:

plait -l --mix "miles davis" "charles mingus" --tracks all

This command creates a playlist with all the available tracks from

Miles Davis and Charles Mingus. This is also the default behavior if

you don't specify a track count.

plait -l --mix "miles davis" "charles mingus" --tracks min

This command determines the number of tracks in the smallest hint

group and then creates a balanced playlist by selecting that number of

tracks from each group. Some tracks from larger hint groups will be

skipped.

plait -l --mix "miles davis" "charles mingus" --tracks max

This command determines the number of tracks in the largest hint group

and then creates a balanced playlist by selecting that number of

tracks from each group. Some tracks from smaller hint groups will be

repeated.

plait -l --mix "miles davis" "charles mingus" --tracks avg

This command determines the average number of tracks per group and

then creates a balanced playlist by selecting that number of tracks

from each group. Some tracks may be skipped and some tracks may be

repeated.

plait -l --mix "miles davis" "charles mingus" --tracks 20

This command creates a balanced playlist with approximately 20 tracks.

Tracks may be skipped or repeated depending on the particular count

you specify and the number of tracks in the source playlist.

Because Plait is designed to create unique playlists every time you

run it, there is a lot of random fudge in the algorithm that balances

playlists. The track counts you specify are just goals; they are

translated into a probability that tracks from each group will be

selected and this is combined with a random number to determine

whether each track is selected. As a result, the playlist will

contain a number of tracks close to the goal you specify but not

necessarily exactly the same.

#### Weighting the balance

It's not always the case that you want to hear exactly equal amounts

of music from each artist, and Plait provides a simple way to weight

the balance when you don't, by repeating hints. The following command

creates a mix with more tracks by Miles Davis than John Coltrane:

plait -l --mix davis davis coltrane --tracks 15

This sets a 2:1 ratio between Miles Davis tracks and John Coltrane

tracks as a goal. Depending on the content of the source playlist,

the goal may or may not be achieved exactly. Tracks will not be

repeated in order to achieve the goal; the effect of repeating hints

is just to give each track a "second chance" in the case where it is

not printed the first time it matches a hint.

This technique can be used to generate a playlist with a featured

artist or featured album, for example

plait -l --mixfile jazz 58 58 --tracks 30 --stripe

This command creates a playlist with a variety of Jazz tracks, but

featuring the album "'58 Sessions" by Miles Davis.

#### Patterns

The playlist optimizer also allows you to order the tracks in the

playlist according to one of several patterns:

plait -l --mix "miles davis" "charles mingus" --tracks 15 --sort

The --sort option causes the tracks to appear in sorted order

plait -l --mix "miles davis" "charles mingus" --tracks 15 --stripe

The --stripe option picks one track matching hint a and then one track

matching hint b, in an alternating pattern. Within the stripes, the

tracks appear in sorted order.

plait -l --mix "miles davis" "charles mingus" --tracks 15 --stripe2

--stripe2 is similar to --stripe, but within the stripes the tracks

appear in random order.

plait -l --mix "miles davis" "charles mingus" --tracks 15 --fade

The --fade option arranges the tracks matching each hint according to

a gaussian distribution. The effect is that tracks matching each hint

are clustered around a certain position in the playlist and appear

less frequently as you move away from that position. Thus each

section of the playlist focuses on one artist, but there are no rigid

boundaries between the sections.

plait -l --mix "miles davis" "charles mingus" --tracks 15 --random

In this case tracks are arranged randomly.

plait -l --mix "miles davis" "charles mingus" --tracks 15 --group

The --group option groups the tracks by hint and shuffles randomly

within each group.

#### Target devices

The final new feature of the playlist optimizer is intended to help

people with a mixture of lossy and lossless encodings in their music

libraries. It filters the playlist so that the encoding types you

specify are either preferred or used exclusively, allowing you to

create playlists that are suitable for a variety of target devices,

including Hi-Fi stereos, disk-based portable music players, and

flash-based portable music players. Examples:

plait doors --device hifi

This command selects tracks in both lossless and lossy formats. If a

given track is available in more than one format, the lossless

encoding is preferred. It is suitable for a home stereo with high

quality audio. This is also the default device.

plait doors --device medium

This command selects tracks in both lossless and lossy formats. If a

given track is available in more than one format, the lossy

encoding is preferred. It is suitable for a disk-based portable music

player.

plait doors --device compact

This command selects tracks in the mp3 format only. It is suitable

for a flash-based portable music player like the iPod Shuffle.

You can define your own target devices or change the default device in

the config file. See section 10.

In all cases, two files are considered to be the same track in

different formats if the file paths are identical except for the

extension. Thus the following two files are considered to be the same

track in two different formats:

/music/Miles Davis/Kind of Blue/Blue in Green.wav

/music/Miles Davis/Kind of Blue/Blue in Green.mp3

The following two files are not considered to be the same track in two

different formats:

/music/WAV/Miles Davis/Kind of Blue/Blue in Green.wav

/music/MP3/Miles Davis/Kind of Blue/Blue in Green.mp3

6. Options

-----------

These options provide finer control over the music you play:

### --list, -l

Learning to use hints involves trial and error. The `--list` option

facilitates this by allowing you to see what songs a hint will play

without actually playing them. Its use is self-explanatory. If you

like the songs listed, you don't have to run the query again to play

them. Simply typing

plait

without any hints plays the list returned by the last query.

### --queue, -q

Normally the songs found by a `plait` command will play instantly,

interrupting whatever was playing when you typed the command. If you

want the songs to be added to the play list, use `--queue`. They will

begin playing after the previous play list completes (mpg123 and

mpg321 do not support queuing, but Plaiter, which is a front end to

those programs, supports queuing and several more features.)

### --random, -r

By default, songs are sorted by file path. If your music library is

organized by artist, album, and title, your playlists will be

organized the same way. If your song names are preceded by track

numbers, they will play in album order. `--random` is for those times

when you want a little variety. It shuffles the play list before

sending it to your music player.

### --sort

Plays tracks in sorted order. --sort is also the default.

### --stripe

Arranges tracks in an alternating pattern with one track matching hint

a, followed by one track matching hint b, and so on until all of the

hints have been used; then the pattern repeats. Within the stripes,

tracks appear in sorted order. This option does not apply to stream

queries.

### --stripe2

Arranges tracks in an alternating pattern with one track matching hint

a, followed by one track matching hint b, and so on until all of the

hints have been used; then the pattern repeats. Within the stripes,

tracks appear in random order. The hints themselves are also

shuffled, so you get a different pattern every time. This option does

not apply to stream queries.

### --fade

Clusters the tracks matching each hint around a particular position in

the playlist, in a gaussian distribution. Thus each section of the

playlist is focused on tracks matching one hint, but there are no

rigid boundaries between the sections. Within each cluster, tracks

are distributed randomly. This option does not apply to stream

queries.

### --group

Groups tracks by hint. Within hint groups, tracks appear in random

order. This option does not apply to stream queries.

### --stream, -s

Plays Shoutcast radio streams (see Section 3). Examples:

plait --stream --random --tracks 5 salsa

plait --stream kplu

plait --stream chinese

plait --stream --random reggaeton

### --tracks, -t

Normally, Plait plays at most ten radio stations at a time, or an

unlimited number of tracks. More than that and your music player will

freeze for a while, which can seem broken. This option allows you to

override the default values. For example

plait --mix --tracks 10 "nick cave" "nick drake"

plait --stream --tracks 20 industrial

As of Plait 1.2, this option behaves differently depending on whether

or not you are doing a stream query. For stream queries, the track

count must be a number and it is a simple limit on the number of

stations that will be selected.

For library queries, the track count is a goal for the playlist

balancer. In addition to particular numbers, there are symbolic track

counts which control the behavior of the balancer, including min, max,

avg, and all. See Section 5.

### --mix, -m

This option selects songs which match *any* of the hints you provide

rather than *all* of them. As an example,

plait --mix "broun fellinis" "stanton moore" motherbug

creates a play list with tracks by three bands. This option does not

effect negative assertions.

### --mixfile, -f

This option causes Plait to read hints from a file. Tracks are then

selected from the music library just as if you had typed the hints on

the command line with the `--mix` option. See Section 4. You can use

this option multiple times to specify more than one mix file:

plait -f punk -f rock

plait --mixfile punk --mixfile rock

Just as `--mixfile` causes Plait to read hints from a file, the `as`

keyword causes Plait to write hints to a file, for example:

plait "neil young" "john hiatt" "nick drake" "john cale" \

as folkrock

In naming mix files, it is best not to use spaces. You can force

Plait to accept a mix file with a space in its name by enclosing the

name in quote marks, but in this case Plait will just replace the

space with a dash. So

plait --mix belafonte strummer as "calypso punk"

will actually create a mix file named "calypso-punk". The same

logic applies to the --mixfile option, so

plait --mixfile "calypso punk"

will correctly find the file you created. The only time you need to

be aware of this rule is when you create mix files by hand--don't use

spaces in their names.

### --device, -d

This option specifies a target device for the playlist. The target

device determines what kinds of files will be selected or preferred.

There are three predefined target devices: "hifi" accepts all file

types but prefers lossless encodings when a given track is available

in more than one encoding; "medium" accepts all file types but prefers

lossy; and "compact" accepts lossy encodings (mp3) only. It is

possible to define your own target devices; see the section on

customization.

### --cache, -c

You need to run `plait` with this option whenever the contents of your

music directory changes. Plait will rescan the entire music directory

and find every new piece of music. Keep in mind that each guest

configuration has its own cache. As of Plait 0.53 this option has an

optional directory argument which causes the rescanning to be

restricted to a subdirectory of your music library, useful for doing a

quick update when you have added, renamed, or deleted music by a

single artist. For example, if your music directory is /music,

plait -c "David Kane Quartet"

will rescan only the `/music/David Kane Quartet` directory. It only

takes about a minute to scan a 3,000 track music library, so if you

lose track of which directories you have scanned, you may simply want

to rescan everything.

Important note: if you rename an artist or album, you may have to run

two cache commands to register the change correctly. If, for example,

you moved music by the band R.E.M from the directory R.E.M to the

directory REM, you would run the commands

plait -c R.E.M

plait -c REM

The first command will delete old cache entries that point to songs

which no longer exist. The second command will register the songs in

their new location.

### --guest, -g

This option provides support for multiple, named configurations. The

main reason you would want this is that each configuration can have a

different music directory. So if a friend has a music collection that

is accessible on your LAN, he will be able to play his music from your

computer. To use this feature, just provide a guest name, for example

plait --guest mypal "einsturzende neubauten"

The first time you use a new guest name, Plait will ask for the

location of that guest's music directory. Subsequently, the location

will be remembered. It is up to you to mount the guest music

directory, if that is necessary. This feature should be particularly

useful if you have a VPN set up, but I have not had a chance to test

that.

When you use a guest configuration you also get the guest's mix files

(and lose your own mix files temporarily). It is done this way

because mix files tend to be compatible with the collection for which

they were created.

### --platform

This option allows you to temporarily override the default platform.

The single argument can be any of the values allowed for the variable

PLATFORM.

### --coverart

This option allows you to temporarily override the cover art setting.

"--coverart 1" causes cover art to be located on the Amazon.com web

site when creating XSPF playlists. "--coverart 0" turns off this

feature.

### --interactive, -i

This option selects interactive mode, in which each track or station

in the playlist is presented for you to vote yes or no on. When

editing tracks, the available responses are:

* y or yes: play this track

* n or no: don't play this track

* Y or Yes: play this track and all remaining tracks

* N or No: don't play this track or any of the remaining tracks

* u or up: move up one level in the hierarchy (from tracks

to albums, for example).

* d or down: move down one level in the hierarchy

* /: search forward

By moving up one or two levels you can vote on albums or artists all

at once. When searching, you may enter a search term immediately

after the slash. A slash by itself repeats the prior search. If

there was no prior search you will be prompted for a search term.

For the purpose of moving through the hierarchy, the character "/" is

used to separate the levels. If your music library is laid out

differently, you can set this to something else in the config file,

for example,

LEVELSEP=" - "

In more complex cases, you may want to use a regular expression, for

example,

LEVELSEP="(/| - )"

For display purposes, the "/" character will be used as the separator,

but the regular expression will be used internally.

When editing radio streams, the available responses are:

* y or yes: play this stream

* n or no: don't play this stream

* Y or Yes: play this stream and all remaining streams

* N or No: don't play this stream or any of the remaining streams

* /: search forward

Plait does its best to present a helpful description of each stream,

but sometimes the Shoutcast web page will outwit Plait's regular

expression-fu and you will see HTML gunk in the description.

### --play

This option forwards the command "play" to the music player.

### --pause

This option forwards the command "pause" to the music player.

### --stop

This option forwards the command "stop" to the music player.

### --next

This option forwards the command "next track" to the music player.

### --prev

This option forwards the command "previous track" to the music player.

### --install

This option installs Plait. You will normally need to do this only

once, but it may also come in handy if Plait stops working because an

important file is deleted. To do a complete reinstall, run this

command from the install directory. You should run this option as

root, using the `su` or `sudo` command.

### --uninstall

This option uninstalls Plait. It is up to you to uninstall any

prerequisites you had to install to make it work, if you don't want

them anymore. If you installed Plait as root, you should run this

option as root, using the `su` or `sudo` command.

### --help

Shows brief help text.

### --version

Shows information about the version of `plait` you are using, the

license, and the author.

7. Advanced hinting

--------------------

Plait hints are actually extended regular expressions that will be

executed by a `grep` command, which fact enables certain advanced

queries. If you are familiar with regular expressions, some examples

have probably occurred to you already. This section provides some

ideas for the uninitiated.

Simplicity is one of Plait's goals and as a result a division is drawn

between simple queries, which include several hints that must all be

matched, usually narrowing the results to a song or an album, and mix

queries, which match any of their hints. But sometimes you would like

a query which combines a little of both. For example, what if you

want to hear "Solitude" by Billie Holiday (but not by Marc Ribot) and

"Walk On" by Neil Young (but not by U2). One solution is to use two

queries:

plait billie solitude

plait -q "walk on" neil

However, there is a one line solution which depends on the fact that

in regular expressions, the string ".*" matches anything. By

exploiting this fact we can combine two hints into one complex hint.

The resulting command is

plait --mix "billie.*solitude" "neil.*walk on"

In this way the "and" part of each query is built into a single hint

and then the two complex hints are "or"-ed together with the `--mix`

option. A variation on this idea is to combine the "or" parts of a

query into a complex hint and then "and" it with another hint. For

example, the following query plays three of my favorite tracks by

Charlie Hunter:

plait charlie "flau|dersu|revo"

The fact that ".*" means "anything" is also useful if you are simply

looking for a way to play a little of everything from your

collection. For example, the following query plays 17 random tracks:

plait --tracks 17 ".*" --random

Some of the more interesting regular expressions will rely on the

naming conventions you use in your music library. Here's one that

works if your tracks are numbered. It will play the first two tracks

of each John Coltrane album in a collection:

plait coltrane "0[1-2]"

#### Eponyms

The fact that Plait uses whole path matching occasionally results in

ambiguous hints when albums and songs are named eponymously. However,

it is generally easy to come up with a precise hint with a little

thought. The following suggestions assume that your music library is

organized by Artist/Album/Song, but similar techniques would apply to

other layouts. An example of an album and song with the same title is

"Walk On" by John Hiatt. Here the trick is to match the path

separator, in order to pick the album, or the dot before the file

type, in order to pick the song:

plait "walk on/" # the album

plait "walk on[.]" # the song

The brackets are necessary around the dot because dot is a regular

expression matching any single character. The brackets tell Plait

that we really mean a literal dot.

Distinguishing an eponymous album from the artist is a little trickier

because they will both end with the path separator. For example,

Charlie Hunter has a self-titled album which appears in my music

collection as

/music/Charlie Hunter/Charlie Hunter/

Typing `plait "charlie hunter"` will give me everything by that

artist, not just the album I am interested in. In this case the

secret is to match a combination of artist and title which is unique

to the album "Charlie Hunter," for example

plait "Charlie Hunter/Charlie Hunter"

or just

plait "Hunter/Charlie"

(or `plait ter/cha` for the terse-minded).

#### Using precise hints

Many of the examples in this document use a relaxed form of hinting

which is convenient and easy. Most of the time hints like these will

"just work". Every once in a while, though, this approach breaks

down. For example,

plait miles

may get you

/music/Byrds/Eight Miles High

/music/Who/I Can See for Miles

rather than the Miles Davis music you might have been looking for.

Likewise,

plait rem

may get you

/music/Talking Heads/Remain in Light

rather than music by the band R.E.M. In cases like this you should

just use a more precise hint, ie

plait "/miles davis/"

or

plait /rem/

8. 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