Stylopalm -- a Stylophone emulator for Palm OS
Philip Boulain <lionsphil@zepler.net> http://www.zepler.net/~lionsphil/
=======================================================================

About
-----
You know those little keyboard things that you played by contacting an exposed
circuit board with a stylus, that Rolf Harris jumped upon in the '70s?
Stylophones. I had been wanting to turn my trusty Palm into a crude musical
instrument for a while, and found the H2G2 article about them from the Harris
connection. So there you are. It's a different kind of onscreen keyboard.

Requirements
------------
Palm OS 3.5 is required. The sound stuff will run on 3.0, but the interface
won't. It might be possible to hack around that if you're brave, but you'll need
to rewrite the extended gadget as a regular one, and remove the volume slider.

I've tested it successfully on the Palm emulator running OS 3.5, a real
Palm Vx running 3.5, a Palm m505 running 4.0, and the Palm simulator running
5.4. It only needs the lowest resolution and a monochrome display.

Installation / Usage / Removal 
------------------------------
To install Stylopalm, just drop the PRC file in palmOne Quick Install and
HotSync. To run it, tap "Stylophone" in the launcher -- it will fall into the
"Unfiled" category by default. Simply use the stylus on the keys to produce
notes, just as you would with the hardware version (see why I did this on a
PDA? :D ). The volume slider does the obvious, with the rightmost setting being
the loudest your Palm can manage, and the leftmost the quietest short of silent.
The vibrato option introduces horrible, downward-semitone wobbling as you move
the stylus. Faster movements give more vibrato, and holding still gives none;
I'm undecided as to whether this is a known bug, or an accidental feature. ;)

You can remove Stylopalm using the normal "Delete..." option from the launcher
menu.

Problems
--------
The only error Sylopalm should be able to encounter is severely low memory. If
this happens, a soft reset should clear the problem.

Other than that, ignoring me and trying to run it under Palm OS versions below
3.5 will cause it to error out and switch to some other application.

Known bugs
----------
There are no known serious bugs. It shouldn't leak memory, crash, or anything
like that.

If you hold a note for over a minute, it may cut out. I'm still trying to figure
out a nice way to detect/have PalmOS tell me when a regular, old-fashioned
speaker note has finished playing (this is also why just holding a note won't
cause vibrato---it needs movement to trigger it).

The vibrato is pretty horrific, but then apparently it was on the original
device. It's a simple, linear sawtooth oscillation between the played note and
one half-tone below it, which is not particularly musical (but /is/ fast to
calculate for a poor little embedded processor).

While not a bug, Stylopalm will probably drain your battery faster than most
applications, simply because you're using the speaker more, and probably holding
the stylus down for longer. Vibratio is particularly bad, as it keeps the CPU
fairly busy. When not playing, Stylopalm just idles as usual.

Compiling
---------
All the files in the archive which aren't the PRC are an Eclipse project,
for the incredibly nifty Palm OS Developer Suite. If you're using that,
you should be able to just build the Release target. If not, ignore the
autogenerated makefile and just compile the contents of src/ and rsc/
into a Palm program using gcc and prc-tools.

There are a few things you might want to poke if you're making a
custom install:
  Frequency debug mode
In AppMain.c, the macro FREQUENCY_DEBUG controls a debugging mode where the
application's title is changed to show the current note frequency in Hertz. This
is pretty neat, but does cause redraw issues at the moment.

  Change octave
The method NoteFrequency() in Keyarea.c converts an note into a frequency, using
the equal tempered scale (thanks to MichiganTech Uni's physics department for
some really nice online documentation on this!). You can either halve or double
the "freqbase" constant above it to shift the pitch down or up respectively,
although the little speakers in most Palms are pretty limited in what they can
produce. Really adventurous tinkerers may want to change the method completely
to change the entire scale in use: NoteHasSharp() and NoteAsText() in the same
file might also be interesting to you. This method also controls the vibrato
implementation if you feel like making it sound less awful. ;)

  Smaller binary
If you're compiling for just your handheld, modify rsc/AppResources.xrd
(possibly using the Palm OS Resource Editor in the Developer Suite) to
remove application icons not needed for your display mode.

If you make any fixes or improvements to the code, send them to me at
lionsphil@zepler.net! =)

Licence / legal
---------------
Stylopalm is Free Software, licensed under the GNU GPL. Here's the
standard boilerplate stuff for it:

 Stylopalm -- a Stylophone emulator for Palm OS
 Copyright (C) 2006 Philip Boulain

 This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
 the Free Software Foundation; either version 2 of the License, or
 (at your option) any later version.

 This program is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU General Public License for more details.

 You should have received a copy of the GNU General Public License
 along with this program; if not, write to the Free Software
 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA

Palm OS and HotSync are trademarks of PalmSource, Inc. or its affiliates.