SnackAmp v3.0 - Feb, 2004

Tom Wilkason tom.wilkason@cox.net

Introduction

SnackAmp is a music player that works well in an environment where thousands of music files may used. You simply organize the files by your own scheme within folders and have SnackAmp play them. SnackAmp allows you to either save/retrieve traditional play lists of individual songs, or save/retrieve auto-play lists that specify folders that contain songs you want to play. SnackAmp provides powerful file organization and searching capabilities and ID3 tagging tools to help you manage your collection. An integrated web server allows remote control or playlist display. In addition, the web server will serve your media files to other clients (including SnackAmp) via http streaming.

Downloading SnackAmp

There are SnackAmp executables on the download page for Windows and Linux platforms which are the easiest way to get going The Windows version includes an installer/un-installer. The Linux version can be run as a separate file.

If you plan to modify SnackAmp you will need the sources. These are available in either zip or gz formats on the download page. SnackAmp is written in Tcl/Tk and uses the snack sound engine for playback. If you plan to use the Tcl/Tk script version, you will need both Tcl/Tk (either a full install or the TclKit versions) and snack for use. If you plan to play Ogg Vorbis files, download the Ogg/Vorbis library listed on the snack page. To save you some trouble, I have included the minimum snack libraries for Windows and Linux in the tar/zip bundles on the download page for you convenience. Note, the included Linux ogg library requires a prior installation of the final 1.0 libraries from Ogg/Vorbis. I recommend you go ahead and install these if your machine doesn't already have them.  These are used by any ogg file player on your machine.

In addition to the source and executables, StarKit files are available for Linux and Windows that can be used with TclKit. If you aren't familiar with this exciting technology, I suggest you check it out here. The Kits can easily be unwrapped  into source format, which you can freely modify, then wrapped back up into StarKits (or StarPacks).

Dag Wieers also maintains rpm's for SnackAmp at his site. You can check there for redhat 7.x/8.0 sources.

Below is a summary of the various version available for download

File (xx is current version) Description
snackAmp-xx-linux.kit Linux starkit, contains all required libraries. You will need the linux TclKit runtime engine to run.
snackAmp-xx-windows.kit Windows starkit, contains all required libraries. You will need the windows TclKit runtime engine to run
snackAmp-xx-i386.gz Linux stand alone executable file. No other files necessary. Unpacks into the file snackAmp.
snackAmp-xx-tar.gz SnackAmp source scripts and runtime libaries for linux. If using on a OSX or Unix, you will need your own snack engine. Tcl/Tk 8.3+ is also required which is most likely loaded on your machine.
snackAmp-xx.zip SnackAmp source scripts and runtime libaries for windows. Tcl/Tk 8.3+ is also required.
snackAmp-Install-xx.exe Installer file for windows to install the runtime files.

Executable Installation (recommended)

Linux

Download the snackAmp-x.i386.gz file and place it anywhere and un-compress it. Change the resulting snackAmp file to execute permission (chmod +x) and run it like any other program. The snack and snackogg libraries will be decompressed in the same library. These three files comprise the entire program.

Windows

Download the snackAmp-Install-x.exe file and run it. A standard installer will place it in the location of your choice and add a start menu shortcut. You can uninstall it like any other windows program.

Star Kit Installation

Windows

Download the StarKit version, snackAmp-x-windows.kit, and place it anywhere. Typically, starkit users tend to place their kits in the same folder, but it is not imperative. You will also need a TclKit run time which can be downloaded here. You should associate the .kit extension to this TclKit runtime allowing you to double-click any StarKit, including SnackAmp, to run it.

Linux

Download the StarKit version, snackAmp-x-linux.kit, and place it anywhere. Typically, starkit users tend to place their kits in the same folder, but it is not imperative. You will also need a TclKit run time which can be downloaded here, you should place the TclKit runtime somewhere in your path. After you download the kit, make it executable (chmod +x) and then you can run it like any other program, including creating a link to your desktop.

Script/Source Installation

Unix/Linux

Un-tar the snackAmp-x.tar.gz (.tar) files into the lib folder under your existing Tcl/Tk 8.3 or later installation (I highly recommend 8.4 due to speed enhancements). The files will be untared into a snackAmp folder. I try to make sure these files are in Unix format, but if not run dos2unix on them after untaring. Mark snackAmp.tcl as executable (chmod) and run it either from the desktop or command line. You may have to adjust the first line to adjust the version of wish invoked depending on your installed version of Tcl/Tk. Make sure Tcl/Tk 8.3 or later and snack 2.2 are installed first. Don't forget the snack ogg libraries if you want ogg vorbis support.

After uninstalling the sources, you can run the snackAmp.tcl main script file to run the program.

Windows

If you want to run the scripts under your installation of Tcl/Tk 8.3 or later, unzip the snackAmp-x.zip file unto the Tcl/Tk lib folder on your system. A snackAmp folder will be created to contain the files. Note you can install the files anywhere, it is however convention to install them under the Tcl/Tk lib folder. If the tcl file type is associated with wish, out can then click in the snackAmp.tcl file to launch it. The zip installation includes copies of the required snack files so which you can use instead of installing the snack distribution.

For any OS, you can also run the script version of snackAmp.tcl using Tclkit, which is very convenient.

First Time Use

