Release Name: gnaural-0.3.20060421

Notes:
==Gnaural 0.3.20060421 Files==

Gnaural-0.3.20060421-setup.exe 		Gnaural for Windows, installer (requires GTK+ 2.0 Runtime Library)
gnaural_0.3.20060421_linux_i386 	Unpackaged Gnaural executable for Linux i386
gnaural-0.3.20060421.tar.gz 		Gnaural source code
gnaural_0.3.20060421-1_i386.deb		Debian installation package


==About the Graph Editor==

Gnaural now has an elementary interface to edit/create 
Schedule files without the tedium of hand-editing text 
files. The actual interface is the graph on the lower 
half of the application; by clicking in this area, you 
can add, delete, move, and edit data points. The technique 
is simple; using the mouse:

 Left button: creates, selects, moves data points
 Right button: opens an editable dialog for the data point
 Middle button: deletes data points

Some random tips:
- double-left-clicking creates a new data point.
- click-and-dragging across data points selects them
- selected points can be moved en masse by dragging
  any selected point.
- Ctrl-C, Ctrl-X, and Shift-X can copy selected data points. 
  Ctrl-V will paste them.
- Delete (on your keyboard) will erase any selected data
  points. Shift-Delete will also delete the durations associated
  with the data points.

Importantly, changes made to the graph can only be saved and/or
used by Gnaural's binaural beat generator after you've selected 
"Apply" in the "Graph" menu, or used it's keyboard shorcut Ctrl-L. 

==About the Windows version, Gnaural-0.3.20060421-setup.exe==

Gnaural's Windows version (like Gaim and Gimp and many 
other cross-platform apps) requires  requires "GTK+ 
for Windows" installed. Download the installer from:

http://prdownloads.sourceforge.net/gimp-win/gimp-2.2.9-i586-setup.zip?download

If that link doesn't work, there is another set of GTK+ 
Windows installers here:
http://prdownloads.sourceforge.net/gaim/gtk-runtime-2.6.9-rev-a.exe?download

NOTE: This version of Gnaural has an installer which 
will search and find the GTK+ libraries (the previous 
one depended on the PATH variable, which the GTK+ 
installer no longer updates). It does this by searching 
the registry for entries that the current GTK+ installers 
create. Thus if you have any problems with the Gnaural 
installer, but have the GTK+ libraries installed, the 
problem would probably be solved by uninstalling your 
current GTK+ version, and downloading the latest.

==How To Compile Gnaural's Code (Linux executable)==

[Note: the following instructions assume you are working from Debian, and targetting a Linux
i386 executable. But they should be fairly easy to translate to any distro.]

First, be sure you have everything you need to compile gnaural. On a standard Debian system, the only 
extras you should need are the various autotools, portaudio, and the development libraries for GTK. 
To get (or to be sure  you already have) all you need, open a terminal window, "su" to root, then paste:

   apt-get install autoconf autotools-dev automake1.9 libgtk2.0-dev libportaudio0

NOTE: it has been discovered that you must remove any old versions of automake, especially
the automake1.4 that Debian unwittingly installs when you type "apt-get install automake". 
To remove it, type: 
   apt-get remove automake1.4
I used GNU automake 1.9.6 for these instructions, and a litte testing suggested that 
automake 1.7.9 and later all work fine.

If you made it successfully through those steps, you should be ready to compile the source code. First, log out of 
root (type "exit" at your terminal window). Next, "cd" to the directory where you've saved the downloaded 
the Gnaural sourcecode (gnaural-0.3.20060421.tar.gz), then paste the following block of commands:

     tar -xzf gnaural-0.3.20060421.tar.gz
     cd gnaural-0.3.20060421
     ./configure
     make
     src/gnaural


If all went well, the full GUI option of gnaural will have launched. If it did not, see Troubleshooting (below).

==Troubleshooting==

- If you had a compiling error, try again using these commands:

     tar -xzf gnaural-0.3.20060421.tar.gz
     cd gnaural-0.3.20060421
     ./autogen.sh
     make
     src/gnaural


- If it still didn't work, check the output from ./configure; it will often list something required to compile 
as the last item before it halted. Importantly, do you have all the required development libraries? See 
the steps at the top of this page to install them.

- If you can't hear any sound:
Make sure your sound system is configured properly

- If you can't see the GUI:
 Make sure you actually logged-out as root.


==Compiling Gnaural's source code on Debian to make a Win32 executable==

