EARPLUG
A "Live Connected" Audio Plugin for Linux
by Jonathan S. Kinnersley
jsk@amath.washington.edu
jskinnersley@hotmail.com
Version 1.0 - 1st March 1999
Features
This Plug-in allows up to 30 sound files
to be played
simultaneously from a web page, and to be controlled from Java or JavaScript
programs using many of the "Live-Audio" methods (and a few more).
The files can be any mixture of AU, AIFF, MIDI or WAV files.
It allows independent control of both stereo channels for some
interesting 2D effects. Here is a snap-shot of EarPlug.
There are volume controls for both stereo
channels and a display of the file being played. The state of the controls
can also be controlled from Java and JavaScript for added visual feedback
(for example, the "play" button will appear to be pressed when the plugin's
"play" method is called from Java or JavaScript).
|
Download and Installation
First
download the gzipped tar file,
earplug-1.0.tar.gz,
then expand it with the command
tar xvfz earplug-1.0.tar.gz
or
gunzip earplug-1.0.tar.gz
tar xvf earplug-1.0.tar
This will make a directory called 'EarPlug-1.0'.
To install the plugin so Netscape can use it,
first 'cd' into the directory called 'EarPlug-1.0'.
If you are the root user, typing
make install
will copy three files
( earPlug.so, EarPlug.class and FadeEarPlug.class )
into the directory
/usr/lib/netscape/plugins/
Alternatively, (if you are not the root user, or if you want EarPlug to be
local to your Netscape)
by changing 'INSTALL_DIR' in "Makefile" before typing 'make install' you
can install them in ~/.netscape/plugins/
You will need to re-start netscape and hopefully everything should work
perfectly! (Note that to play MIDI files you'll need timidity - see below).
You can test out EarPlug on my test files.
If you have problems, look here first.
(Note - If you are using RedHat Linux version 5.x or 6.0 the
binaries should work right away.
I don't know if the binaries will work with other versions of Linux - if
not, you'll need to re-compile the source code (see below) - sorry!).
Re-compiling the source
The source code is included in the gzipped tar file
EarPlug.gz
Download, unzip and untar as above.
You'll need the
Plugin SDK from Netscape, along with the
Java Developers Kit from Sun.
You'll need to change the definitions of 'SDK' and 'JDK' in Makefile
to point to your SDK and JDK directories, then just type 'make'
and it should re-compile the Java and native C code.
If it does compile and run properly I would appreciate a copy of the
binaries so I can include them here - thanks.
Timidity
In order to play midi files you'll need to have timidity installed - but
don't worry! - you have already downloaded it!.
Timidity converts MIDI files to WAV format files which can then be played
on almost any sound card.
Timidity was originally written by Tuukka Toivonen and though
his page
is now not being maintained by him it still contains useful links.
I have included a version of timidity (which should run on RedHat Linux 5.x and 6.0)
in the EarPlug.gz file you just downloaded. You can copy timidity into
'/usr/local/bin' (as well as a cut-down sample of patch files into
'/usr/local/lib/timidity/patch') by simply typing
cd timidity
and then
make install
Read the README file if you want to put the files somewhere else.
When EarPlug is presented with a MIDI file it calls Timidity which
converts the MIDI file to a WAV file, which EarPlug can then play and mix
with other sounds. Timidity may take a while to convert
a file, so you will notice a pause of a few seconds before EarPlug
plays the converted MIDI file. Timidity needs a set of "patch" files
which contain the wave shapes of all the instruments needed. This full set
of patch files takes up about 7 MB (though the selection I have included is
much shorter).
If the binary code I mentioned above doesn't work for you,
you can get a version of timidity from
Vincet Pagel's
timidity page, or search the web a bit.
If you want the full set of patch files (I really recommend getting them),
you need to put them in the directory '/usr/local/lib/timidity/patch'.
I got my patch files
from
Fredrick Hubinette's Plugger page (which, by the way, I
recommend if you want a general purpose plug-in to deal with lots of different
kinds of files).
Links to pages with cool sound files
Embedding an EarPlug in your web page
In addition to the brief write-up here, you might want to take a look
at the source of the page as an example of how to use EarPlug from JavaScript.
In order to play sounds on your web page you have to embed an EarPlug plugin
in it. You do this with the command
< EMBED
NAME="name" an optional name for the plugin
so that you can refer to it from
SRC="URL or file" (must have a suffix aif,aiff,mid,
midi,wav,au or snd)
TYPE="MIME type" (eg. audio/basic - if SRC is not
included you'll need this to get
an EarPlug plugin).
COLOR="color" (eg. red - default is lightblue)
AUTOSTART="{true or false}" (starts playing right after loading)
WIDTH="int" a number - 150 is good
HEIGHT="int" a number - 70 is good
DISABLED="{true or false}" if true, console can be enabled later
using the method "enable()"
HIDDEN="{true or false}" hides the plugin console
LOOP="{true or false or int}" infinite loop, single play, or a certain
number of loops.
>
For example,
< EMBED SRC="sound.wav" color="blue" width=150 height=70
autostart=false loop=true >
or
< EMBED src="http://www.noise.com/sounds/bang.au" autostart=true >
or
< EMBED type="audio/midi" width=120 height=70 >
Controlling an EarPlug from Java and JavaScript
EarPlug has a number of methods which can be called from JavaScript or
Java, but in both cases you first have to embed an EarPlug
plugin in your web page.
The methods are
| play(loop,url) | eg. play(true,"sound/boing.au") - loops endlessly
or play(false,"http://www.noise.com/tune.midi") - plays once
or play(3,"hey.wav") - plays 3 times.
|
| play(loop) | plays the sound file last loaded - 'loop' is as described above.
|
| stop() | stops the plugin playing.
|
| pause() | pauses the plugin
|
| setvol(vol) | where 'vol' is an integer from 0 to 100.
Sets both stereo channels to 'vol'
|
| setvol(leftvol,rightvol) | sets volumes for left and right
speakers, again from 0 to 100
|
| fade_to(vol) | fades left and right channels to 'vol'
over a time of 3 seconds
|
| fade_to(leftvol,rightvol) | fades left channel to 'leftvol' and
right channel to 'rightvol' over 3 seconds
|
| fade_to(leftvol,rightvol,time) | fades left channel to
'leftvol' and right channel to 'rightvol' over 'time' seconds
|
| disableConsole() | disables the console controls
|
| enableConsole() | enables the console controls
|
| stopAll() | stops all playing plugins
|
| pauseAll() | pauses all playing plugins
|
| playAll() | re-starts all plugins which have been paused
|
| IsPlaying() | returns true when plugin is playing
|
| IsPaused() | returns true when plugin has been paused
|
| IsStopped() | returns true when plugin has been stopped
|
| IsReady() | returns "true" when sound file has been uploaded
|
| GetVolume() | returns the average of left and right volumes
|
These methods are called by prefixing them with "document.embeds[n]."
where 'n' is the number of the plugin in the web page (starting with 0).
eg. document.embeds[0].play(3,"sound.wav") would play "sound.wav"
three times on the first plugin.
More detailed information on calling plugin methods from JavaScript and
Java can be found on Netscape's Client-side JavaScript Guide,
or you can take a look at the source for this page
(hold "shift" down and click to download).
Problems
If you are using RedHat, you'll need a bug-free version 4.06 or higher of
Netscape (the upgrades are available from
RedHat). The earlier versions had problems with Java.
I've had problems when trying to refer to a plugin from JavaScript
using its name (defined by the NAME attribute in the EMBED statement).
Everything worked when instead of 'document.earPlug.play(1,"file.wave")'
I used 'document.embeds[0].play(1,"file.wav")'
If EarPlug doesn't work, check that it is enabled for
all the MIME-types AIFF, AU, MIDI and WAV. Do this by
going to the "About Plugins"
page under the "Help" menu on Netscape.
If EarPlug is not enabled, go to the
Netscape Applications page by choosing
"Edit" - "Preferences" - "Navigator" - "Applications".
Then find the above MIME types and make sure the EarPlug plug-in is selected
for them. Note that audio/wav and audio/x-wav both refer to files with the
.wav suffix.
I also had problems because the ownership of
my ~/.netscape/cache/index.db file had been
inadvertently changed to 'root' - make sure that it is owned by
you, by using chmod.
Afterward
I wrote this plug-in mainly out of frustration! I wanted noisy
web pages to be available to Linux users - at first I thought Java
was the answer, but I soon found out that the Java applet method
"play" just didn't work!
Then when I read about the Netscape Live-Audio plug-in
I thought NOW I could produce noisy web pages.... until
I eventually realised it wasn't shipped with the Unix/Linux versions!
I would appreciate comments and bug reports - and if anyone makes binaries for
a Linux system which uses libc5 and not glibc, please let me know.
You can mail me
at
jsk@amath.washington.edu
or
jskinnersley@hotmail.com