Snack v2.0 - a sound toolkit for scripting languages

Kre Sjlander <kare@speech.kth.se>



Introduction
-------------------------------------------------------------------

Snack is a sound processing toolkit designed as an extension
to a scripting language. Snack currently works with the scripting
languages Tcl/Tk and Python.
Snack has commands to play, record, process, and visualize sound.
Snack supports in-memory sound objects, file based
audio, and streaming audio. It handles fileformats such as WAV, AU, AIFF,
and MP3.
The visualization canvas item types update in real-time and can output
postscript. The same scripts run on Unix (Linux, Solaris, HP-UX, IRIX,
FreeBSD, NetBSD), Macintosh, and Windows 95/98/NT/2000. It is also possible
to run scripts embedded in web pages through the use of the Tcl plug-in.
Several example scripts can be found in the demos directory.

For more information on Tcl/Tk and Python see
Tcl/Tk: http://dev.scriptics.com/
Python: http://www.python.org/

In order to use Snack you must have Tcl and Tk version 8.0 or later. Always 
use the latest stable release, currently 8.3.2, which can be downloaded from 
ftp://ftp.scriptics.com/pub/tcl/.

Tcl/Tk is often included with Python distributions. Snack has been tested
with Python 1.5.2 - 2.0 on Linux and Windows. See the Python
section below.

The Snack package has been tested on the following platforms:
Windows 95/98/NT/2000
Linux 2.0.35 (OSS 3.5) - 2.2.14 (OSS 3.8.2) (x86 and PowerPC)
SunOS 5.5.1 (Sparc and x86), Solaris 8 (Sparc)
HP-UX B.10.20
IRIX 6.2, 6.3 & 6.4 (even runs under SoftWindows, although slowly)
NetBSD-current/i386 using the OSS emulation library
BSD/OS-4.1
MacOS 8.6

Make sure you have the latest Snack version available at
http://www.speech.kth.se/snack/ before proceeding with the installation.



Compilation instructions for Snack on Unix
-------------------------------------------------------------------

You must have Tcl/Tk installed on your system. Both Tcl and Tk must have
been configured with the "--enable-shared" flag at build time (this is 
default for the 8.3 versions). Build them before Snack.

Unpack Snack and change directory to the snack2.0.7/unix directory.

Type "./configure".

If you get this error message "Can't find Tcl configuration definitions",
you have to specify their locations using the options "--with-tcl" and
"--with-tk" when running configure. For example, use 
"--with-tcl=/usr/lib --with-tk=/usr/lib" if Tcl/Tk was
installed in "/usr/lib", or "--with-tcl=../tcl8.2.1/unix" if you use that
version.

Type "make".

IMPORTANT: if you use Tcl/Tk 8.0 to 8.0.5 you will have to use the flag
--disable-stubs, when configuring Snack.

If the make fails you will have to edit the Makefile and possibly also the 
configure script. TCL_INCPATH should be the path to the directory which 
contains the Tcl header file (tcl.h). The same goes for TK_INCPATH (tk.h). 
XINCLUDES should be the path to the directory containing the X11 include
files.

Summary in case you download Tcl, Tk, and Snack and build from scratch:
You should place the distributions in the same directory and unpack them.
Build Snack using the following commands:
cd tcl8.3.1/unix
./configure --enable-shared
cd ../../tk8.3.1/unix
./configure --enable-shared
cd ../../snack2.0.7/unix
./configure
make

If you use Tcl/Tk 8.0 to 8.0.5 you change the last configure to
configure --disable-stubs



Testing
-------------------------------------------------------------------

When you have succesfully compiled Snack it's time to look at the demos.
In order to run these you will have to set the environment variable 
TCLLIBPATH to the directory containing the Snack library files (you don't 
need this step if you install Snack as described below). If you have 
compiled Snack in /u/kare/snack2.0.7/unix, this would be:

setenv TCLLIBPATH /u/kare/snack2.0.7/unix

Change to the demos/tcl/ directory and type ./widget.tcl:

cd ../demos/tcl/
./widget.tcl

this runs the Snack widget demonstration.

You should also try the Snack test suite. Type:

make test

in the build directory. You should then see a printout of the test files
processed. If any errors occur, you'll see a much more substantial printout
for each error. Please report any problems to the author.



System wide installation
-------------------------------------------------------------------

The recommended installation directory is the standard Tcl package directory. 
You can determine this by typing:

tclsh
puts $tcl_pkgPath

If you choose this directory you don't have to set the TCLLIBPATH variable.
Edit the Makefile if necessary. SNACK_INSTALL_PATH should be the path to the 
directory where you want to install the Snack package (e.g. /usr/local/lib).

Install using:

make install



Compilation instructions for Snack on Windows
-------------------------------------------------------------------

The workspace and project files necessary to build Snack on Windows are
in the win directory of the source distribution.