These instructions are experimental; this is quite a bit more involved than compiling a
native executable, requiring you to download Tor Lillqvist's Win32 GTK+ dev files, and also
the MinGW32 cross-compiler (easy on Debian/Ubuntu), and a few other things. But if all that is 
in-place, autoconf and automake get to do their magic, and you will automagically have a Win32
executable in your src file merely by pointing the variable "mingwdir" (in src/Makefile.am) to 
your batch of GTK+ libs then replacing the line in the above (regular compile) batch commands:
     ./autogen.sh
with
     ./autogen.sh  --host=i586-mingw32msvc --target=i586-mingw32msvc --build=`./config.guess`

Amazing. 

But getting it all set up is not so amazing, it is tedious, and took me about 3 weeks to finally
piece together. Mostly because of autoconf/automake, which are either unbelievably poorly documented
or an IQ test on which I have proven decidedly stupid. Hellish little angels, but worth the trouble
because they will do do all the work for you if I have set them up properly in configure.in and 
src/Makefile.am. Assuming I have, and that you have a recent automake (try "apt-get install automake1.9"),
and you have also amassed all the other ingredients I list below for compiling and (god-willing) 
testing, then these are the steps:

1) Remove evil automake1.4 if it has possessed your autotools:
  apt-get remove automake1.4

2) Get the usual compiling tools necessary for compiling gnaural:
  apt-get install autoconf autotools-dev automake1.9 libgtk2.0-dev libportaudio0

3) Get the special cross-compliling tools (in this case, Debian's MinGW32 package). As root, type:
  apt-get install mingw32 mingw32-binutils mingw32-runtime

4) Get Tor Lillqvist's GTK+ Win32 development libs -- download everything with "-dev" in the name from: 
  http://www.gimp.org/~tml/gimp/win32/downloads.html

5) If you want to test the executable, you should get WINE and the GTK+ Win32 runtime libs installed too.

Once you have all that, unzip all of Tor's GTK+ dev-libs in to a folder named "lib_gtkwin32" (arbitrary 
name -- simply what I use in the steps that follow). Now edit the file src/Makefile.am (in Gnaural's code
directory) to make the variable "mingwdir" point to lib_gtkwin32, something like this:
   mingwdir = ../../../../lib_gtkwin32

Now you are ready to compile.

NOTE: it is advised that you do a "make clean" at this point before proceeding. If there are remnants of a 
previous Linux build, they will pollute your cross-compiation in ways that can make the results look truly 
mysterious and even deeply depressing (until you remember that you forgot to "make clean").


1) In the project's root directory, paste the following:
    ./autogen.sh --host=i586-mingw32msvc --target=i586-mingw32msvc --build=`./config.guess`
NOTE: Optionally, you can do this (if it works for you):
    ./configure --host=i586-mingw32msvc --target=i586-mingw32msvc --build=`./config.guess`
2) If that went well, paste:
    make
3) If that went well, congratulations, you have succeeded. You might want to strip the executable 
(because it is huge, yet can be tiny):
    i586-mingw32msvc-strip src/gnaural.exe
4) Test the executable with this:
    wine src/gnaural.exe -d 
5) And finally, let me know how configure.in and src/Makefile.am could be even better :-) They feel 
uncomfortably like hacks; but I have tested them on standard Ubuntu and Debian distros, on which they 
work very well. I wish old automake1.4 could handle them, since that is the default automake Debian
installs for some unknown reason.





==Command Line Help==

Gnaural (ver. 0.3.20060421) - A programmable binaural beat
and pink noise generator. Outputs in stereo 44.1khz PCM WAV
format following directives in ~/.gnaural/gnaural_schedule.txt.
For more info see:
        http://gnaural.sourceforge.net/
===Command Line Options===
 -w [file.wav]  write output to a .WAV file
 -o             write output to stdout (for redirection)
 -p             play output through sound system
 -a [0 to 9]    specify sound card (optional)
 -s             create default file ~/.gnaural/gnaural_schedule.txt
 -i             show runtime info on screen (use with -p or -w)
 -d             output debug info
 -h             show this info
===Examples===
 Create a CD-compatible WAV file:
        gnaural -iw MyMeditation.wav
 Play directly through sound system:
        gnaural -pi
 Pipe Gnaural through LAME to create an MP3:
        gnaural -o | lame - MyMeditation.mp3


[NOTE: deb for version 0.3.20060421 still under development; no available yet]
==How To Install The deb (Debian specific)==

Open a terminal window, "su" to root, then issue this command:

 dpkg -i gnaural_0.3.20060421-1_i386.deb

If you get error messages about not meeting or exceeding lib version
requirements (an Ubuntu installation complained, for instance), you could
consider forcing the install:

 dpkg -i --force-all gnaural_0.3.20060421-1_i386.deb

In most case, I've found gnaural to work just fine. And if not, you can either
try to upgrade to the required libs, or remove gnaural with:

 dpkg -r gnaural
