.\" Hey, EMACS: -*- nroff -*-
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.\" Please adjust this date whenever revising the manpage.
.\" 
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.TH "UADE" "1" "2005-11-16" "Heikki Orsila and Michael Doering" ""
.SH "NAME"
UADE \- Unix Amiga Delitracker Emulator
.SH "SYNOPSIS"
.B uade123
[\fIoptions\fR] \fIfiles\fR ...
.SH "DESCRIPTION"
.BR uade123
plays old amiga music formats by emulating Amiga hardware. It
re-uses Amiga Eagleplayer plugins to play different formats. Eagleplayer
plugins require an implementation of the Eagleplayer API and AmigaOS APIs
to run on. Therefore Eagleplayer API and parts of AmigaOS have been
implemented in uade.

uade123 is a command line player that can be used to play Amiga songs. It's
options and behavior are documented here. There is also a plugin for the
.BR xmms
(1).

Section
.BR FILE\ FORMAT\ DETECTION
explains hardships of recognizing amiga formats and consequently problems it
may cause for the user (and authors).

Section
.BR COMMAND\ LINE\ OPTIONS
documents command line options for uade123.

Section
.BR ACTION\ KEYS
documents action keys which are used to issue run-time commands to control
playback. These commands include switching subsong, skipping to next song,
skipping fast forward, pausing and altering post-processing effects.

Section
.BR CONFIGURATION\ FILES
documents variables which can be changed in
.BR eagleplayer.conf ,
.BR song.conf
and
.BR uade.conf
to alter default behavior of uade123.
eagleplayer.conf is used for eagleplayer plugin specific configurations.
song.conf is used for song specific configurations which can be used to change
sound effects or avoid problems.
uade.conf is the main configuration file that can be used to set defaults for
variables. Command line options will always override uade.conf options.

.SH "FILE FORMAT DETECTION"
Creating file detection heuristics for 200 formats is difficult and most of
those formats are undocumented or otherwise not easily recognizable. Therefore
we have to detect some formats by file name prefixes and postfixes which
can easily cause problems. For example, many different protracker variants
are named with 'mod' prefix and the format lacks version number inside
the data file making it rather hard to recognize proper mod variant. 
Sound output can be buggy with some unrecognizable mod variants. When file
format can not be deduced based on file contents, a heuristics based on the
file name must be used. This may sound strange, but many of the
m68k machine language player plugins are black boxes which have no reliable
mechanism to validate whether a given file belongs to them or not.
In uade123 the filename based heuristics may cause
unrecognized songs and in XMMS it can cause conflicts with other plugins.
.BR contrib/uadexmmsadd
script can be used to add uade:// prefixed playlist entries into XMMS to
avoid conflicts with some of the existing mod plugins for XMMS. However,
we recommend disabling conflicting XMMS plugins if convenient.

.SH "COMMAND LINE OPTIONS"

