\input texinfo

@setfilename tracker.info
@set VERSION 5.3-OpenBSD edition
@settitle Tracker @value{VERSION} 
@c End of header
@set EMAIL Marc.Espie@@openbsd.org
@set POSTAL Marc Espie@*60 rue du 4 septembre@*87100 Limoges@*France

@dircategory Miscellaneous
@direntry
* Tracker: (tracker).		Amiga modules player.
@end direntry

@titlepage
@title Tracker @value{VERSION}
@subtitle Documentation rev. 1.0
@author Marc Espie

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1995 Marc Espie.
@end titlepage






@node    Top,        Introduction, Concept Index, (dir)

@ifinfo
This documentation describes tracker @value{VERSION}.

tracker is a shareware soundtracker player that works
on many different architectures.

It is now forbidden to redistribute tracker as a
stand-alone program. I'm fed up of getting incomplete bug-reports.
Be sure to at least include the documentation with your versions,
and full directions to get back to the source.

@strong{Thanks}

For @emph{any} bug-report, @emph{don't forget to include @strong{full}
version information} including
@itemize @bullet
@item
tracker source version.
@item
the architecture on which you've compiled it.
@item
any change from the standard distribution as available from @ref{aminet}.
@end itemize

As I am a lazy person, this file tends to change more slowly than the tracker
program itself.  Some options may no longer exist, some may have been added.
Many things may be different.  I mainly try to get out a working, efficient
reasonably bug-free program.  If I manage to write corresponding docs, fine!
If I don't, tough luck! Anyhow, looking at the source file should provide
you with enough insight for everything.

Copyright @copyright{} 1995 Marc Espie.

@end ifinfo
@menu
* Introduction::
* Availability::
* Registration::
* Reporting bugs::
* Credits::
* History::
* Installation::
* Porting tracker::
* Usage::
* Technical Information::
* Concept Index::
@end menu







@node    Introduction, Availability, Top, Top
@cindex Soundtracker
@cindex Protracker
@cindex Tracker, what is it
@cindex Module definition
@cindex History of Protracker
@cindex MED
@chapter Introduction
``Soundtracker'' is a family of music composition programs
that exist on the Amiga. The resulting data files (modules)
have been appearing on ftp sites for some time now.

For a machine with sufficient horsepower and some audio capability,
it is possible to emulate the @ref{Amiga audio hardware} in real time,
and play those modules. How close to an actual Amiga the resulting rendition
will sound depends only upon your machine's CPU and audio abilities.

The Soundtracker format originated on the Amiga about
ten years ago, with the original sound tracker, written by Karsten Obarsky.
There have been numerous variants built upon it, including the many versions
of Protracker (@pxref{The Protracker format}).

A Soundtracker module is a binary format that mixes audio samples with 
sequencing orders, making it possible to play rather long pieces of digital
music with reasonably good quality. 

Tracker is a portable player for these modules.
Its main features are
@itemize @bullet
@item
faithful rendition of all Protracker tunes. @footnote{Well almost all.
Since there are several distinct protracker in existence, it is difficult
to be compatible with all. I estimate that more than 99% of modules are output
correctly}
@item 
portability. All the code is written in C.
@item
support of efficient compression methods.
@end itemize

@ref{The Protracker format}
is historically limited by the Amiga audio hardware, namely
@itemize @bullet
@item
no more than four tracks.
@item
somewhat poor sample rendition.
@end itemize

There have been some attempts to override these limitations, and some 
offsprings of Soundtracker on other platforms that support 6 or 8 channels
modules. Tracker tries its best to support these variant formats.

