@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:
- Install pyMad and pyao using your distributions automatic dependency resolution system, be it emerge, urpmi, or apt-get.
- Install pyAudiere. A little trickier, but you can do it.
- 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:
- mp3 playback ONLY
- 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)
- 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.
- 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.