
cluck is a TUI xmms2 client program written in Chicken Scheme, but
available as pure C (because Chicken is awesome like that).  See
FEATURES for the feature list.

Requirements
============

General Usage
-------------

XMMS2 DrKosmo, or a current snapshot if DrKosmo isn't out yet.  I
apologize for this requirement, but it wasn't possible to do file
renaming or moving without it, and that feature is a lot of the
reason I wrote the client in the first place.  I found the process
of installing the latest snapshot pretty easy; just make sure you
have all other versions removed first.  See
http://wiki.xmms2.xmms.se/index.php/Download_XMMS2#Source

PCRE (in the form of libpcre.so.3 OSLT)

XMMS2 client lib (in the form of libxmmsclient.so.2 OSLT)

Curses (in the form of libncurses.so.5 OSLT)

Song Tag Editing
----------------

If you want to edit song information *and* you want that information
written back to the song file, you'll need the programs "id3v2" (for
mp3 files) and "vorbiscomment" (for Ogg Vorbis files) in your path.
You'll also need write permissions on the files and the directories
they are in, and the file names need to end in .mp3 or .ogg as
appropriate.

Installation
============

Unless you already have Chicken and really want to use the Chicken
version (in which case, you're pretty much on you're own) you'll
want to go to the cluck-c directory and run "make".  This should get
you a file named "cluck", which should be all you need.

Yes, I know this is a half-assed installation instruction, but it's
straight C, it really shouldn't be a big deal.  If you have
problems, mail rlpowell@digitalkingdom.org with "cluck" in the
subject line somewhere.

Note that warnings like:

    Warning: local assignment to unused variable `f_binding' may be
    unintended

can be totally ignored.

The Horrible Startup Delay
==========================

Yeah, sorry about that.  The issue is that to get a list of all
properties used by all songs in the database (which is later used
for song editing and column selection), I have to iterate over every
property in every song in the entire database.  If this bothers you,
add a cranky note to http://bugs.xmms2.xmms.se/view.php?id=1684

If that bug shows as resolved, send a mail to
rlpowell@digitalkingdom.org so I can update the code.

The startup data does cache, though, so you should only need to deal
with this when you update the database.  In particular, if you add a
new artist, or if you add new properties, definately run the update
step, which is  "cluck -r".

Request For Suggestions
=======================

I'm really not a very good program designer, and since I designed
this from scratch, it's particularily bad.  It's obviously an
accretion of parts, that don't fit well together.

I specifically request that if you can think of any way to improve
the user interface, you send me mail at rlpowell@digitalkingdom.org.
Streamlining the interface is particularly important/welcome.

Non-Obvious Features
====================

Song Property/Info Editing
--------------------------

E: edit song info
and
W: toggle prop->file writing

When you edit the information associated with a song, you are
editing properties associated with the song in xmms2's media
library.  If you have prop->file writing turned on, and you have the
auxillary propgrams id3v2 and/or vorbiscomment installed (depending
on whether you're writing back mp3 or ogg files), those tags that
can be written back to the song file itself will be.

Note that the writing back is a bit of a hack: it uses shell calls
to the id3v2 and vorbiscomment programs.  It's brittle and prone to
annoying failures.  It does, however, work, which is all I was
looking for at the time.

Creation of Collections
-----------------------

N: New collection; filter view only.

Collections kind of need to be based on a search to start with, so
go to the filter view and arrange the search you want, then press N
to create your new collection based on that search.

Song Tagging & Collections
--------------------------

A: Add a property to a song
N: New collection; filter view only.
T: Manage song tags

An obvious use for collections is to manage tags on songs, that is
to keep a list of songs that are fast, or slow, or offensive, or
wordless, or etc.  Something like a song's genre, but more
multifarious and more personal.  There are a few ways to get
something like this out of xmms2, but the way Cluck handles it is a
combination of query-based collections and boolean (either on or
off) properties.  Cluck views any integer (number) property that is
only ever set to either a 0 or a 1 as a tag-like property, and shows
them in the manage tags view.

So, to make a list of songs with a particular new tag, use the "Add
a property" key to add the tag you want to any song.  Make sure it's
a "number" type tag and is set to 1.  Then filter on "tag:1" (for
whatever your tag is); you should get the one song.  Save that as a
collection, and every song you give this tag to in the future should
show up in that collection (since collections are dynamic).  Then
use the "manage song tags" key to add that tag to as many songs as
you like.

I know that's a bit tedious, but the first two steps only need to be
done once for each tag.

Ratings, Auto-Rating & Auto-Skipping
------------------------------------

R: Manage song ratings
CTRL-r: Turn on auto-rating
CTRL-k: Turn on auto-sKipping

Ratings are used to give the system a sense of how much or how
little you like a song.  You can use this to create collections or
with the auto-skip feature.

You may be surprised to be asked for a user name when you first try
to rate a song (please select something without spaces in it).  This
is so, in theory, you can have multiple users with auto-skip turned
on (see below) and The Right Thing will occur.  This grows out of me
writing Cluck as a sort of replacement to mserv, where this is a key
feature.

Properties in xmms2 are strings or integers (whole numbers), so to
accommodate the auto-rating feature, the ratings are 100-500 (in
increments of 100) instead instead of 1 through 5.  100 is bad, 500
is good, as you can see by using R to manage the ratings.

If you have auto-ratings turned on, skipping a song, selecting a
song, or previousing back to a song will alter the ratings by an
amount you choose when you first turn on auto-ratings.  Skipping
reduces the rating, selecting a song or previousing back to it
increase the rating.

Auto-skipping simply skips any songs below the limit you specify.
This can be done with multiple users: each copy of Cluck will
respect the user name entered by the person who ran it, and so
everyone's Cluck will auto-skip the songs they really dislike.