\fB\-1, \-\-one\fR
Play at most one subsong per file.
.TP
\fB\-@\fR filename\fB, \-\-list=\fRfilename
Play song files listed in the file.
.TP
\fB\-\-buffer\-time\fR=x
Set audio buffer length to x milliseconds. It can be used to avoid audio
underruns on some systems. The default value of this setting is provided
by the libao. Notice that libao support for ALSA has a bug
in versions 0.8.6 and earlier that buffer_time must actually be given in
microseconds rather than milliseconds.
.TP
\fB\-d\fR
Turn debug mode on. Experts only.
.TP
\fB\-e\fR format
Set output file format. Use with
.BR -f .
.TP
\fB\-f\fR filename
Output sound data to filename.
.TP
\fB\-\-filter\fR
Enable filter emulation. It is enabled by default but could be disabled from
uade.conf.
.TP
\fB\-\-filter=\fRx
Set filter emulation mode to
.BR x .
x is a500, a500e, a1200, a1200e or none. A500E is
the default. 'none' means disabling the filter. Please note that A500 and A1200
are audibly different on every
song even if a song doesn't use filtering. Surprisingly, the biggest
difference between A500 and A1200 is filter behavior when LED is off (i.e.
song doesn't use filtering). When LED is off, A1200 does very little filtering
but A500 does some filtering that can be easily heard. Please try switching
between A500 and A1200 modes. You should get same results with real
Amigas too :-)
.TP
\fB\-\-force\-led=\fRx
Force Amiga filter on or off. 0 means "OFF" and 1 means "ON".
.TP
\fB\-G, \-\-gain=\fRx
Set volume gain to
.BR x .
x must be a non-negative value. The default value is 1.0.
.TP
\fB\-g, \-\-get\-info\fR
Print playername and subsong information to stdout and then exit. This is
useful for recording script.
.TP
\fB\-h, \-\-help\fR
Print command line help.
.TP
\fB\-\-headphone\fR
Enable headphone postprocessing effect.
.TP 
\fB\-i,	\-\-ignore\fR
Force eagleplayer to play the song.
.TP
\fB\-\-interpolator=\fRs
Set interpolator to
.BR s .
It can be
.BR default
(anti),
.BR anti
or
.BR none .
.TP
\fB\-j\fR x\fB, \-\-jump=\fRx
Jump to song position of x seconds.
.TP
\fB\-k\fR x\fB, \-\-keys=\fRx
Turn action keys on (x = 1) or off (x = 0).
.TP
\fB\-m\fR filename
Set module filename.
.TP
\fB\-n, \-\-no-filter\fR
Disable filter emulation.
.TP 
\fB\-\-no\-song\-end\fR
Play music ad infinitum by ignoring song end.
.TP 
\fB\-p\fR x, \-\-panning=\fRx
Set panning effect to x. This means mixing left and right channel affinely
together. n is a value between 0 and 2. 0 is full stereo, 1 is mono and
2 is inverse stereo.
.TP 
\fB\-P\fR playerfile
Set filename of the eagleplayer.
.TP 
\fB\-r, \-\-recursive\fR
Play directories recursively.
.TP 
\fB\-s\fR n\fB, \-\-subsong=\fRn
Choose subsong n.
.TP 
\fB\-S\fR scorefile
Set filename of sound core. Experts only. Useful for debugging sound core
related problems. Picking score file from earlier releases may help revealing
the problem source.
.TP 
\fB\-\-speed\-hack\fR
Enable speedhack. Emulate all instructions to be executed
in one m68k cycle. Some players, such as EMS v6, take too
many m68k cycles to be real\-time. This option gives them
enough m68k cycles. Notice that you do _not_ need to use this
switch with EMS v6 or Octamed, because it is automatically enabled for
those formats. A replayer usually knows to ask for speedhack.
.TP
\fB\-\-stderr\fR
Print all messages on stderr. This is useful if one uses -f /dev/stdout as
a trick to pipe sample data on the command line.
.TP 
\fB\-t\fR x\fB, \-\-timeout=\fRx
Set song time out to x seconds. Default is infinite (-1).
.TP 
\fB\-w\fR x\fB, \-\-subsong\-timeout=\fRx
Set subsong timeout to x seconds. -1 means infinite. Default is 512 seconds.
.TP
\fB\-v, \-\-verbose\fR
Turn verbose mode on. This is useful for debugging strange situations.
.TP 
\fB\-y\fR x\fB, \-\-silence\-timeout=\fRx.
Set silence timeout to x seconds. If x seconds of silence is detected the
(sub)song ends.
.TP 
\fB\-z, \-\-shuffle\fR
Turn shuffle mode on. Plays songs in random order.
.SH ACTION KEYS
uade123 can be controlled interactively on the command line by pressing
specific action keys.
.br
 [0-9]         Change subsong.
.br
 '.'           Skip 10 seconds forward.
.br
 SPACE, 'b'    Go to next subsong.
.br
 'c'           Pause.
.br
 'f'           Toggle filter (takes filter control away from eagleplayer).
.br
 'g'           Toggle gain effect.
.br
 'h'           Print this list.
.br
 'H'           Toggle headphones effect.
.br
 RETURN, 'n'   Next song.
.br
 'p'           Toggle postprocessing effects.
.br
 'P'           Toggle panning effect. Default value is 0.7.
.br
 'q'           Quit.
.br
 's'           Toggle between shuffle mode and normal play.
.br
 'v'           Toggle verbose mode.
.br
 'x'           Restart current subsong.
.br
 'z'           Previous subsong.
.SH CONFIGURATION FILES
All configuration files are in a line based format. This means that line breaks
(\\n) must be used properly. Lines beginning with # are comment lines. Empty
lines are ignored.
.SH eagleplayer.conf
Each line in
.BR eagleplayer.conf
has the format:
.sp 1
playername prefixes=prefix1,prefix2,... [opt1 opt2 ...] [comment]
.sp 1
.BR playername
refers to an existing eagleplayer in players/ directory.
.BR prefixes
is a list of file prefixes and postfixes that are associated with
this eagleplayer.
.BR opt1 ,
.BR opt2
and so forth are options that can be given to the player. Valid options are:
.sp 1
a500                 Use A500 filter emulation.
.br
a1200                Use A1200 filter emulation.
.br
always_ends          A song will always end. This means that song end
                     detection code is perfect so timeouts in uade.conf
                     can be ignored. However, timeouts given from
                     command line will override this setting.