Run the appropriate snackAmp file (based on how you install it). Initially you won’t have a default settings file, so you will be asked to set a Media Folder on the next window.  Please set this to the base folder containing your media. You can add additional folders later. After the tracks are quickly indexed, you will be asked if you want to catalog them. Cataloging reads the ID3 and other metadata from the tracks and puts it in a database. Cataloging is done on an as needed basis, so you can skip this step if you are in a hurry. 

If you don’t have a default Auto-playlist file (which you won't the very first time), you will be told one was created with all folders set to true, and asked if you would like to change them. You can answer either yes or no. The Auto-playlist can be changed later from the Auto-Play lists/Manage Auto-Play lists menu selection (or folder tree icon). The default Auto-Playlist is kept in a default.tafs file in your home directory. The selected auto-playlist file is retained between sessions.  You will also be given a chance to change other settings, which you can do later from the Settings menu if desired.

If you are using SnackAmp in a shared environment, you can copy any  .snackAmpDefaults file into the same directory as snackAmp.tcl or snackAmp executable and it will be used for the default settings for subsequent new users. This is useful in a shared environment to pre-set the media folders.

The wrapped version of SnackAmp will extract a default hotkeys file to your home folder and use it, the tar'd/zipped versions contain a copy which you must copy over manually to your home folder.

On subsequent startups you will not be prompted for anything. SnackAmp will launch using the previous Playlist and position (if the Restore Prior Playlist option is enabled), or a freshly sorted/shuffled list of songs that match the default Auto-Playlist file. 

Upgrading from a prior version

SnackAmp can coexist or replace a prior version with no problems. The settings and other files are all backward/forward compatible.

SnackAmp Use

See user manual

General Notes

There are a number of different of user settings you can save for SnackAmp. This are set via the Settings/Other Settings… menu. Each has a balloon help that provides instructions for use.

Startup

If you need to use non-default settings folders, read the next two paragraphs.

SnackAmp puts its configuration file in a subfolder called .snackAmp within your "home" folder. On *nix, this is your default folder when you log in. However, on some non *nix systems (e.g. Windows 9x) you may not have a home folder specified which defaults to your root directory where windows is installed (e.g. c:\). If you want to specify a different home folder for SnackAmp then you can create one somewhere and specify it by setting the SNACKAMPHOME environment variable to it or running SnackAmp with a commad line option -home folder, where folder is where you want to store the configuration files.

On Windows, SnackAmp will first check your HOME (env variable HOME) folder for an existing installation, if it does not find one, it then checks your USERPROFILE location and if available it sets this up as your home folder. If USERPROFILE is not available, it uses the root folder of the drive SnackAmp is installed on (e.g. very old WIN 95 systems). See comments above about overriding this.

Integrated Web Server

SnackAmp has an integrated Web server that server static pages, dhtml pages (via TCL macro files and urls mapped to SnackAmp Functions), dynamic playlists and streaming media. The SnackAmp home page is typically SnackAmp.vfs/docs which may be a real folder (if you are using the script version), or a virtual folder within SnackAmp itself. You can also add your own pages if you enter the name of your external folder root into the Settings->Web Server->Local Folder to map /local to setting.

Web Server Access and Protection

There are a number of ways you can restrict access to the build-in web server.

At this time login access in not supported, but may be in the future if there is demand for it.

The file search and processing order for SnackAmp is as follows:

No File Specified

index.tml (a TCL Macro File)
default.tml (a TCL Macro File)
default.html
index.html
default.htm
index.htm
built-in macro: If you have created a built-in macro. e.g. /streaming/browser. the macro will be processed passing any url parameters to it. The macro should produce pure dhtml (including a header) and return the entire text to the caller. A number of examples of these can be found in lib/urlRedirect

An HTML File Specified

If you specify an HTML file, SnackAmp will first check if a TML file exists with the same base name. If so, the TML file will be processed and written out to HTML file. The HTML file will be served. This allows you to write wrapper HTML files which include valid TCL macro calls. The TCL macro calls are processed and expanded dynamically to produce live content.

Extending the web server

You can place content into any local folder, map it to the /local url (via Settings), and when /local is called (e.g. http://locallost:8127/streaming/index.html), the files will be processed. You can also create TML files and place them in the folder. They will be processed via the methods described above.

Uninstalling

Installed File

If you are using the SnackAmp.exe installed file, just run the uninstaller to remove it. The Linux version can simply be deleted.

Script Version

Remove the snackAmp folder and its contents.

All Versions

All version of SnackAmp create and use the files below. You may remove these to completely uninstall SnackAmp.

Files Created and Used by SnackAmp

SnackAmp creates configuration and catalog files in your home directory within a .snackAmp folder under the folders discussed in the following table. This folder and the associated files are created automatically on first use of SnackAmp. All of the SnackAmp configuration, Playlist and Auto-playlist files will be stored here.

Operating System Location of .snackAmp folder
Unix/Linux Under your home directory, which is typically /usr/... or something similar. Entring cd ~/.snackAmp from a console will put in the SnackAmp folder.
WinNT/2K/XP The home folder is under your "Documents & Settings" personnel folder which is where windows stores your other profile related documents.
Win9x/WinME The env(HOME) folder setting within Tcl, which is typically the root folder of the volume windows in installed on

If you want to specify a different home folder for SnackAmp then you can create one somewhere and specify it by setting the SNACKAMPHOME environment variable to point to it, or running SnackAmp with a command line option -home folder, where folder is where you want to store the configuration files.

If you have any problems or suggestions please contact Tom Wilkason at tom.wilkason@cox.net.

Credits

To Do

You can always find the latest version at
http://sourceforge.net/projects/snackamp/