Liam Corner (@pxref{Credits}) had the original idea of writing a Soundtracker
player for the Sunstation. His program, though imperfect, proved it was 
possible @footnote{This is the original @code{str15}/@code{str31} that might
still be available on some sites, even though it is hopelessly outdated.}.
I wouldn't have thought of writing it myself, but armed with his original code, 
I used my knowledge of the Amiga tracker format to `add some improvements'. 
Of course, I ended up rewriting the whole code. At that point, it ran on 
Silicon Graphics Indigos and Suns.

After that point, lots of people (@pxref{Credits}) found that tracker
was reasonably easy to port to their machines though quite buggy still.
These days, some two years later, tracker looks as if it works 
on many more machines, though that may simply be a deceptive illusion.

If you want to modify tracker or make it run on another machine, or correct
problems, please do so. Just try to keep in touch with me (@value{EMAIL}).

There are more architectures supported all the time. Check the @file{Makefile}
for this version or see @ref{Installation}.  
Your machine should be able to produce sounds, that goes without saying. 
You also need tunes to play (module files). 
Some are available on @code{nic.funet.fi} or check @ref{aminet}, 
for instance.

@emph{Most} Soundtracker/Noiseplayer/Protracker modules should play out ok. 
Due to various disagreements between all the Soundtracker versions (never forget
Soundtracker is a horrible hack, a big kludge), 
it is a @emph{real} nightmare to
try and make some commands work. What you have is my best effort at trying
to outguess every Soundtracker composer in existence@dots{} Obviously, I haven't
completely succeeded. 

@sc{med}, @sc{s3m}, or @sc{xm} support I've thought of, 
but don't forget, to make tracker work, 
I need to reverse-engineer assembly routines coded like spaghetti, 
and transform it into more or less human-readable, normal C code.
So up till now, I haven't had time enough to support these. Teijo's
code is not exactly limpid, @code{MEDplayer} itself tends to change from 
release to release, but maybe one day@dots{}

Actually, if you know other player programs, you will notice that tracker is
better at the compatibility game than most of them.





@node    Availability, Registration, Introduction, Top
@cindex Where to obtain tracker
@cindex Tracker latest version
@cindex Contacting the author
@chapter Various pointers
@section Where to obtain tracker
@ifinfo
@subsection The status of tracker
Tracker is @emph{Shareware}. If you use it much and feel like it, please send
me some money, or software you've written for the Amiga. This is just
a moral obligation, something between you and your conscience. Some
amount like $20 or FF 100 would be fine. (Note that you can still use tracker
without paying anything). 
My postal address:
@display
@value{POSTAL}
@end display
For commercial purposes, please negotiate with me.
@emph{As of today, I haven't received any contribution@dots{} I feel like
I'm lacking some incentive to go on!}
@end ifinfo
@subsection The most recent version
In case of trouble, please try to obtain the latest version. This documentation
describes tracker @value{VERSION}.

It is available through anonymous ftp to @ref{aminet} in
the @file{misc/unix} subdirectory or other sources. 
Some binaries may be available as well as the source code.
All recent releases of tracker do display a version number if started up without
other arguments.

@subsection My Address
You can also contact me at the following e-mail address:
@display
@value{EMAIL}
@end display
Please try to refrain from contacting me for trivial purposes, especially
questions for which this documentation already contains an answer. 
Encouragements are always welcome, though I would prefer some real money.
@xref{Reporting bugs}.

@subsection Related utilities.
Along with tracker, you might also need:
@itemize @bullet
@item
some modules
@item
@code{zoo} and @code{lha} for your machine.
@item
the @code{shorten} utility.
@item
the @code{ppunpack} program, distributed with the tracker archive.
@c If you're reading the html version you might not have the archive yet.
@c It might be a good idea to include a hyperlink to the latest release
@c with the html version. The latest texinfo releases support that.
@end itemize






@node Registration, Reporting bugs, Availability, Top
@cindex How to register tracker
@cindex Shareware concept
@section Registration
Tracker is @emph{Shareware}, but it is not crippled in any way.
What you get is the full working version, except if somebody
else tampered with the distribution.

Tracker registration is just a moral obligation. You can support what
I've done in several ways:
@itemize @minus
@item
By sending me some money.
@item
By giving me your software (registered copies of Amiga programs).
@item
By porting it to other architectures.
@item 
By @ref{Reporting bugs}.
@end itemize

It is up to you to decide what to contribute. I would like to get more
money, but I won't force you. Some amount around $20 or FF 100 would be
a fine price.
My postal address:
@display
@value{POSTAL}
@end display
For commercial purposes, please negotiate with me.

Even if you don't register because you don't have any money, don't hesitate
to send me praise, postcards, encouragements, bug-reports.

If  you  have some money, and use tracker a lot, please consider sending me
some money.   I've sunk hundreds of hours into tracker.  This is mostly a
passion for me, but it would provide me some incentive to go on.

As tracker is somewhat of a collective project, I would also like to clear some 
things up: I feel that I've spent much more time developing tracker than anybody
else these days. I consider that all the people that have helped me along the 
line (@pxref{Credits}) have registered by their work. If I ever get some significant
amount of money thanks to tracker, they will get their share. This doesn't seem
likely for the moment.









@node Reporting bugs, Credits, Registration, Top
@cindex In case of bugs
@section Reporting bugs
Before you report bugs, try to obtain as recent a version of tracker as possible.

For @emph{any} bug-report, @emph{don't forget to include @strong{full}
version information} including
@itemize @bullet
@item
tracker source version.
@item
the architecture on which you've compiled it.
@item
any change from the standard distribution as available from @ref{aminet}.
@end itemize

In case the problem occured with a specific module, give me full directions to
retrieve the module through ftp, or ask me what you can do, if it is not available
through ftp (I don't like to get binary files in my e-mail without forenotice).

I would prefer not to get bug-reports from outdated versions, or from betas not coming
from official beta testers@dots{}








@node    History, Installation, Credits, Top
@cindex History
@chapter History
Unless you are one of tracker's beta-testers, you should only
have one of the official releases. In case of trouble, 
@strong{please verify you have the latest version before contacting me.}
@subheading Release 4.44 @i{(official release)}
I've finally decided to release 4.44 as an official release, since it
appears to be quite stable, and I'm currently changing a lot for 5.0.
Problems to note:
@itemize @bullet
@item
The OS/2 version seems to crash from time to time, and Bruno has been unable
to track the problem down.
@item
AIX internals seem to have changed quite a bit recently. There will be a
patch available as soon as the problem is fixed.
@end itemize
@subsubheading Release 4.44 @i{(beta)}
@itemize @bullet
@item
Full documentation included in the package.
@end itemize
@subsubheading Release 4.43 @i{(beta)}
@itemize @bullet
@item
works on the Amiga again thanks to slight changes. Merging the Amiga files
into the main distribution slowly@dots{}.
@item
Mixed up @ref{Fine portamento up} and @ref{Fine portamento down}, thanks
Emil (@pxref{Credits}).
@end itemize

@subsubheading Release 4.42 @i{(beta)}
@itemize @bullet
@item
slight bugs in file reading@dots{}.
@item
put back @code{transpose} option where it belonged.
@item
experimented with audio dithering for 8 bit output. Removed it,
does not seem to give better sound quality.
@item 
option parsing code in order. All old options put
back in.
@item 
bugs with color handling fixed.
@item
Amiga version considered temporarily broken due to extensive changes.
@item
The list option is currently broken.
@end itemize

@subsubheading Release 4.41 @i{(beta)}
@itemize @bullet
@item
corrected long-standing bug in effect 5.
@item
fixed stupid bug in older-style tempo.
@item
should compile correctly under solaris.
@item
new-style options.
@end itemize

@subsubheading Release 4.40 @i{(beta)}
@itemize @bullet
@item
the player is now more sensible.
@item
added @kbd{m}/@kbd{M} runtime switch (mono/stereo).
@item
fixed up minor amiga problems.
@item
fixed up the audio recognition loop in the Sparc engine.
@item
removed transpose feature as it will be simpler to do it by
changing sampling frequency and tempo.
@item
in case of an older soundtracker module with 15 samples, always use
old-style set tempo command.
@end itemize
@subheading Release 4.39 @i{(beta)}
@itemize @bullet
@item
fixed up data sizes mostly everywhere.
@item
added prototypes to @file{Arch/Sparc/config.h}, 
and @code{#define IOCTL_IS_REDUNDANT} to remove gcc warnings.
@item
made porting much easier.
@end itemize

@subsubheading Release 4.38 @i{(beta)}
@itemize @bullet
@item
checked memory handling thanks to @file{mung.c}. Various small memory bugs
fixed.
@item
fixed bug in @code{run_in_fg}. 
It did sometimes reply that tracker was run in bg even though this was false.
@item
changed semantics of @code{sync_audio}: we need a second function to be able
to free data in @code{remove_pending_tags}.

@end itemize
@subsubheading Release 4.37 @i{(beta)}
@itemize @bullet
@item
fixed bug with tremolo.
@item
total duration working correctly. 
Showing up in the title bar for xterms.
@end itemize
@subsubheading Release 4.36 @i{(beta)}
@itemize @bullet
@item 
the virtual player now computes the total song length.
@item
small bug-fixes.
@item
documentation rewritten using TeXinfo.
@end itemize
@subsubheading Release 4.35 @i{(beta)}
@itemize @bullet
@item
start of virtual player: try computing the total song length@dots{} Not fully
implemented yet.
@item
some more cleanup as far as note handling is concerned.
@item
pulled @code{randomizer} inside of main code@dots{} now randomize correctly across
directories. Better @code{play_list} handling
@end itemize

@subsubheading Release 4.34 @i{(beta)}
@itemize @bullet
@item
loads of compression in the song reading. sample numbers get remapped
and we get rid of most redundant stuff.
@item
better memory allocation: does not store pitch any longer. Allocates
all patterns as one big chunk (shouldn't be a problem since it's less
than 128K anyway).
@item
specific setup for virtual player (soon to be implemented)
@end itemize

@subsubheading Release 4.33 @i{(beta)}
@itemize @bullet
@item
separated @code{SPECIAL_NOTE} (no known pitch) from @code{NO_NOTE}.
@item
better disk/memory throughput: use @code{read_file} where applicable.
@item
does not interpret unused patterns. Does not even read them, in fact.
@item
better event reading scheme: read the whole pattern, then interpret
each track independently. First step to the virtual player.
@end itemize

@subsubheading Release 4.32 @i{(beta)}
@itemize @bullet
@item
documentation update.
@item
player clean up.
@item
Sparc sound engine @emph{more} powerful.
@end itemize

@subheading Release 4.31
@itemize @bullet
@item
OS/2 version updated.
@item
HP versions updated.
@item
SGI minor bug fix.
@end itemize

@subsubheading Release 4.30 @i{(beta)}
@itemize @bullet
@item
better interface for the Sparc, post-synchronized display,
plus resample change on the fly. Maybe make it automatic ?
@end itemize

@subheading Release 4.29 @i{(beta, official Amiga)}
@itemize @bullet
@item
runs on the Amiga again.
@item
fixed up @emph{all} remaining Protracker problems. All Protracker effects
are now functional!
@item
minor bugs fixed. Nothing serious under Unix, used to crash under AmigaOs.
@end itemize

@subsubheading Release 4.28 @i{(beta)}
@itemize @bullet
@item
partial port to mm1
@item
renamed @file{getopt.h} to @file{getoption.h}
@end itemize

@subsubheading Release 4.27 @i{(beta)}
@itemize @bullet
@item
minor bug fixes in @file{Arch/common.c}. should work correctly on NextStep now.
@item
xterm stuff cleaned up.
@item
@code{ppunpack} is now @emph{officially} part of tracker. Nico Francois
(@pxref{Credits}) @emph{has} given his benediction.
@strong{You may redistribute @code{ppunpack} as you wish.}
@end itemize

@subsubheading Release 4.26 @i{(beta)}
@itemize @bullet
@item
title in window title bar for @code{xterms}.
@item
version number cleaned up, now shows up in exactly @emph{one} place (@file{Makefile})
@end itemize

@subsubheading Release 4.25 @i{(beta)}
@itemize @bullet
@item
added remaining Protracker 1.1 effect: @ref{Invert loop} (extended 15).
@item
fixed up (mostly) @ref{Loop pattern} (extended 6).
@end itemize

@subsubheading Release 4.24 @i{(beta)}
@itemize @bullet
@item
network audio (@pxref{NAS}) port@dots{} probably not working yet.
@end itemize

@subsubheading Release 4.22 @i{(beta)}
@itemize @bullet
@item
implemented vibrato/tremolo control. @xref{Set vibrato waveform}, 
@xref{Set tremolo waveform}.
@end itemize

@subsubheading Release 4.20 @i{(beta)}
@itemize @bullet
@item
notion of data width introduced, fixed some problems (more or less).
@item
corrected minor bug in @file{Arch/Sparc/audio.c}: used to modify the volume
at exit.
@item
some minor changes in commands according to the actual Protracker code. 
@end itemize

@subsubheading Release 4.19 @i{(beta)}
@itemize @bullet
@item
more sensible scrolling display.
@item
tremolo (@pxref{Tremolo}) finally working.
@item
Rolf Grossmann's patch (@pxref{Credits}): cleaned up user interface, with less @code{#defines}.
@end itemize

@subsubheading Release 4.18 @i{(beta)}
@itemize @bullet
@item
New Sparc features: @samp{-sync} support, waiting at start for buffer 
to fill for unhashed audio output.
@item
lots of minor bugs everywhere fixed.
@item
@strong{WARNING:} @code{oversample=0} (linear resampling) is probably broken right now
@end itemize

@subsubheading Release 4.17 @i{(beta)}
@itemize @bullet
@item
cleaned up architectural stuff. Even faster.
@end itemize

@subsubheading Release 4.16 @i{(beta)}
@itemize @bullet
@item
much better optimization in @file{resample.c}.
@item
optimization of the various @file{audio.c} files.
@end itemize

@subsubheading Release 4.15 @i{(beta)}
@itemize @bullet
@item
added missing @ref{Tremolo} effect@dots{} 
@file{guitarslinger} now sounds correctly (I hope).
@item
fixed up @ref{Set finetune}@dots{} was not updated instantly enough.
@end itemize

@subsubheading Release 4.14 @i{(internal)}
@itemize @bullet
@item
PowerPacker depacker.
@end itemize

@subheading Release 4.13 @i{(full release)}
@itemize @bullet
@item
cleaned up small bugs as compared to 4.11.
@item
much better technical documentation.
@item
upgraded Amiga version to 4.13.
@end itemize

@subsubheading Release 4.11 @i{(internal release)}
@itemize @bullet
@item
implemented color @sc{ansi} support.
@item
NextStep status: working with minor patch.
@item
linux status: working.
@end itemize

@subsubheading Release 4.8
@itemize @bullet
@item
@emph{Note for programmers:} @code{output_samples} size @emph{has} changed 
to 23 bits, to allow for 16 bit samples, oversampling, 
volume, and so on@dots{}
@item
reorganized machine dependent code to @file{Arch/}.
@item
cleaned up @file{Makefile}.
@item
implemented buffered files (finally). Faster loading of some modules.
@item
clutter of includes moved to @file{defs.h}.
@end itemize

@subsubheading Release 4.7 @i{(internal release)}
@itemize @bullet
@item
small bugfixes.
@item
compiling now on other architectures: NeXT, OS9. @xref{Architecture dependent 
problems}, @xref{Credits}.
@end itemize

@subheading Release 4.3
@itemize @bullet
@item
full Amiga support. Good playing model.
@item
rewrote @file{Makefile}.
@item
minor options changes.
@item
much easier to tinker with than the previous versions. Hooks for future
upgrades everywhere.
@item
tracker 3.xx is no longer supported. I won't answer to bug reports 
concerning it except to redirect you to the newer version.
@end itemize

@subheading Release 3.19
@itemize @bullet
@item
Amiga support! Finally.
@item
Solaris 2.2 support.
@end itemize

@subheading Release 3.11
@itemize @bullet
@item
general bug-fixes, plays some modules it goofed on (speed check, extended
command @ref{Loop pattern} now works).
@item
repeat working better.
@item
should be rather difficult to get cores out of it.
@item
may fork when loading a new module, though not working satisfactorily yet.
@item
almost readable scrolling display.
@item
support for DECstations (thanks to Andrew Leahy, @pxref{Credits}) .
@item
support for hpux (thanks to Bjoern Stabell, @pxref{Credits}).
@item
partial support for solaris.
@end itemize

@subsubheading Release 3.10 @i{(internal release)}
@itemize @bullet
@item
linux: small bug-fix, 16 bit support.
@item
general: bug in finetune fixed.
@end itemize

@subsubheading Release 3.9 @i{(internal release)}
@itemize @bullet
@item
background/foreground csh-aware mode, much cleaner termio.
@end itemize

@subsubheading Release 3.7 @i{(internal release)}
@itemize @bullet
@item
support for linux (thanks to Hannu Savolainen, @pxref{Credits}).
@item
small bug fix in @file{termio}: restore to a sane tty on exit.
@end itemize

@subsubheading Release 3.6 @i{(internal release)}
@itemize @bullet
@item
more efficient replay routine, works faster, all glitches finally removed
(I hope).
@item
more options, better integrated.
@item
much cleaner source code.
@end itemize

@subsubheading Release 3.0 @i{(internal release)}
@itemize @bullet
@item
tracker knows about  the Sparcstation 10.
@item
bug fix for command 5 (@pxref{Tone portamento + Volume  slide}), 
that now works like portamento (@pxref{Tone portamento}). 
Mostly affects @file{apocalypse} module.
@item
support for most protracker extended commands, including finetune.
@item
dynamic adjustements to the output frequency, fast skip, much better
user-response overall.
@item
better runtime interface (without those strange signals sequences).
@item
better screen output.
@item
audio flush on the Sparc, don't have to wait 10sec+ to exit.
@end itemize






@node    Installation, Configure tracker, History, Top
@chapter Installing tracker

@menu 
* Configure tracker::                  to know what you can change
* Generic problems::                   check these things first
* Architecture dependent problems::    if it doesn't work
* Porting tracker::
* Performance issues::                 to finetune tracker
@end menu

@node Configure tracker, Generic problems, Installation, Installation
@section Configuring tracker for your machine.

In order to compile tracker, you have to edit the
@file{Makefile} and change several entries:

@table @asis
@item @var{MACHINE}
your type of machine or precise port.

@item @var{PREFIX}
where installed files will go.

@item @var{CC}
C compiler to use.

@item @var{COMPRESSION_FILE}
the default `compression known database' file.
@end table

then type 
@example
make
@end example

@samp{make install}
usually doesn't work, but tracker is quite easy to install by hand anyway.
If everything didn't work ok, check the @ref{Generic problems} section.

The only important part is to get @var{MACHINE} and @var{CC} right. Since
Unix installations tend to vary, you may have to delve further into the 
Makefile and modify compiler switches.

@node Generic problems, Architecture dependent problems, Configure tracker, Installation

@heading Program organization

Most files are system independent, with some exceptions.

@table @asis
@item The @file{Arch} directory.
holds a @file{config.h} and an @file{audio.c} file for every configuration tracker has been 
compiled on.
@file{config.h} specifies various things about the machine. 
@file{audio.c} is the audio driver itself.