.br
content_detection    A song can only be detected by contents, never
                     by filename prefix or postfix.
.br
speed_hack           Enable speed hack.

.BR comment
is a tag after which everything is considered just a comment
about the line.

Some example lines for eagleplayer.conf:
.sp 1
custom          prefixes=cust
.br
fred            prefixes=fred           broken_song_end
.br
PTK-Prowiz      prefixes=mod,pha,pp10   always_ends
.br
EMSv6           prefixes=emsv6          speed_hack
.br
foobar          comment: this format is not detected by a filename
                prefix but file content as it should be
.SH song.conf
.BR song.conf
is a configuration file for applying work-arounds for songs that
have problems with eagleplayers. Protracker is especially notorious
for having many incompatible versions, and modules do not have version
information about the editor which was used to create them.

The file shall have lines of following format:
.sp 1
md5=XXX option1 [option2 ...] [comment: YYY]
.sp 1
Valid options are:
.sp 1
	\\broken_subsongs
.br
	\\led_off
.br
	\\led_on
.br
	\\no_headphones,
.br
	\\no_panning
.br
	\\no_postprocessing
.br
	\\ntsc
.br
	\\speedhack
.br
	\\subsongs=x,y,...
.br
	\\vblank
.sp 1
Those options should be self-explanatory ;) A few example lines:
.sp 1
md5=09ad7aed28ec0043e232060546259767 \\broken_subsongs \\comment cust.Bubble_Bobble reports wrong subsong numbers                        
.sp 1
md5=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \\speedhack \\comment this is the only song in format foo that needs speedhack    
.sp 1
md5=yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy \\led_off \\comment this song just sucks with filtering                  
.sp 1
md5=zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz \\led_on \\comment turning LED ON makes this song sound c00l       
.sp 1
md5=wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww \\no_panning subsongs=2,5 \\comment only subsongs 2 and 5 sound good
.SH uade.conf
.BR uade.conf
sets default variables for configuration settings. Each line
may contain at most one command. The valid commands are:
.sp 1
    filter x           Set filter emulation mode to be A500, A500E,
                       A1200 or A1200E.
.br
    headphone          Enable headphone effect.
.br
    panning x          Set panning value to x inside range [0, 2].
                       The default is 0.
.br
    gain x             Set gain value to x which is a non-negative
                       value. The default value is 1.0.
.br
    interpolator x     Set interpolator to x which is either default
                       (anti), anti or none.
.br
    subsong_timeout x  Set subsong timeout value to x seconds.
.br
    action_keys x      Set action keys "off" or "on".
.br
    no_filter          Turn filter emulation off.
.br
    force_led_off      Forces LED to "off" state.
.br
    ignore_player_check    Force eagleplayers to recognize any given
                           song.
.br
    random_play        Set random play or shuffle mode. Used for
                       uade123 only.
.br
    recursive_mode     Scan directories recursively. Used for uade123
                       only.
.br
    silence_timeout x  Set silence timeout value to x seconds.
.br
    timeout x          Set timeout value to x seconds.
.br
    buffer_time x      Set audio buffer length to x milliseconds.
.SH "SUPPORTED FORMATS"
Quite a few. See documentation, eagleplayer.conf and players/ directory.
.SH "FILES"
.TP 
PREFIX/bin/uade123
Player executable.
.TP
PREFIX/share/uade2/eagleplayer.conf or $(HOME)/.uade2/eagleplayer.conf
.TP 
PREFIX/share/uade2/score
MC68000 sound core file
.TP 
PREFIX/share/uade2/players
MC68000 eagleplayer binaries
.TP
PREFIX/share/uade2/song.conf or $(HOME)/.uade2/song.conf
.TP
PREFIX/share/uade2/uade.conf or $(HOME)/.uade2/uade.conf
.TP
PREFIX/share/uade2/uaerc
Configuration file for UAE.
.TP
PREFIX/share/doc/uade-*
UADE documentation
.TP
PREFIX/share/man/man1/uade123.1
This man page.
.SH "EXAMPLES"
.TP 
\fBuade123 \-zr /path\fR
.br 
Play files under /path recursively in random order.
.TP
\fBuade123 \-f output.wav mod.foo\fR
.br
Synthesize mod.foo into a wav file.
.SH "AUTHOR"
\fBUADE\fP project was started by Heikki Orsila <heikki.orsila@iki.fi>.
There have been many other contributors. Most notable contributors
are Michael 'mld' Doering (for almost anything),
Harry 'Piru' Sintonen (MorphOS port) and Antti S. Lankila <alankila@bel.fi>
(Amiga filter emulation). See
.B http://zakalwe.fi/uade
.br
for more information.