In order to use Snack you will have to install Tcl/Tk 8.3 first, don't forget
to tick the box to install include and library files.



Using Snack with Python
-------------------------------------------------------------------

Snack must currently be used in conjunction with Tkinter. You need to have a
matching installation of Snack and Tcl. For example, Python 1.5.2 uses
Tcl8.0.5 and Python 1.6-2.0 uses Tcl8.3. You can check this by typing the
following lines at the Python prompt:

import Tkinter
Tkinter.Tk().tk.eval('info tclversion')

Snack is accessed using the tkSnack module located in the python directory.
You need to put the file tkSnack.py in your Python path. 

Some demos can be found in demos/python/.

Documentation is found in doc/python-man.html



Using Snack with the Tcl Netscape plug-in 2.0
-------------------------------------------------------------------

You can optionally install Snack as an extension to the Tcl 
Netscape plug-in. First you should install the Tcl plug-in 2.0, which you 
can get from ftp://ftp.scriptics.com/pub/tcl/plugin/.

To use Snack as an extension you select this at configure time:

./configure --enable-plugin

When you install it using "make install", the appropriate files will be
copied to "/usr/local/lib/netscape/tclplug/2.0/".
If you have placed the Netscape plug-in somewhere else (e.g. locally in 
$HOME/.netscape/) use:

./configure --enable-plugin --with-mozilla=$SOMEWHERE

You can also simply copy the files yourself to get something similar to this:
/usr/local/lib/netscape/tclplug/2.0/snack2.0/unix/libsnack.sl
/usr/local/lib/netscape/tclplug/2.0/snack2.0/unix/libsound.sl
/usr/local/lib/netscape/tclplug/2.0/snack2.0/unix/pkgIndex.tcl
/usr/local/lib/netscape/tclplug/2.0/snack2.0/unix/snack.tcl

Currently you need to set this environment variable before starting Netscape:
setenv TCL_PLUGIN_WISH 1

In some cases this may also be necessary:
setenv NPX_PLUGIN_PATH $HOME/.netscape/plugins/



Using Snack with NIST/Sphere file formats
-------------------------------------------------------------------

It is possible to configure Snack to create an additional package for
handling the NIST/Sphere file formats. Use the configure option
--with-nist=DIR to specify the location of the NIST/Sphere distribution,
which can be downloaded at
ftp://jaguar.ncsl.nist.gov/pub/sphere_2.6a.tar.Z. In the Sphere
distribution you will have to modify the file src/scripts/install.sh and add
the compilation flag to create position independent code in some cases. Look
at the Snack Makefile for these.

On HP-UX with HP cc use: -Ae +z

See SphereFile.txt for more info.

Windows users can get a compiled dll at
http://www.speech.kth.se/~kare/libsnacksphere.dll.
Put it in ..Tcl\lib\Snack2.0 (together with libsnack.dll).



Dynamic linking problems
-------------------------------------------------------------------

(Sun, Linux, and SGI)
The loader must be able to find the "libsnack.so" shared object. You may
have to set the environment variable LD_LIBRARY_PATH to point the directory
where it is located. This variable is a colon separated list of paths which
can be modified using setenv. If you, for example, have compiled Snack in
the directory /u/kare/snack/unix and have the shared objects libtcl8.3.so
and libtk8.3.so in /usr/local/bin you would use the following command at the 
terminal prompt or in your .cshrc file:

setenv LD_LIBRARY_PATH /u/kare/snack/unix:/usr/local/bin:$LD_LIBRARY_PATH

(HP)
The corresponding environment variable on HP-UX systems is SHLIB_PATH and 
shared objects use ".sl" as file extension.


License
-------------------------------------------------------------------

Snack is currently licensed under GPL, see the file COPYING.
Contact the author if this kind of license is a problem.
The only reason for GPL is the MPEG decoding code, see jkFormatMP3.c.
If you remove that code it is possible to use a license similar to the one 
Tcl/Tk uses (BSD style) and to include Snack in any software on the same
terms.



Acknowledgements
-------------------------------------------------------------------
The following people have contributed code, suggestions, and/or other help.

Roger Lindell
Jonas Beskow
Claude Barras
Mel
Alexandre Ferrieux
Daryl Vertigan
David van Leeuwen
Stefan Karnebck
Simon Arnfield
Magnus Lundeberg
Zhibiao Wu
Qiru Zhou
Philippe Langlais
Dan Ellis
Holger Kanwischer
Egbert Ammicht
Richard Donselius
Seymour Shlien
Leonid Spektor
Frederic Bonnet
Andreas Gustafsson
Jeffrey Hobbs
Johan Dahl
Erhard Rank
Richard Ross-Langley
Uwe Koloska
Kevin Russell
Nicolas Garbe
Tom Wilkason
Jonas Ekeroot
Peter Kabal