@item @file{Arch/Unix/ui.c} and @file{Arch/OS2/ui.c}
provide some `user interface' under Unix or OS/2. 
Mainly deals with raw mode and stuff like that, plus color xterms recently.

@item The @file{Arch/Amiga} directory
the Amiga version of tracker holds more system specific code than the other
versions. Namely, the audio drivers hooks in at the Amiga audio driver level
(bypasses @file{resample.c} completely, @xref{Amiga audio hardware}, 
@xref{Resampling details}, @xref{Amiga implementation}, for details).
@end table

If you need to understand how tracker works, a good place to start with is
@file{extern.h}, which holds commented prototypes for most functions.
Also, @xref{Resampling details}.

@section Generic problems

@table @asis
@item My computer barfs on the @file{Makefile}
your @samp{make} probably doesn't understand nested macros, 
like @code{CFLAGS = $(CFLAGS_$@{MACHINE@})}
@table @asis
@item Quick fix
edit the @file{Makefile} and replace @code{CFLAGS} and others with their 
definition, i.e., for a Silicon Graphics machine: @code{CFLAGS_sgi = -O2}
@item Real fix
install a real @samp{make}, like @file{gnumake}.
@end table

@item What's @code{stricmp} ?
that's `@code{strcmp} without caring about cases'. On some machines, there is 
a function called @code{strcasecmp} instead. 
A @code{#define strcasecmp} in your machine's 
@file{config.h} will be enough.
If you really don't find it, it's easy to roll your own, or even replace it
with @code{strcmp} at low cost.

@item tracker does not recognize any module
maybe the decompression isn't working correctly. First try out tracker with
uncompressed modules. Be aware that tracker doesn't support XPK modules, 
and has only external support for PowerPacker. To achieve support for lha
and other standard compressed formats, there is a good chance you'll have
to edit the @code{COMPRESSION_FILE} and install some utilities.
Also, don't forget that tracker supports only Soundtracker/Protracker modules
for the time being.
@item I don't get any sound.
Don't forget to check that your machine is audio capable. Do you have a
sound card ? Do you manage to get sound out of other programs ? Is your
loudspeaker hooked in ? Does your machine output sound through headphones
by default ? Is the audio package installed@dots{} Sounds stupid, but this is
the most probable problem.
Try to keep a key depressed: if you get some hashed sound output, the user
interface is broken. You'll have to check how to put your tty in cbreak mode.
Check the @code{HAS_TERMIOS} and @code{HAS_SGTTY} entries.

@end table

If tracker doesn't compile more or less cleanly, check that it pulled the
right @file{config.h} file, and check the definitions in that file.

If you manage to get sound output from tracker, but if the result is garbled
you probably need to check @ref{Performance issues}.
@node Performance issues, Usage, Porting tracker, Installation

@section Sound output problems
@emph{Warning: most of these problems can only be fixed by changing the code
of tracker@dots{} non-programmers, beware!}
You might wish to get a look at @ref{Resampling details} at this point.

@table @asis
@item The output is hashed
your machine is not fast enough for the quality you ask. Experiment with
optimizer flags. Try another compiler (gcc gives faster code on the sparc
in this case). Downgrade the output frequency with -freq. Don't use 
scrolling display. Use -mono, especially when you have only one loudspeaker
anyway :-)

@item The output sounds like white noise
Maybe you are trying to output 16 bit samples when your hardware supports
8 bits. Or you have overflows all the time. Or you are outputting unsigned
data when your hardware expects signed data.
You'll probably have to hack your own audio driver.

@item There are bursts of static through normally audible output
Overflow. Your sound engine outputs, for instance, 9 bit data when your
hardware expects 8 bits.

@item The output is strangely distorted
Most probably, you are doing 16 bit linear to ulaw conversion, which 
coincidentally outputs 8 bit data which doesn't sound @emph{that} garbled if
your hardware expects 8 bit linear. 
Modify your sound engine to output 8 bit linear.

@item The output is still distorted and I'm using ulaw
ulaw isn't that great a format for music output. Try to coerce your hardware
to output linear data. If you can't, try oversample. Might sound a little
better. Sorry about that.

@end table

@section Specific modules problems
@table @asis

@item Tracker doesn't recognize some modules
Remember that tracker won't handle compressed modules unless carefully
installed, and that you have to use @code{ppunpack} to depack PowerPacked
modules. Also, tracker doesn't yet know how to play MED, S3M, or xm modules.

@item Tracker barfs on some modules
Try @samp{-tolerant}. If it still doesn't work, send a bug report.

@item The module doesn't sound like it should
Check that carefully. Make sure you were using the right player on an Amiga. 
Double check with several players if possible. If you
still have something weird, you may have a bug. Try e-mailing me.

The only thing I can't implement is the on/off switching of the low-pass
filter for obvious reasons.

@end table


@node Architecture dependent problems, Aix, Generic problems, Installation


@section Specific architectures problems
@menu
* Aix::
* Amiga::
* DECstation::
* HP/UX::
* Linux/FreeBSD::
* MM1/OS9::
* NAS::
* NextStep::
* OS/2::
* Silicon Graphics::
* Sparc::

* Other Architectures: Porting tracker.
@end menu

@node Aix, Amiga, Architecture dependent problems, Architecture dependent problems
@subsection Aix

The Aix port is slightly outdated and won't run with most recent versions of
Aix. There is nothing I can do about it until somebody sends me an up-to-date
version as I don't have access to Aix machines.

@node Amiga, DECstation, Aix, Architecture dependent problems
@subsection Amiga

There is currently one Amiga version running under AmigaDos. 
An adaptation of the @ref{Linux/FreeBSD} version
to run under Amiga Linux or Amiga netbsd would probably be reasonably simple, 
the most difficult part being to get a working audio device.

The status of the current version is experimental. I most often work on
a Sparc in my school, and can't check on my Amiga except during vacations.

Version 4.36 compiles cleanly with SAS/C and smake. It probably doesn't
compete with HippoPlayer or Delitracker. Its only advantages are in terms
of compatibility. I've taken steps to be dead sure that tracker uses the
system and only the system, isn't a CPU-hog and works with terminal 
programs (and any weird hardware that hooks on the @sc{CIA}s for that matter).
Also, tracker probably will still run with new Amigas with PA-Riscs or 
something, since all the code is in C.

You will need to install KingCon on your machine. It is also a good idea
to replace the standard queue-handler with the one bundled with HWRCS
unless you don't intend to use compressed modules.

See the Amiga version as an unobtrusive module player without bells and
whistles, a quick way for me to check that everything sounds as it should.

There might still be memory bugs lurking, so if tracker crashes, get a more
reliable module player, or hack the source. 

Some known problems
@table @asis
@item The user interface doesn't seem responsive at the end of modules
Due to the asynchronous nature of tracker implementation.
Computations for the current song are actually finished. The interface is
locked waiting for the song to end in order to be able to release the
memory used for sound samples. 
I will need to add much smarter code to handle that: the player sits at a
point where it has the last song loaded, is ready to unload it and load the
next one. Just loading the next one before unloading the current one is not
a good idea, since it consumes too much memory.

@item The scroll window doesn't open when I ask for it
Performance reasons and  implementation hack. Scrolling information is only
computed when you ask for the scroll window, and the scroll window opens
magically when some scrolling information is ready.  Since the sound 
is buffered, you first have to listen to all the buffered sound 
before the scroll window appears.

@item I have 1.3 and tracker doesn't run
Upgrade@dots{}

