######################################################################
    rateplay 0.08
######################################################################

NAME
        rateplay - Rate MP3 songs, produce playlists and play them.

SYNOPSIS
        rateplay

     Options:
       -v     print version

DESCRIPTION
    rateplay is a Perl script using the POE framework, a Gtk GUI and the
    musicus (xmms-based) MP3 player.

    It plays MP3s in two different phases: The training phase and the play
    phase. During training, it randomly plays songs from a collection and
    asks the user for ratings on two criteria: The *energize* and the
    *schmoop* level. It stores these ratings persistently in a SQLite
    database (automatic setup, no fiddling required).

    During the play phase, it lets the user select acceptable *energize* and
    *schmoop* levels and randomly plays songs matching these criteria.

    What are *energize* and *schmoop*? The *energize* level of a song
    describes how fast a song is and how much energy the song emits on a
    scale from 1 to 5. The *schmoop* level, on the other end, describes how
    schmoopie a song is. If you're a Seinfeld fan, you'll know what
    schmoopie is ("You're schmoopie! No, you're schmoopie!"), for the rest
    of the world it's the softness of a song, the
    in-certain-situations-playability.

    It's a personal call, but I would rate "Thunderstruck" by AC/DC at an
    <I>energize<I> level of 5 und a <I>schmoop<I> level of 1. On the other
    end of the scale, "Don't Know Why" by Norah Jones would probably get an
    <I>energize<I> level of 1 and a <I>schmoop<I> level of 5.

    Your mileage might vary, but I think it shows the concept. This
    double-rating allows for useful playlist requirements later on, like
    "play fast songs, but none that drive my boy/girlfriend away" with
    allowed energize levels of 4-5 and schmoop levels 3-5.

    Or, "play titles for my bachelor party", with allowed energize levels of
    3-5 and schmoop levels 1-3.

  Advanced Administration Topics
    If you click on the "File->Export" menu, "rateplay" will export the
    content of the rating database to a file named "~/.rateplay" in current
    user's home directory in the following format:

        /ms1/SONGS/pods/029/Soundgarden_-_S12_Fresh_tendrils.mp3|1|1
        /ms1/SONGS/pods/005/Nine_Inch_Nails_-_PHM03_Down_in_It.mp3|5|1
        /ms1/SONGS/pods/025/B-52's_-_NotM10_Roam.mp3|3|1
        /ms1/SONGS/pods/005/Jim_Croce_-_T5AC01_Hey_Tomorrow.mp3|3|4

    That's the mp3 file path, followed by the *energize* and *schmoop*
    ratings in the database. After adapting the paths to a new system's
    requirements, you can import those ratings to another instance of
    "rateplayer" by transferring "~/.rateplay" over to a new location (also
    into the current user's home directory) and clicking on the
    "File->Import" menu.

INSTALLATION
    To adapt the script to your local environment, take a look at these
    three lines at the top of the "rateplay" script:

        our $DB_NAME   = "/data/rp.dat";
        our @SONG_DIRS = qw(/ms1/SONGS/pods);
        our $FIND      = "/usr/bin/find";

    $DB_NAME specifies path and file of a to-be-created SQLite database.
    Just make sure the directory exists, the script will create the database
    file if it doesn't exist yet.

    @SONG_DIRS is an array of directories containing *.mp3 files at any
    depth level. "rateplay" will later traverse these directories and all of
    its subdirectories to find all *.mp3 files in your collection.

    $FIND points to the Unix "find" program which will be used by "rateplay"
    to find your *.mp3 files. "/usr/bin/find" is standard on Linux.

    The script also requires the xmms-based "musicus" MP3 player by Robert
    Muth, available from

        http://muth.org/Robert/Musicus

    If you have a "xmms" installation (if not, get the xmms 1.2.10 RPM),
    just download the latest tarball, type

        tar zxfv musicus.1.13.tar.gz
        cd musicus
        make

    and then copy the binary "musicus" to "/usr/bin".

    The script requires a couple of modules from CPAN:

        Gtk
        Log::Log4perl
        DBI
        DBD::SQLite
        Class::DBI
        Class::DBI::AbstractSearch
        Algorithm::Numerical::Shuffle
        POE
        POE::Component::Player::Musicus

    If installing Gtk turns out to be a bit tricky, just try

        perl Makefile.PL --without-guessing

    If it fails, type

        touch ./Gtk/build/perl-gtk-ref.pod

    try again.

LEGALESE
    Copyright 2004-2005 by Mike Schilli, all rights reserved. This program
    is free software, you can redistribute it and/or modify it under the
    same terms as Perl itself.

AUTHOR
    2004, Mike Schilli <cpan@perlmeister.com>