
    @version $Id: README,v 1.4 2005/01/14 00:52:35 davidfancella Exp $

*****************************************************************
Welcome to the readme file for pyAlarm!
*****************************************************************

pyAlarm is a hardcore alarm clock for hardcore sleepers.

Right now, you have several choices of what to do if you're on Linux.  You can:

1.  Install pyMad and pyao using your distributions automatic dependency resolution system, be it
emerge, urpmi, or apt-get.

2.  Install pyAudiere.  A little trickier, but you can do it.

3.  Install pygame, which in turn requires SDL.  Again, use your distribution's automatic dependency
resolution system.

Any one of these three will get you audio playback.  Here's what you get, respectively:

1.  mp3 playback ONLY
2.  mp3 and ogg (more coming, as soon as I verify what Audiere builds with and what I can reliably expect
on a user's machine)
3.  mp3 and ogg (the pygame plugin is slated to be removed, however)

If you downloaded the Windows installer, you have Audiere already, but no mixer.  Sorry, the only mixer
currently supported is OSS in Linux.  So you'll need to use your sound card driver's mixer to set levels
on the computer, and then your amplifier's/speaker's volume knob to make sure it's loud enough.

To run pyAlarm, it *MUST* be installed.  This has to do with its fancy plugin architecture.  The plugins
can't resolve their own dependencies if pyAlarm isn't installed.  This is not a problem if you downloaded
the Windows self-installer.  It's also not a problem if you're installing from rpm.  It may be a problem
if you need to install it from source but don't have root access, or you don't want to install software with
such a low version number with Python's dist-utils that don't provide an uninstaller.

**************************************
A word about the plugins
**************************************

I have mixed feelings about putting up rpms with dependencies.  The nature of Linux is that every program
written has 3+ dependencies.  pyAlarm already has Python and wxPython.  Python is just about guaranteed to
be on your system, but pyAlarm requires 2.2 or higher, and some installations are still running really old
Pythons.  To play music, pyAlarm would need more dependencies.  Audiere, to my knowledge, isn't packaged for
any distribution in a manner that allows your automatic dependency resolver to deal with it.  pyMad and pyao
are available for many distributions in an easy to install package, but each of those has its own C library
it depends on.  So both of those for pyAlarm makes a total of 4 dependencies, and that's just for mp3 playback!
pygame is the smallest hitter, because it depends on SDL and does its own automatic dependency resolution (i.e. it
doesn't load modules that don't have the SDL library installed to support it, but lets you work with any that
do), but it's also the worst player for pyAlarm because it doesn't give you volume control.  It does, but not
a very good volume control.  Then it still doesn't play as loud as the soundcard is capable of playing.

So I wrote up a plugin system that does its own dependency resolution.  So if you load up pyAlarm and it doesn't
play music, it's probably because you don't have any of the libraries installed you need.  But pyAlarm will still
install and run just fine!  It just won't be able to make any real noise.  I toyed with having the plugins
to be downloaded as separate files, but decided it didn't make sense to make you download two packages for
a stupid alarm clock.  So I packaged the plugins back with pyAlarm, and with no dependencies marked.

The plugin system is designed to allow any arbitrary type of action plugin to be used as an alarm.  I don't intend
pyAlarm to be limited to playing music because music isn't the only way to wake someone up.  So it doesn't
make sense for someone who's, say, deaf, to have to install tens/hundreds of megabytes worth of music libraries
just to get the base alarm clock!

So the plugins do their own dependency resolution, and it's limited to trying to load the modules they depend on.
If that fails, the plugin is disabled.  Useful text gets written to the console right now, better reporting
is planned.  On Windows, you don't get this useful information.  But then, on Windows you get Audiere already,
so you don't even have to deal with it.

If you don't like the dependencies currently available for the plugins, you'll need to write your own plugin.
The simplest plugin to copy is probably going to be paMad.py, but paAudiere.py is pretty simple too.  Just do
what you see there, depend on what you want, and you'll be fine.  If it's a non-audio plugin, or an audio plugin
that somehow eliminates dependencies, send it my way.  If you can maintain it, I'll consider including it
in the core distribution.  Since the plugins are so good at figuring out for themselves if they work, it's
relatively painless to include whatever plugins in the core distribution I want, so my only criteria are that
the plugins use the API properly (as demonstrated in existing plugins) and that you will be able to maintain your
plugin over API revisions.  If a plugin loses its maintainer at an API revision, it'll get pulled from the
distribution because the chances that I'm going to have time to maintain OPP (Other People's Plugins) are pretty
slim.  In fact, there are only two chances, and if you can guess both of them I'll send you a cookie.

I am, however, considering making a plugin that uses wxPython's wxSound object, or whatever that particular
class is called.  That would be no extra plugins, and instant sound.  The only problem is that it's only wav
files, and only short wav files, so no streaming.  I can fair use some pretty awesome samples, though.  I can
also include MOD files that the Windows build using Audiere will be able to play out of the box.  So there
are options available, and when I find the time I'll pursue them.

Patches to deal with any of these issues are welcome.

*****************************************************************
Installing pyAlarm
*****************************************************************

There are several ways you can install pyAlarm, depending on what you downloaded.  If you're running on a
Mandrake system that is *NOT* Mandrake 10.1, I suggest you follow option #3.  You might also follow that
option if your distribution has a program to install an rpm even though it's not an rpm-based distribution.
If you're a Debian fanatic, make Python's distutils support you and I'll build the package.  If you're
a Gentoo zealot, you know what to do.  Patches accepted.  If you're anyone else, you know what to do.  If you
still don't know what to do, better ask someone.  The real problem with python's distutils is that they
don't offer a way to uninstall the package if it fails during installation, or if it just doesn't work for
you.

1.  If you downloaded a source distribution, you can install pyAlarm with Python's distutils, like so:

./setup.py install

2.  If you downloaded an rpm, then you should be using an rpm-based distribution.  I built this rpm
under Mandrake 10.0, so it should work on Mandrake 10.0, and likely nothing else.  But you can install
it by first becoming the superuser, and then typing something like:

rpm -Uvh pyAlarmVERSION.noarch.rpm

3.  If you are using an rpm-based Linux and you want to try installing an rpm, and you downloaded a
source distribution, you should be able to use python's distutils to build an rpm for you.  Try:

./setup.py bdist_rpm
cd dist
rpm -Uvh pyAlarmVERSION.noarch.rpm

Uninstalling pyAlarm as an rpm is just a matter of first becoming the superuser, and then typing:

rpm -e pyAlarm

*****************************************************************
Running pyAlarm
*****************************************************************

Running pyAlarm is just a matter of typing pyAlarmRun.py from a terminal.  It should be
installed in your path, and if it's not, then I'm sorry.  ;)  Fix it and send me a patch, if
the problem is in pyAlarm.  If not, fix it anyway and don't send me a patch.

*****************************************************************
License
*****************************************************************

This program is provided to you under the terms and conditions of the GNU General Public License, v2.0.
This means you have rights and stuff, and the file called LICENSE will tell you everything you ever
wanted to know about copyleft and the GNU GPL.