@item I'm confused about the menu speed items
Their state doesn't accurately reflect what's going on, but 
@sc{PAL} and @sc{NTSC}
work (once again, since the sound is buffered, there's some delay).
Custom is just a provision for the future.

@item The sound filter is always off
Not implemented yet, even for the amiga!!!

@item Tracker doesn't understand powerpacked modules
It doesn't need to. Install xpk and xfh and it'll work.

@item Tracker is much bigger than some other players and takes up more memory.
But it should work on every amiga, is CPU-efficient, and supports
some unique features. 
@itemize @bullet
@item
   plays lha modules
@item
   transpose modules
@item
   scroll-window, somewhat more readable than just plain ciphers.
@end itemize
It is also portable.

@item The Invert loop effect sounds weird
too difficult to implement properly (call back@dots{}) right now

@item Tracker loses some memory sometimes
There seems to be a bug with the @code{CON:.../AUTO/WAIT} 
windows that stay around forever under the 3.1 beta I've got on my system. 
I haven't been able to check whether the problem stays under other system 
versions.  As I said, the current release is experimental.
@end table

@node DECstation, HP/UX, Amiga, Architecture dependent problems
@subsection DECstation

That port hasn't been upgraded for a loong time, so it will certainly need 
extensive surgery to work.

It uses a package called @file{AudioFile}. It is a public domain audio package
available from DEC @file{crl.dec.com} aka 192.58.206.2, @file{/pub/DEC/AF}.
the software will run on a number of platforms: Sun/NeXT/SGI/DEC.
The @file{AF_audio.c} code sends the sound directly to the AudioFile server.
There is but a slight problem! It Seg Faults when closing the Audio
connection@dots{} dunno why, haven't been able to get rid of it!
Uses 2 environment variables:
@table @code
@item AUDIOFILE
the name of the audio server to connect to for mono
playback. And for the Left Channel in stereo playback. eg. @samp{"machine:0"}
@item AUDIORIGHT
the name of the audio server for the Right Channel when
playing stereo.
@end table
This code is only tested for DEC 5000/20, 5000/25, Ultrix 4.2, Ultrix 4.3@dots{}
so I can't vouch for how well it'll work on other machines!

@node HP/UX, Linux/FreeBSD, DECstation, Architecture dependent problems
@subsection The HP ports

There are currently three ports (actually four if you count @ref{NextStep}):

hp3, hpalib and hplow. I've only been able to check
personally hplow, which is a horrible hack which accesses the audio hardware
directly, since hplib is not installed here. hpalib and hp3 are mostly
equivalent (done by different persons).

Difference between hp3 and hpalib (by Bjoern Stabells, @pxref{Credits}):
@itemize @minus
@item
my port, hpalib, uses AConvertBuffer(), while hp3 doesn't.  I'm actually
not sure if it's necessary. :)
@item
hp3 also supports 8bit linear, while hpalib only supports 16bit linear
@item
hpalib does a 3 second wait to let the audio stream fill up, while
hp3 doesn't, resulting in uneven playback (silent gaps in the music)
@item
hp3 rounds the frequency to always use a legal frequency, while
hpalib really should be able to handle all frequencies, but doesn't
right now.
@end itemize

@subsubheading Old documentation for the hp3 port

This documentation was written by Darryl Okahata, @xref{Credits}.

@emph{NOTE: this is still undergoing development, and will probably be
enhanced, as some parts don't work very well.}

This is a port of tracker, version 3.19, to HP-UX 7x5 machines with
audio devices that can handle 16-bit CD-quality stereo audio.  Tracker
plays Amiga MOD files, which are generally of much higher quality than
most computer music that most people have heard (however, MOD files
still aren't excellent in terms of sound quality---they are merely
"very good").

Note that you must have an audio device that supports stereo and
16-bit data.  Other audio output devices are not supported, although
support may be added in the future.

You also need HP-UX 9.01 to use this program, and you must have set
up audio services on your 7x5 workstation.  See the audio services
manual to see how to set this up.

@subsubheading Quickstart instructions:
@enumerate
@item
Put these files in some convenient directory.  The tracker binary
contains no hard-coded paths, and can be placed anywhere.

@item
The files whose names end with ".mod" are Amiga "MOD" files, which
contain instructions on how to play a song.  Each .mod file is one
song.

@item
To play a song to the headphone jack, do (for example):
@example
tracker -volume -20 -mix 40 boesen.mod
@end example
(You may have to add paths to the tracker binary or to @file{boensen.mod})

If you want the song to be output to the internal speaker, do:

@example
tracker -speaker -volume 0 -mix 40 boesen.mod
@end example

@strong{Important: do not use a volume level of zero (0) if you are listening
using headphones.  A volume level of zero is loud, and could
conceivably cause damage to your hearing.}
Frankly, you probably
shouldn't use anything above -5 if you are listening using
headphones.

@end enumerate

@subsubheading  Other notes:

@enumerate
@item
The volume is specified in dB, and the default volume setting is
-20dB.  Note that setting the volume to -5dB and higher could
conceivably cause damage to your hearing if you listen to mod files
using a headphone.
@item
After running tracker, X-Windows (vue) can no longer beep.  I have no
idea why, although I'm looking into this.
@end enumerate


@node Linux/FreeBSD, MM1/OS9, HP/UX, Architecture dependent problems

@subsection Linux/FreeBSD ports

This port only concerns the PC versions of Linux and FreeBSD, as I haven't been
able to check what kind of audio driver there is on the Amiga.

The program currently needs to be told about your audio hardware 
(8 bits/16 bits, @code{dsp_samplesize} constant in @file{Arch/Pcux/audio.c}). 
It should be possible to analyze that automatically with the recent drivers versions.
Also, you might need to fiddle with @code{UNSIGNED8} and stuff (I hope not).
In any case, do not try replacing @file{/dev/dsp} with @file{/dev/audio}@dots{}
@file{/dev/audio} is a sun-compatible driver that only accepts ulaw audio. 
It's possible to modify tracker to output ulaw output, but in that case it's stupid,
since the whole shebang will go linear16bit, ulaw, linear8/16bit, losing
@emph{both} resolution @emph{and} cpu time.

Since Linux/FreeBSD audio drivers change rapidly, check that your audio
driver is recent before blaming anything on tracker.

If you have a problem which is specific to the Linux/FreeBSD port, check with
Hannu Savolainen (@pxref{Credits}).

@node MM1/OS9, NAS, Linux/FreeBSD, Architecture dependent problems

@subsection MM1 Port
The plain MM/1 is a bit too slow to enjoy tracker in full. 
Be patient when you start---it takes a lot of time to initialize. 
When the processor is not fast enough, pauses will occur during playing. 
This can often be cured by selecting a smaller reproduction sampling frequency 
with the command line parameter @samp{-frequency}.

Mono output mode has been disabled since the MM/1 output is stereo.
To save the processor time in the critical loop, mixing between the left
and right channels has been disabled. 

The original program sends output to the sound driver in relatively small
pieces. I found that the quality of the output is improved when the sound is
played only if the buffer is full. The price for this is that the tracker
reacts rather slowly to the keyboard commands when playing. The code in
question is in the @code{flush_buffer} function---it is disabled right now. 
If you prefer the faster keyboard reaction at the cost of the quality, you may 
reenable it and recompile.

Playing on MM/1 is done using the system call @code{_ss_play} and using 
two buffers, so that when the first buffer is played, 
the other is being filled.

@node NAS, NextStep, MM1/OS9, Architecture dependent problems
@subsection Network Audio (NAS) port

The event oriented nature of NAS programming dictated a rather unusual
solution. Because NAS is built around an event loop, it demands to be in
control of the application. Instead of massively patching tracker, or
using co-routines with occasional snoops on the event queue 
in order not to miss events, the port uses @code{fork} with processes
squirting data down a pipe. The back end handles all the netaudio stuff, 
processing events and requesting data from the pipe when necessary. 
The front end waits until the backend returns an int saying 
what the max frequency is (or 0 if it fails to make a connection). 
Then it runs along producing data and stuffing it down the pipe as normal.

@node NextStep, OS/2, NAS, Architecture dependent problems

@subsection NextStep port

There is a known problem: You can't skip patterns forward or backward in quick
succession. It will restart the same pattern. This is because of the buffering
we have to do, while keeping syncronized with display output. I'll fix it,
when I find the time.

There used to be a problem with big endians/little endians machines. It
should be solved these days. Look around in @file{Arch/NeXT/audio.c} for 
@code{SNDSwapSoundToHost}.

Please double-check that your machine does support audio output, as this
is not the case with all NextStep machines.

In case you have a problem that is specific to the NextStep port, you might 
ask Rolf Grossmann (@pxref{Credits}).

The NextStep port of tracker was originally done on m68k hardware, 
but other people have tried it on the other NextStep platforms
as well (and submitted patches when necessary).

These are the main changes Rolf had to make, in case someone is interested:

@itemize @bullet
@item
Added support for sgtty (``old'' BSD) style terminal settings to 
@file{Arch/Unix/ui.c}.
Also cleaned this up and made it architecture independent. 
Verified that it works on Suns, too.

@item
Created a new variable @code{play_ahead} that tells how many buffer blocks
are queued before waiting for the sound to actually play. The buffering 
is required to ensure continous play, even if the program is not running 
continously (like when you're actually working with the computer).
You can set it's value using the port-specific option -play-ahead <n>.
I think the default of 5 is a good value and you probably won't need
to change it.

@item
Added call to @code{SNDSwapSoundToHost} before actually playing the sound, so
it should work on NS/intel now.

@item
Thanks to recent changes to the @file{Makefile} it should even work with
NeXT's native make. If you're having problems with it, use GNU make.

@end itemize
@node OS/2, Silicon Graphics, NextStep, Architecture dependent problems
@subsection OS/2 port

There is still an unfixed bug with respect to memory usage that may lead 
to crashes.
Everything uses the same drivers as for
Linux/FreeBSD (almost). Ask Bruno Monsuez directly (@pxref{Credits}).

@node Silicon Graphics, Sparc, OS/2, Architecture dependent problems
@subsection Silicon Graphics port

Maybe you don't have any audio software. If you can't find audio include
files/libraries that's a good bet.

Irix 5.3 includes the audio package as a default again. If you were using
Irix 5.2 or lower, upgrade. If you are using Irix 5.3, check that the audio
@emph{has} been installed.
Also, the standard @sc{sgi} @file{make} is crippled. @xref{Generic problems}.

If the audio output sounds like garbage, you probably botched the @samp{typedef}
of @code{SAMPLE}. Chars on Silicon Graphics are @code{unsigned} by default, and 
@code{SAMPLE} needs to be @code{signed char} 
@footnote{I have not put this in every
@file{config.h} for compatibility with old K&R compilers}.
This can happen very easily if the @file{config.h} tracker uses is not the 
Silicon Graphics one. Remove the @file{config.h} in the main directory, 
and let make replace it with the correct one.

@node Sparc, Porting tracker, Silicon Graphics, Architecture dependent problems
@subsection Sparc port

The Sparc version is probably the most tested since this is the architecture 
I happen to develop tracker under.

Tracker has run on Sparc 1, 1+, 5, 10, 20, under both SunOS 4.1.3 and Solaris 2.x.
There are still problems though, thanks to the brain damaged way Sun is 
running their business (insert your favorite expletives here).

In case you don't have acc (@sc{ansi} C compiler), tracker also works 
with the old K&R cc and also with gcc.  In fact, it is recommended to compile
tracker with gcc as gcc optimizes better (at least in tracker's case).

If you have Solaris 2.x, use target name @samp{solaris} instead of @samp{sparc}
(thanks to Dave Tiller, @xref{Credits}.)
include file names may change between @file{sun/audioio.h} and @file{sys/audio.io.h} or
some other weird combination. Ask Sun about that!

If you don't hear any sound, don't forget to check that the Sparc isn't sending its output
to the audio jack instead of the speaker or headphones.

There is a bug in older kernels of Sparc 5 that sometimes crashes the machine
when you play with @file{ioctl} and @file{audio}. 
It's easy to check: run tracker twice in quick succession. If the machine seems 
to hang five seconds when launching tracker the
second time, you have it! Upgrade, or you run the risk of crashing your 
machine!

There is some intricate code in @file{Arch/Sparc/audio.c} 
to check for the precise hardware used in your Sparc.

The @code{AUDIO_GETDEV} ioctl changed between SunOs 4 and Solaris 2, hence
the two distinct checks.

In case the code doesn't recognize your hardware, it reverts to base 8000Hz
Ulaw, unless you explicitly asks for a different frequency. It also informs
you about what hardware you have. Report the result to me together with your
audio manpage, and I'll fix it for the next release of tracker.

   
For the adventurous, there is a possible change to tracker which I haven't
put into the Makefile because it's too complicated. It turns out that
tracker is linked with @samp{-static} because this consumes much less
cpu in the critical modules. In fact, these critical modules are just
@file{resample.o} and @file{Arch/Sparc/audio.o}. If you feel like it,
you can use your linker separately to link these statically 
(something like @samp{ld -Bstatic -onew.o resample.o Arch/Sparc/audio.o})
and then link the whole executable dynamically.

On my setup, tracker shrinks from 188416 to 73728 bytes without any 
performance degradation.

@node Porting tracker, Performance issues, Sparc, Installation
@chapter Porting tracker to another architecture

If possible, you should use the same coding conventions as I do.
@itemize @bullet
@item All of tracker source code is archived with @code{RCS}. Use @code{RCS}
to maintain tracker if you can.
@item For me, tabs correspond to three spaces.
@item Standard file header:
@example
/* st_read.c
   vi:ts=3 sw=3:
 */

/* $Id$
 * $Log$
 * Revision 1.1  1995/09/03 15:44:31  espie
 * Initial revision
 *
 */

/* description of the file if applicable */
#include "defs.h"

#include <system_files>

#include <extern.h>

ID("$Id$")

@end example
The @code{$Id$} and @code{$Log$} entries are filled by RCS. @file{defs.h} 
includes some standard header files: @file{config.h}, @file{stdio.h},
@file{stdlib.h}, @file{string.h}. It also includes some useful standard
definitions. You are advised to read it.

@item My C is ANSI, but should be acceptable to K&R compilers. This means
that prototypes use the form @samp{function P((int param));}, where @var{P}
expands to a prototype or a @code{()} according to @file{config.h}, and that
actual function declarations should use old type prototype.
You don't have to care to much about that as I'm most probably be switching
to full ANSI soon.

@item Tracker uses ANSI functions, with some smattering of Unix-isms where
applicable. Be aware that tracker should stay portable, try to use ANSI C
functions whenever possible, and to encapsulate system functions where needed.

@item Tracker needs a decent address space, not a toy computer like an 
IBM PC.

@item Tracker needs files and pipes, it's real difficult to port to 
toy computers like MacIntoshes.
@end itemize

There are several parts of tracker that need porting.

@section The audio interface
In case samples need to be in a specific part of memory,
add @code{#define SPECIAL_SAMPLE_MEMORY} to @file{config.h} and
provide suitable @code{alloc_sample} and @code{free_sample} functions as
per @file{extern.h}.

If your audio hardware cannot emulate an Amiga directly 
(@pxref{Amiga audio hardware}), you will have to use resampling, 
@xref{Resampling details}.

Basically, you will build a specific @file{audio.c} file for your
architecture that holds two important functions:

@code{open_audio(freq, stereo)} opens the audio hardware for a given 
resampling frequency, and stereo or mono mode. This returns the actual
resampling frequency nearest to the frequency asked that will actually be
used. For your first try, open the audio channel in a suitable stereo or mono
mode at a fixed rate.

@code{output_samples(left, right, n)} adds two audio samples to the stream
in progress. Both samples have n bit resolution.

Other functions in @file{audio.c} as documented in @file{extern.h} can 
mostly be replaced by suitable stubs.

This audio architecture will probably change for release 5, in order to
provide for more flexibility, but you shouldn't have to worry too much
about that yet, as I will provide a `compatibility interface'.

You have some templates of suitable configuration files in the directory 
@file{Arch/Port}. Specifically, this @file{config.h} removes most of 
tracker system dependencies. @file{ui.c} is a minimal user interface file
that needs only stdio to work, and @file{audio.c} is a minimalist audio
interface derived from the Sparc audio interface.

Create a directory for your architecture, copy these files there, update
the @file{Makefile} to add an entry for your architecture. You need to
edit @file{config.h}, since as shipped it doesn't work, and to implement
the base functions as discussed in @file{audio.c}. Don't forget to use
the set of routines in @file{common.c}. With them, you can get most audio
hardware running.

When this part works, try to implement the remaining of the audio functions.
First, try to have parameters working, like different sampling rates, mono
and stereo, then try to add the advanced features.

@section The user interface
Once the audio works, try to fix the user interface up. 
If your system looks like a standard Unix, you'll just have to discover
how to put your terminal in cbreak mode@dots{}.
Usually, the @file{Arch/Unix/ui.c} file together  @code{#define USE_SGTTY} or
@code{#define USE_TERMIOS} will be enough. 
If you are not under Unix, this
might be more difficult. 
Also note @code{run_in_fg}, which decides whether
to do all this stuff or not, since background processes tend to fail if
they try to output something.

Recently, I've added support for xterms (triggered by @code{PREF_XTERM})
and for color terminals (triggered by @code{PREF_COLOR}).
@code{PREF_XTERM} is set by the @var{TERM} environment variable in 
@file{main.c}, @code{PREF_COLOR} is set according to the compilation switch
@code{COLOR_IS_DEFAULT}. Note that both of these settings may be overriden by
command line options.

If your machine uses another color model, you will have to add suitable 
definitions to @file{color.c}. Note that I'm not satisfied with the way
color currently is defined, so I might change this stuff.

@section File systems
To support compression, your system must have popen and pclose. If it does not,
you'll have to modify @file{open.c} extensively if you want compression.
Try to remove @code{#define NO_PIPES} from @file{config.h} and recompile 
@file{open.c} to check whether compression works or not.
You'll also have to adapt @file{compression_methods} to your system.

I'm currently investigating into a more supple variant of tracker that would
use sockets instead, so that all the decompression shebang would lie with a
perl script (that could also cache file, access the network, and everything).

You also need @code{stat}, @code{S_ISDIR}, @code{readdir} for the 
automatic expansion of directories in @file{play_list.c} to 
work@footnote{I'm going to make this much more portable soon}.

@section Beyond the simple port
I would like some people to work on more interesting ports. The Amiga version
of tracker, for instance, includes some significant improvements, but I have
no time myself to be writing an X-Window port of tracker. 
Due to the asynchronous nature of tracker, the audio output is usually 
buffered. Some events, like the scrolling display, should occur when the
corresponding audio event is played. The Amiga, Sparc, and NeXT versions
include a post-synchronization function. They use the @code{sync_audio}
function@footnote{Well@dots{} the Amiga version does not, but it should.
I just haven't updated it yet.}

Basically, @code{sync_audio} inserts a hook into the audio pipeline: a
function to call, with some parameters, when the audio stream finally 
reaches the current point. More precisely, there are two functions: one
to call when the audio stream reaches this point, and an alternate function
to call to clean up if the audio stream never reaches this point. For 
instance, when you depress @kbd{n} on the keyboard, it would be most 
unpractical to have all the accumulated scrolling info suddenly appearing
on the screen, so it is flushed. But there is some memory accounting involved,
hence the flushing function calls @code{free} on each line involved.




@node Usage, Technical Information, Performance issues, Top
@chapter How to use tracker
@section Compression
Various compression methods are supported through pipes. 
There is a simple-minded configuration file @file{compression_methods} 
(check @file{Makefile} to see where you want to install it). Its format is:
@display
extension       command line in printf format.
@end display

For instance, 
@example
.gz	        gzip -dc %s
@end example
(simple, isn't it ?)

@section Environment variables
@table @asis
@item TRACKER_DEFAULTS
The set of options invoked by default, e.g., my options are
@example
-scroll -freq 44 -color -tolerant
@end example

@item MODPATH
A path where you wish to look for mod files. This
is a sh-styled path: @samp{setenv MODPATH dir1:dir2:...}

@item TRACKER_COMPRESSION 
Overrides the default @file{compression_methods}
file@dots{} Very useful when, for example, you want to use a binary fetched from
the net.
@end table

@section Command line switches:

Note that tracker now accepts directories as arguments. It will
automatically recurse down the tree to find modules.
@table @asis
@item @samp{-stereo/-mono}
switch between stereo and mono output. Some modules need mono output to
sound right. Apart from that, on stereo-capable machines, mono output usually
uses less CPU.
@item @samp{-mix <percent>} 
for stereo output, decide how to mix left/right channels.
0 is spatial stereo, 100 is mono. The change tends to
be exponential, so you may want to experiment with values 
around 90+.
@item @samp{-frequency <freq>}
set the audio output frequency (kHz). The normal output frequency
is a `normal' frequency for your machine. Normally <freq> will be 
rounded to an actual output frequency available on your machine.
@item @samp{-oversample <n>}
where n is usually 1, 2 or 4. Controls the accuracy of the sound
reproduction by trying to use 1,2 or 4 sample values
to render a given sample. The higher, the better, but the more CPU it
uses. Changing the frequency usually works better, but there are cases 
where 2 or 4 will give you a better rendering for some module. 
The default value (1) is quite good at high frequencies, but not so good
on, for instance a sparc station 1 at 8000 Hz. 
The code in @file{resample.c} is optimized to get oversample 2 and 4
to be reasonably efficient@dots{} After 4, you probably won't hear any
significant improvement.
0 is a special mode, called linear resampling. See @file{resample.c} for
details.
@item @samp{-new/old/both}
select a soundtracker format, between new (31 instr), old (15 instr)
and both (auto-detect what's going on). You should only use it if
tracker gets very confused on a module.
@item @samp{-picky}
do not allow for any problems in a module.
@item @samp{-tolerant}
allow for many problems that would normally stop a module
@item @samp{-repeats / -repeats <n>}
repeat each module n times. With no value (or a 0), repeat the
module forever.
@item @samp{-looping}
make module list loop as a whole.
@item @samp{-verbose}
show a sample listing for the module.
@item @samp{-scroll}
scroll-display the module being played.
@item @samp{-color/-bw}
use with terminals with color-ansi capability (e.g., kterm)
to get a colorful scroll.
@item @samp{-speed <n>}
change the base tempo to n. The normal value is 50 (PAL video
frequency). Some modules have been written on a buggy NTSC composer,
so you may wish to use -speed 60. Weird values like -speed 10 or
-speed 2000 are allowable. 
Note that the samples may sound a bit strange since you only change
the tempo, but the samples till play at the same speed.
@item @samp{-pal/-ntsc}
@sc{pal} or @sc{ntsc} tempo. Shortcut for the @samp{speed} option.
@item @samp{-speedmode (normal|old|finefirst|normalfirst|alter)}
compatibily hack for old soundtracker tunes and various variants.
@samp{old} (also known as @sc{VBLANK} mode) will force all speed commands
to affect only the major tempo. @samp{alter} is an alternate version of
the automaton found in some soundtracker tunes. Other options are mostly
there for debugging purposes.
@item @samp{-transpose <k>}
transpose the song up k half-notes. If k is negative, obviously transpose
the song down. The results will vary according to the module. This command
changes only the pitch independently from the speed, so modules which
use samples as `strictly instruments' will work better. Of use when you
get bored@dots{}.
@item @samp{-start n}
start the module at pattern number n instead of number 0.
@item @samp{-randomize}
plays the module list in random order.
@item @samp{-list file}
plays the modules listed in the given file (one module name per line, spaces
are significant).
@end table

The Amiga version uses @code{ReadArgs} style argument parsing, and doesn't
recognize the precise same options.

@section Sample control
@table @asis
@item @samp{-cut 012@dots{}abcd}
suppress samples from the audio output.
@item @samp{-add 012@dots{}abcd}
add samples to the audio output (exclusive with cut).
@item @samp{-halve 012@dots{}abcd}
halve these samples volume.
@item @samp{-double 012@dots{}abcd}
double these samples volume (exclusive with halve).
@end table

@section Runtime controls
@table @kbd
@item	n
go to next song.
@item	p
restart current song/go to previous song.
@item	>
fast forward.
@item	<
rewind.
@item	S
@sc{NTSC} tempo (60 Hz). @ref{Amiga audio hardware} for the reason this exists.
@item s
@sc{PAL} tempo (50 Hz).
@item	q
@itemx	x
@itemx	e
quit right away.
@item m
switch to monaural mode.@footnote{This key is equivalent to @samp{-mix 100}, i.e.,
it does not reduce the CPU bandwidth used by tracker as when in true mono mode.}
@item M
go back to stereo mode.
@item	+
(Sparc only) increase sampling rate.@footnote{Warning: there is a bug in the
SunOS 4.1.3 kernel that may manifest itself when using this option}
@item	-
(Sparc only) decrease sampling rate.
@end table

@node Technical Information, Tracker memory consumption, Usage, Top
@chapter Technical information

Throughout tracker, I'm trying to establish a trend of
well thought-out and intelligent music playing programs.
Tracker's code is relatively high-level, and I'm trying my
best to substitute an intelligent approach to the traditional
`brute-force' system of @sc{ASM} playing routines.
@menu
* Tracker memory consumption::
* The Protracker format::
* Amiga audio hardware::
* Resampling details::
* Amiga implementation::
@end menu




@node Tracker memory consumption, The Protracker format, Technical Information, Technical Information
I've gone to some length to ensure that tracker doesn't use too 
much memory, and is still fast enough. Specifically, I'm storing note values 
instead of actual pitches
(@pxref{The Protracker format}). 

Some modules don't use all the patterns stored
within the file, and in fact, only junk is stored in the unused patterns.
For that reason, tracker now analyses a module to remove unused patterns 
and unused samples.  This ensures that note values will be correct, 
reduces memory consumption slightly, and junks binary files in a quick way.

Here is a rundown of tracker memory consumption, for a 
typical machine where @code{short} values
occupy 2 bytes and @code{long} values 4 bytes:

@itemize @bullet
@item pitch table for 17 finetunes and 120 notes. Weighs in at 4080 bytes.

@item sample info for all used samples. Each sample info is about 200 bytes 
long, including sample name, and 100 bytes of volume scaling table. 
Only as many sample infos as samples are used, add one sample info for 
an `empty sample'.

@item sample memory for used samples only. Precious chip memory on the Amiga.
Since I've seen `The player' from Jaarno Paarnen, I'm thinking of adding
decompression code for the samples on-the-fly. Also, a real resampling mode
on the Amiga or a sample cache would be cool.

@item 4 bytes per event, 1036 bytes per used pattern (for 4 tracks songs).

@item song data structure, approximately 300 bytes.

@item sine table for vibrato and tremolo (@pxref{Base effects}), 
approximately 768 bytes.

@item buffered extendedfile, 15K.

@item audio buffer, when applicable. Usually set for one second of sound
(around 100K usually).

@item pattern load buffer, 1K.
@end itemize

In the end, memory consumption is very close to the actual length of the 
file on disk (sometimes less).
As a benefit, the file is scatter-loaded into memory. 
Tracker works well even when the memory is somewhat fragmented.

Recently, I've added a memory allocation logging tool to tracker 
(@file{mung.c}). To use it, you just have to recompile tracker with 
@samp{-DMUNG} and add @file{mung$O} to the list of object files.
Tracker will then log all of its memory activity to @file{logfile}. 
It is then trivial to write, for instance, a perl script that will analyze
this file and retrieve interesting statistics about tracker.

I was able to trace several minor memory leaks thanks to this tool, and
discover that tracker uses very little memory of its own. In fact, tracker
uses most of its memory for audio samples (some 500K out of 660K) on a 
real life example.

This shows quite clearly why it might be useful to load samples on need
instead of having them in memory all the time.

@include protracker.fmt

@node Amiga audio hardware, Resampling details, Set tempo, Technical Information
@section The Amiga audio hardware

Since part of the behavior of soundtracker-like programs depends heavily on the
Amiga audio hardware, it is only suitable that there be a description of this
hardware here.@footnote{A more precise description can be found in the Amiga
Rom Kernel Manual: Hardware, published by Addison Westley}

The Amiga has four completely independant audio channels, numbered from 0 to 3.
Channel 0 and 3 are connected to the left-side stereo output, 1 and 2 to 
the right-side---hence the strange numbering in soundtracker programs.

Sound data is 8 bit signed in standard 2 complement (-128<=v<=127).

The volume is also set independently from 0 to 64 (0<=v<=64). 
There is no typo there! In terms of the hardware, the 64 value means that the
hardware dampening is disconnected.

The volume is linear. Sample values as follows:
@display
Volume   db
---------------
64         0
48       - 2.5
32       - 6.0
16       -12.0
@end display

The sampling period is limited by the number of @sc{dma} cycles allocated to an 
audio channel, and traditionally linked to the video frequency. The formulas 
are of little interest. The result is used in notes.c for instance.

The Amiga features a low-pass filter that can be disconnected through
software. The filter becomes active around 4KHz and gradually begins to attenuate
the signal. Generally, you cannot hear frequencies higher than 7KHz.
Most soundtrackers disable the low-pass filter, and use it only for special
effects.

Finally, tracker is also tied to the Amiga display hardware, oddly enough. Older
versions of soundtracker used the video @code{VBLANK} interrupt for timing, hence
soundtracker is based upon 50 Hz ticks. This also explains why some older files
sound better when played with 60 Hz ticks (@sc{NTSC} instead of @sc{PAL}).

@node Resampling details, Amiga implementation, Amiga audio hardware, Technical Information

@section The core of tracker: the resampling engine

Any profiler will tell you that tracker spends most of its time emulating
the Amiga hardware in @file{resample.c} (except on the Amiga, of course).
Basically, the machine has to compute the actual stream of bytes to output.
There are several things to do:
@itemize @minus
@item
choose the right sample value in the sample. This is what the simple automaton 
@code{DO_NOTHING}/@code{PLAY}/@code{REPLAY} does. Each pitch value gives
rise to a @code{step} value (see @file{notes.c} for the step value table).
tracker runs down the sample `by hand' using fixed-point arithmetic.

@item
Mix samples in the right proportions. There is a volume table for each sample
(computed in @file{st_read.c}) that is used to scale the sample value. Then 
sample values are added according to left side/right side.

@item
Outputting both sides. Some further mixing occurs in the various @file{Arch/@dots{}/audio.c}
files: for a convincing stereo effect, some part of the right side has to go out on
the left side and vice-versa. This is usually accomplished thanks to a generic routine
of @file{Arch/common.c}.

@item
Converting the output for the hardware used. At this point, the hardware output frequency
has already been taken into account, stereo has been taken care of as well. It remains
to convert the sample from linear to ulaw, swap bytes, handle buffers, scale the sample
to the right size/signedness. This is the only really hardware-dependent part.
@end itemize

There is also some provision for oversampling: instead of using one sample value for
each sample output, we add several sample values distributed in the right area. 
@itemize @minus
@item
Multiply the output frequency by @code{oversample}. That way, we get @code{oversample}
values for each value output.
@item
Collate all sample values and downscale accordingly. In the latest version, since the output
size can vary, this is easiest when @code{oversample} is a power of two, since it is enough
in this case to augment the output size accordingly.
@end itemize

All this can take a lot of time, too much for your cpu maybe.
What can be done to alleviate the problem ?

@itemize @minus
@item
On any machine with hardware sufficiently similar to the Amiga hardware (at least
four channels and independent replay speed), write routines similar to the
Amiga.

@item
Keep it simple@dots{} Even a stupid test might slow the routine down. Hence,
the duplicated code according to the value of @code{oversample}, 
the special `empty' sample and its properties (
@code{samp->fix_length == 0 && samp->rp_start == NULL}).
@end itemize

As a consequence, new sample styles (like 16 bit samples) should be implemented
as new types of commands like @code{DO_NOTHING}, @code{PLAY}, @code{REPLAY} 
(@code{PLAY16} and @code{REPLAY16} come to mind), even though this will
 duplicate loads of code.

Recently, the code has changed to allow for more than four channels. This incurs
a slight overcost (two more additions), which is actually negligible for 
oversampled replay, and has been deemed acceptable for simple replay.

The lookup table for converting 0-64 volumes to a linear scale is a cheap way
to allow for all sorts of manipulations on the sample volumes at a low cost,
and also to use n-bit samples in an almost transparent way, even with n not
being an integral multiple of 8.




If your machine is really slow, and uses ulaw, computing a complete lookup
table (all 16384 values of it) might speed things up somewhat. Removing the
oversampling test altogether might do it also. Then you can unroll the
@code{for(i = 0; i < number; i++) loop}, not initialising @code{value[LEFT_SIDE]} and
@code{value[RIGHT_SIDE]} to 0, but giving them their initial real value.

If all that fails, you can still find a better compiler, check whether your
audio bandwidth is not too limited, downgrade the audio output to a lower
acceptable frequency (stuttering and outputting several times the same 
sample is possible). Lastly, you can still go to assembly language code.

An important optimization may exist if your machine uses dynamic libraries
and dynamic linking: on some Unixes (Sparcs for instance), some table lookup
@c Hmmm ... Sparc is not a Unix ...
and dynamic linking occurs at runtime, which means that function calls may be
slightly slower. In that case, coercing your linker to use static linking may be
a good idea. If you can, link only @file{Arch/machine/audio.c} and 
@file{resample.c} statically, since this is the place where the speed bottleneck
occurs. This way, you will get both the advantages of static linking (speed) and
dynamic linking (size).

Maybe the specific audio code for your architecture can be improved.
Recently, I've added some optimization to @file{Arch/common.c}.
Checking where tracker was spending time, I discovered that almost all the time
was spent computing divisions/multiplications, like for the stereo mixing.
Instead of computing:
@display
realLeft = left*primary + right*secondary
realRight = right*primary + left*secondary
@end display

computing

@display
sum = (left+right) * (primary+secondary)/2
diff = (left-right) * (primary-secondary)/2
realLeft = sum+diff
realRight = sum-diff
@end display

gains two multiplications! Just realize that @code{(primary+secondary)/2} and
@code{(primary-secondary)/2} don't change and can be precomputed.

Apart from primitive architectures where multiplication and addition costs
are the same, this gains a lot. On a Sparc 5, this makes the difference between
being able to use @samp{-over 2 -freq 44} and not!

There is a switch in @file{Arch/common.c} (@code{NEW_OUTPUT_SAMPLES_AWARE})
used for compatibility. In older implementations of tracker, the resample
code called @code{output_samples(left_value, right_value)}, where left
and right values were 23 bits signed. The newer version call is
@code{output_samples(left-value, right_value, width)}, with width the number
of bits used. Newer ports should define @code{NEW_OUTPUT_SAMPLES_AWARE} and
use the code of @file{Arch/common.c} whenever possible.

This gains a lot when, for instance, oversample is used, since this keeps
the shifting of data left or right to a minimum.
Check whether your implementation uses the new form of @code{output_samples}.
If it does not, it is a good idea to convert it.

Also, the audio routine should give its output resolution when needed. Right
now, tracker doesn't use it, but when I get around to adding 16 bit samples,
tracker will routinely convert them down to 8 bit if the audio output is only
8 bits.

As a rule, the Sparc version is the most complete. Try to refer to it in case
of doubt.

@node Amiga implementation, Concept Index, Resampling details, Technical Information
@section Peculiarities of the Amiga implementation: tracker versus Delitracker ?

In fact, this title is a joke@dots{} tracker doesn't compare with
Delitracker at all. The purpose of the two programs is quite different,
and Delitracker is most certainly the best at what it does.


Anyway, tracker yields some very interesting features, probably unique.
@itemize @minus
@item
it's written entirely in C.
@item
it's portable.
@item
it goes through the OS for everything (except the audio filter toggling,
but that's not provided for right now).
@item
you can steal audio from under it without any trouble!
@item
it reads archive files (like lha or zoo).
@item
it buffers its sound output, so that it runs at about the same pace on
every machine @emph{without needing any kludge}.
@end itemize

The old version used the timer @code{WAIT_EBLANK} unit for all its timings and
assumed everything was done fast enough that the new audio commands would 
fall on the right beat. 

This new version uses a two tasks model: task 1 fills messages telling
what to do at a given time until it has no messages left and sends them
to task 2. Task 2 peeks at the messages it received, waits for the right
time to act on them, performs the sound changes, and sends the message back
to task 1.

This offers lots of advantages.
@itemize @bullet
@item
time-critical code is bundled in one simple routine that
basically only has to wait for the right instant and send very simple events
to the audio device. I've upped the priority of this task to 90 since it
waits most of the time.
@item
tracker modules do not always need the same amount of processing power,
the load might even vary (and does vary) during one given module. Using
buffering means you equalize the load and you can then play very complex
modules on a small Amiga even with unoptimized code.
For instance, scrolling output with @samp{scroll} works on almost 
any Amiga and any module unless you @emph{really} need too much 
processing power for it to work.@footnote{This means that, once again, 
thinking a lot about how to code things wins hands down over the brute force
approach. Assembly, no-system hackers, eat your hearts out! Tracker does
not use any assembly code, is probably badly optimized in places, but what
do we care ? It runs on anything at a decent pace.}
@item
because of the buffer, we @emph{do} know about the samples we'll have to play
with some look-ahead. It should be feasible to load them from normal ram
to chip without much trouble@dots{}.
@end itemize

and some drawbacks too:
@itemize @bullet
@item
even though sas/c tries and help you, it's still difficult to debug 
multithreaded programs. I've circumvented that difficulty by adding conditional
code that splits tracker into two distinct programs.
@item
handshaking is easy to get wrong. Forgetting to take some messages into account
can lead you to lose some, and end up with a deadlock when no message is left.
@item
since audio output is buffered, the interface tends to react with some delay
unless you program things carefully. 
Part of the problem is alleviated by using @code{ReadEClock()} to get some feedback
in the necessary buffer.
@end itemize

Another stupid problem I got in while programming the Amiga support was using
the standard @code{WAIT} unit of the @code{timer.device}, the one based on 
@code{VBLANK}.
This was very stupid: using a timer unit of the same resolution (or about so)
as the events I was wanting to measure. Since I got unlucky, it appeared to
work correctly for quite some time@dots{} I'm usually looking at a rock-solid
@sc{ntsc} 60@dmn{Hz} display. 


Some new add-ons: the event handling is completely decentralized. See @file{events.c}.
This is an interesting way to bridge the gap between the usual programming model
and the event-driven model.

There is some problem with arq not recognizing requesters built through 
@code{BuildEasyRequest()} instead of using @code{EasyRequestArgs()} directly, 
but it enables us to add a filerequester 
(the @code{reqtools} one since Amigados @code{asl}'s 
doesn't support truly asynchronous operation@dots{}
Yet another blunder from Commodore).

I haven't put any iconifying possibility in the main window. I feel that Menufy/Iconify
provide very nicely for it@dots{} and they work for me, so why should I care. 
Already tracker weighs in at 60 K bytes, that's a true monster of a player program!

In the future, I will try to add more controls to the user interface.
After all, I've got an incredible amount of data and switches
about a module that I don't use at the time:
@itemize @bullet
@item
global volume,
@item
volume on a per-instrument basis,
@item
volume on a track per track basis,
@item
non-linear volume scaling,
@item
on-the-fly transposition,
@item
switching instruments on/off@dots{}
@end itemize
obviously, the most difficult part is to write the interface itself.
All of this is possible today!


@node aminet, Finding a specific file, Background information, Top
@appendix The aminet network
@cindex Aminet
@cindex Obtaining tracker

Aminet is a network of ftp sites for Amiga software. They offer a comprehensive
array of Amiga programs and press new CD-Roms periodically. Aminet is the official
repository for tracker, the place where you can find the latest version.

The following is adapted from aminet's official @file{readme}.

@menu
* Finding a specific file::
* Mirror sites of Aminet::
* Accessing Aminet on the Internet::
* Accessing Aminet without Internet::
* Copyright status and disclaimer::
* Background information::
@end menu

@node Finding a specific file, Mirror sites of Aminet, aminet, aminet
@appendixsec Finding a specific file
Before you start looking, you should be aware that not all Aminet sites
are complete. Most delete older files. So if you don't find something at
your 'home' mirror, use one of the big sites that keep everything online
like @file{ftp.wustl.edu}, @file{ftp.uni-paderborn.de} or @file{ftp.doc.ic.ac.uk}

Sometimes you are looking for a certain category of file without knowing
a name. You then best go by directory. The directories within @file{/pub/aminet/}
are:

@display
new/     New files, upload here. (See new/README.BEFORE.UPLOAD)
priv/    Private uploads.        (See new/README.BEFORE.UPLOAD)

biz/     Business software       hard/    Hardware related
comm/    Communications          info/    Site information
demo/    Euro style demos        misc/    Miscellaneous
docs/    Text documents          mods/    Music modules
dev/     Developer software      mus/     Music software
disk/    Disk tools              pix/     Pictures
game/    Games software          text/    Text related
gfx/     Graphics software       util/    Utilities
@end display

A complete list of the sub-directories can be found in the file @file{TREE}.
A local @file{INDEX} with descriptions is in each subdirectory, however it only
lists the files that exist on that site, not the ones available elsewhere
on Aminet.

@node Mirror sites of Aminet, Accessing Aminet on the Internet, Finding a specific file, aminet
@appendixsec Aminet mirrors

These are the members of Aminet and have the files from here.  All mirrors
have the new files but most delete old files, however @file{ftp.wustl.edu},
@file{ftp.uni-paderborn.de} and @file{ftp.doc.ic.ac.uk}  keep all files.  
@strong{Whenever possible, use the mirror that is the closest to your place.  Most mirrors
get updated three times a day.}

@display
Location     Name                     IP Address      Path         Files

USA (MO)     ftp.wustl.edu            128.252.135.4   pub/aminet/    ALL
USA (WI)     ftp.netnet.net           198.70.64.3     pub/aminet/    ALL
Scandinavia  ftp.luth.se              130.240.18.2    pub/aminet/    ALL
Switzerland  ftp.eunet.ch             146.228.10.16   pub/aminet/    ALL
Switzerland  ftp.math.ethz.ch         129.132.104.6   pub/aminet/   1000
Germany      kelly.uni-paderborn.de   131.234.128.206 pub/aminet/    ALL
Germany      ftp.uni-paderborn.de     131.234.2.42    pub/aminet/    ALL
Germany      ftp.uni-stuttgart.de     129.69.18.15    cd  aminet    4000
Germany      ftp.uni-erlangen.de      131.188.3.2     pub/aminet/   7000
Germany      ftp.uni-trier.de         136.199.8.81    pub/aminet/   4500
Germany      ftp.cs.tu-berlin.de      130.149.17.7    pub/aminet/   4000
Germany      ftp.tu-chemnitz.de       192.108.33.193  pub/aminet/   4000
Germany      ftp.fh-augsburg.de       141.82.16.242   pub/aminet/   3000
Germany      ftp.uni-oldenburg.de     134.106.40.9    pub/aminet/   2500
Germany      ftp.uni-bremen.de        134.102.228.2   pub/aminet/   2000
Germany      ftp.uni-kl.de            131.246.9.95    pub/aminet/   1500
Germany      ftp.uni-siegen.de        141.99.128.1    pub/aminet/   1500
Germany      ftp.rz.uni-wuerzburg.de  132.187.1.2     pub/aminet/    700
France       ftp.cnam.fr              163.173.128.15  pub/aminet/   8000
Portugal     ftp.ci.ua.pt             193.136.80.6    pub/aminet/   2000
UK           ftp.doc.ic.ac.uk         155.198.1.40    pub/aminet/    ALL
UK           micros.hensa.ac.uk       148.88.8.84     pub/aminet/   8500
@end display

@node Accessing Aminet on the Internet, Accessing Aminet without Internet, Mirror sites of Aminet, aminet
@appendixsec Accessing Aminet on the Internet
There are many other ways than FTP to access Aminet. On the Internet:

@table @asis
@item ADT
This is a front end for FTP that allows easy access to Aminet. Get
it from @file{misc/unix/adt*.c} and compile it on your UNIX box by typing
@samp{sh adt.c}.

@item WWW
Mosaic or Lynx are a very decent way to access Aminet. Try the
URLs @file{http://ftp.wustl.edu/~aminet/} or 
@file{http://ftp.eunet.ch/~aminet/}
where you can also find pointers to other Aminet sites with WWW
support.

@item FSP
Aminet Files can be downloaded from the FSP site @file{ftp.luth.se} at
port 6969. @file{ftp.wustl.edu} and @file{ftp.doc.ic.ac.uk} have FSP on port 21, 
but can't be reached from everywhere (just try). Uploads are accepted
at wustl and luth.

@item telnet
@file{ftp.doc.ic.ac.uk} strikes again. You can telnet to 146.169.2.1
and log in as 'sources', which gives you a UNIX account where you can
download the files on src using commands like 'sz' and 'kermit', or
just browse around.

@item NFS
The only Aminet site that allows NFS mounting of the archives is
@file{ftp.wustl.edu}. FTP there and read the details in /README.NFS

@item IRC
On Internet Relay Chat, you can talk to various server robots like
Mama, LitBot and MerBot, to do queries and retrievals. Find out more
about them using '/msg mama help', for example.

@item finger
To find out what's been uploaded to Aminet within the last
week, enter @samp{finger aminet@@ftp.wustl.edu} or @samp{finger aminet@@ftp.eunet.ch}

@item gopher
Gopher is specially supported by several Aminet sites. Just 
type @samp{gopher <sitename>} or @samp{gopher -p <startpoint> <sitename>}.

@display
  USA (MO)    ftp.wustl.edu        1/pub/aminet/info/goph
  USA (TX)    ftp.etsu.edu         1/AmigaArchives/Aminet
  SWITZERLAND ftp.eunet.ch         1/pub/aminet/info/goph
  GERMANY     ftp.uni-paderborn.de 1/Service/FTP/Direct/ftp-server/aminet
  UK          ftp.doc.ic.ac.uk     1/pub/aminet/info/goph
@end display

@end table
@node Accessing Aminet without Internet, Copyright status and disclaimer, Accessing Aminet on the Internet, aminet
@appendixsec Accessing Aminet without Internet

@itemize @minus
@item
Get internet access. Certainly the most comfortable way to access
  Aminet but sometimes expensive. Some Internet providers are:
@display
  USA         Portal  Voice 1.408.973.9111  Modem 1.408.973.8091
              Netcom  Voice 1.408.554.UNIX
  GERMANY     EUnet   Voice +49.231.972.00  Fax +49.231.972.1111
  SWITZERLAND EUnet   Voice +41.1.291.45.80 Fax +41.1.291.46.42
  UK          Demon   Voice +44-81-349-0063 Fax +44-81-349-0309
@end display
@item
Aminet mailserver. The Aminet mail server can do various things for you,
  like doing finds and accepting uploads, but it does not send out 
  binaries. Send HELP to aminet-server@@wuarchive.wustl.edu to find out
  more.

@item
Bin mailserver. The Aminet site src.doc.ic.ac.uk has an email server
  that sends out uuencoded binaries. Send a message with HELP in the body
  to ftpmail@@doc.ic.ac.uk or ftpmail@@ftp.luth.se . You can also use 
  ftpmail@@decwrl.dec.com to retrieve files from any Aminet site, but 
  please use an American one to save bandwidth. Send HELP there for 
  information, too. Germans try ftpmail@@uni-paderborn.de , Canadians
  send HELP to MRCserv@@MtRoyal.AB.CA .

@item
Modem. The following BBSes carry up-to-date Aminet files. Most have
  more phone numbers than we can mention here, call to see a list of
  the others. List sorted by phone number.

@display
  Country     Name        FIDO          Phone            ISDN
  -------     ----        ----          -----            ----
  USA (MS)    The Gateway 1:3604/60     (+1)601 374 2697  
  USA (CA)    Heavy Metal 1:202/1112    (+1)619 232 4919
  USA (NC)    The C: Dir                (+1)919 787 6211
  Canada      RCN Networks              (+1)418 653 3099       
  Canada      TunnelVisio 1:153/910     (+1)604 535 9826
  Canada      MidnightMag               (+1)905 796 2931,
  France      Ramses      2:320/104     (+33)1 45845623
  Italy       Glass Globe 2:332/118     (+39)577 959054
  Italy       SpeedOfLife 2:335/533     (+39)931 833773  
  Switzerland Amiga Micro 2:301/819     (+41)1 3001008   (+41)1 3001009
  Switzerland Helvetica   2:301/723     (+41)1 3130879   (+41)1 3101016
  Switzerland Dolphins                  (+41)1 8450936   (+41)1 8846028
  Switzerland AmiCall     2:301/722     (+41)1 9804297
  Switzerland Turicum                   (+41)1 9918501   (+41)1 9918503
  Switzerland Dive-Inn    2:301/325     (+41)22 7518103  (+41)22 7518105
  Switzerland Alphanet                  (+41)38 414081
  Switzerland LogicPalace 2:301/706     (+41)31 7320051  (+41)31 7320044 
  Switzerland LINKSys                   (+41)61 3215643  (+41)61 3832007
  Switzerland AUGS BBS                  (+41)62 445041   (+41)62 445041
  Austria     Amiga World 2:310/72      (+43)1 5044269   (+43)1 5047701
  Denmark     Scala BBS   2:230/418     (+45)44680300    (+45)44861540
  Germany     Surprise                  (+49)201 329761  (+49)201 8315005
  Germany     Art-Line                  (+49)202 596003  (+49)202 2546013
  Germany     T.O.M.                    (+49)202 595267
  Germany     Pleasure                  (+49)203 431366
  Germany     SMachine                  (+49)203 4061447 (+49)203 9940127
  Germany     Grisubox                  (+49)2065 24447
  Germany     Karma Designs             (+49)208 670722
  Germany     Future Line               (+49)2041 686829
  Germany     Blue Moon                 (+49)2065 66407
  Germany     TrkPool                   (+49)208 808640
  Germany     Delvinor                  (+49)2131 549457 (+49)2131 951253
  Germany     Newswire                  (+49)2154 5011
  Germany     Debuwi                    (+49)2236 83233
  Germany     Candys                    ---              (+49)221 462138
  Germany     Darkness                  (+49)2273 1096   (+49)2273 910062
  Germany     X-RAY                     (+49)228 455893
  Germany     CBonn                     (+49)228 666588
  Germany     Blanker                   (+49)231 815739  (+49)231 9812094
  Germany     SID                       (+49)231 448496
  Germany     Fantasie                  (+49)2381 675700
  Germany     Stingray                  (+49)2385 6542   (+49)2385 910031
  Germany     ASBM                      (+49)251 791650
  Germany     Circus                    (+49)281 24001
  Germany     Amiga Mbx                 (+49)30 3739293
  Germany     TERM                      (+49)30 4537288  (+49)30 45470171
  Germany     Quick                     (+49)40 5479638
  Germany     ITHH                      (+49)40 6064098  (+49)40 60680341
  Germany     DOOM                      (+49)4223 8355   (+49)4223 95004
  Germany     Flight                    (+49)4442 72138  (+49)4442 920362
  Germany     Delbox                    (+49)5250 53785  (+49)5250 99952
  Germany     MultiCom                  (+49)5321 45440  (+49)5321 305373
  Germany     Black-Z                   (+49)6142 46278  (+49)6142 924080
  Germany     SLTO                      (+49)615 264898
  Germany     TecMania                  (+49)6157 87427  (+49)6157 910121
  Germany     48'er       2:2468/6020   (+49)6203 180293
  Germany     WestCoast   2:2468/9718.0 (+49)6221 761304
  Germany     RudisBox                  (+49)6253 86677  (+49)6253 972100
  Germany     HIT                       (+49)681 399426  (+49)681 372552
  Germany     Groenland                 (+49)6824 8444
  Germany     Titan                     (+49)6826 800391
  Germany     Outworld                  (+49)6831 52995  (+49)6831 995003
  Germany     ***elOutside              (+49)6838 84739
  Germany     BrainWave   2:246/2006.0  (+49)7071 78729  (+49)7071 971213
  Germany     Amiga Univ. 2:246/1416.0  (+49)7195 920677 (+49)7195 940130
  Germany     Amiga Inside2:2476/539.0  (+49)721 841292
  Germany     Uplink      2:246/2320    (+49)751 96217
  Germany     Fairytale   2:246/2300    (+49)7541 24362  (+49)7541 930232
  Germany     Melting Point 2:2476/825  (+49)7663 50103  (+49)7663 912013
  Germany     Predator    2:2490/1140   (+49)9131 14439
  Germany     LSD                       (+49)9133 9591
  Germany     Turtle      2:2490/1092   (+49)911 3241044 (+49)911 3241055
  Germany     Lizard                    (+49)911 476948
  Germany     Incubus                   (+49)931 781464  (+49)931 7900200
  Australia   Continental               (+61)2949 4256
  Australia   1990 Multi  3:690/758.0   (+61)9370 3333 
@end display

@item
Anonymous UUCP. In Germany, you can access the Aminet files at the
  phone numbers of Brainwave BBS (see above) using the following entry.
  Download the file "Aminet:INFO" for more information.
  anarchy Any SER 38400 ATD<Phone> BBS. ..\c ogin: uanon sword: uanon
  In Switzerland you can use the Alphanet BBS, ~/archives/aminet,
  with the login nuucp.
  
@item
FIDO. If you want to file-request Aminet files, you can do so by 
  requesting the file INFO from 2:246/2006.0. The BBSes which have
  a FIDO node number mentioned above allow file requests.

@item
Mailing lists. If you want to get the list of new uploads mailed every
  week, send a mail with 'SUBSCRIBE aminet-weekly foo@@bar.edu' in the 
  body to listserv@@wunet.wustl.edu or if you want daily updates, just use
  'SUBSCRIBE aminet-daily' instead. Replace foo@@bar.edu with your email
  address, of course. Keep the welcome mail in case you forget how to 
  unsubscribe.

@item
Usenet. A list of recent uploads is posted every week to the newsgroups
  comp.sys.Amiga.misc and de.comp.sys.Amiga.archive.

@item
EZINFO. This is an internet BBS in Switzerland. Here you can download by
  Kermit or ZMODEM, but you need to be verified to become user. Modem dial 
  01 251 20 02, then type 'telnet b050' to connect to EZINFO. Also try
  telnet kometh.ethz.ch and 'call b050' from internet.

@item
CD-ROM. Aminet CD 5 and up are available from Stefan Ossowski, Germany
  (stefano@@tchest.e.eunet.de) or Fred Fish (orders@@amigalib.com). The 
  CD costs DM 25 or US$ 20. You can also buy the complete Aminet as of
  Jan 95 on 4 CDs for DM60 or US$ 40. For further details, have a look at
  @file{docs/misc/CD-Orders.txt}. 

@item
Aminet-on-disk. You can order single Aminet files (3 DM per disk)
  or per-directory subscriptions (2 DM per disk) from Martin Schulze,
  Parkstr. 14,  66806 Ensdorf, Germany.  Phone: +49 (0) 6831 506171,
  email masc@@coli.uni-sb.de . Send 3 DM in stamps or $2 to get an
  index disk with instructions.
  Aminet-on-disk is available on Amiga-Floppy (880k: 3DM, 1.76MB: 5DM),
  SyQuest 88/105/270MB and 128MB-Magneto-Optical. (DM 0.40 per Megabyte
  without media costs)

@end itemize

@node Copyright status and disclaimer, Background information, Accessing Aminet without Internet, aminet
@appendixsec Copyright status and disclaimer

While the files from Aminet are freely distributable, the collection is 
Copyright 1995 Urban D. Mueller. Making a CD-ROM with more than 200M of 
files from our collection or mirroring it on a regular basis requires 
permission from the administrators. That permission will be granted to 
mirrors if they provide an upload facility. If you as an uploader do 
not like this policy, don't upload or have your uploads removed.

The administrators of Aminet give no warranties concerning the files
stored.  Use at your own risk.  Specifically, we cannot guarantee that the
programs are virus-free, uncorrupted, freely distributable or even useful
in any way, although we do our best to ensure the above.

@node Background information, aminet, Copyright status and disclaimer, aminet

@appendixsec History

Aminet was founded by members of ICU (computer science students' club) in
Zurich, Switzerland, using an A3000UX donated by Commodore Switzerland.  In
the beginning it was one FTP site among many, but when the formerly biggest
site (@code{ab20.larc.nasa.gov}) 
shut down, people started adopting Amiga.physik
as the replacement.  In order to share the burden both performance- and
network load wise, two mirror sites were installed.  The new 1GB harddisk
donated by Walnut Creek and the user community allowed us to keep all old
files, while at the same time number of mirror FTP sites increased
constantly to currently 10.  Today, Aminet is the leading Internet source
for Amiga software, giving authors a far-reaching distribution medium and
the user community a place to look for both new and old freely
distributable software.

@appendixsec Contact addresses

Please direct reports about corrupt, illegal or infected files immediately
to aminet@@ftp.wustl.edu (do not rely on someone else doing it!). People
who report a copyrighted file on Aminet get a free CD. For problems local
to one mirror, check the local README's to find out about the administrator 
there.  Some of the the people involved:

@display
Moderators

    Urban D. Mueller   umueller@@wuarchive.wustl.edu
    Matthias Scheler   mscheler@@wuarchive.wustl.edu

  Default contact address:

    aminet@@wuarchive.wustl.edu
@end display

We hope you enjoy the service.

@node    Credits, History, Reporting bugs, Top
@section Credits
Lots of people have contributed to tracker in one way or another.
I may have forgotten some guys. Please forgive me. If you feel you
should be included in this list, or if your e-mail address is out of
date, feel free to send me a note.

@table @strong
@item Oleg Bartunov (megera@@sai.msu.su)
Minor bug report
@item Mike Battersby
Linux, Makefile design
@item Andrew A. Chernov (ache@@astral.msk.su)   
FreeBSD port, various
@item Doug Cook (cook@@sgi.com)  
SG Wiz
@item Liam Corner
original program
@item Yannis Delmas-Rigoutsos (Yannis.Delmas@@ens.fr) 
nit-picking
@item Matthew Donaldson       
bug-report
@item Roger Espel Llima (espel@@ens.fr)      
bug-report
@item Nico Francois (nico.francois@@scala.com)        
permission to use ppdecrunch
@item Looc Grenii (Loic.Grenie@@ens.fr)         
bug-report
@item Rolf Grossmann (grossman@@informatik.tu-muenchen.de)
NextStep port, ui cleanup
@item Markus Gyger (mgyger@@itr.ch)    
hp port
@item Steve Haehnichen (shaehnic@@ucsd.edu)     
first PC port
@item Stephen Hocking (sysseh@@devetir.qld.gov.au)     
Network audio port
@item Joerg-Cyril Hoehle      
bug-report
@item Emil Johansson
Protracker semantics
@item Reinhard Katzmann       
Amiga help
@item Andrzej Kotanski (kotanski@@zeus02.desy.de)  
MM1 port
@item Petri Kuittinen (eye@@niksula.cs.hut.fi)     
SG beta test
@item Bo Kullmar (bk@@kullmar.se)            
bug-report
@item Thomas R. Lawrence      
old port to the macintosh
@item Andrew Leahy (A.Leahy@@st.nepean.uws.edu.au)    
Dec port
@item Kang-Jin Lee (lee@@tengu.in-berlin.de)    
bug-report
@item Jim Leonard (trixter@@trxhome.mwc.com)       
useful discussions
@item Dev Mazumbar (dev@@netcom.com)   
AudioWare port
@item Cyrille Micheneau 
volunteered some help
@item Bruno Monsuez (Bruno.Monsuez@@ens.fr)        
OS/2 port
@item Francis Mouthaud (u220@@esigetel.fr)      
much stuff
@item Darryl Okahata (darrylo@@sr.hp.com)    
hp 3 port
@item Andreas Pahlsson (z94an0pa@@isy.liu.se)      
bug-report
@item Pascal Rullier 
volunteered some help
@item Hannu Savolainen (hannu@@voxware.pp.fi)   
Linux port
@item Frank M. Siegert (frank@@miranda.tue.schwaben.de)  
NextStep port
@item Bjoern Stabell (bjoerns@@staff.cs.uit.no)    
hp port
@item Dave Tiller (dtiller@@cscsun.rmc.edu)     
Solaris/sun incompatibilities
@item Lukas Wunner                                       
bug-report
@end table




@node Concept Index, Top, Amiga implementation, (dir)

@unnumbered Concept Index
@printindex cp
@contents

@bye
