UADE(1)UADE(1)NAME
UADE - Unix Amiga Delitracker Emulator
SYNOPSISuade123 [options] files ...
DESCRIPTIONuade123 plays old amiga music formats by emulating Amiga hardware. It
re-uses Amiga Eagleplayer plugins to play different formats. Eagle‐
player 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 audacious and xmms (1).
Section FILE FORMAT DETECTION explains hardships of recognizing amiga
formats and consequently problems it may cause for the user (and
authors).
Section COMMAND LINE OPTIONS documents command line options for
uade123.
Section 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 CONFIGURATION FILES documents variables which can be changed in
eagleplayer.conf, song.conf and uade.conf to alter default behavior of
uade123 and other frontends. 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 prob‐
lems. 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.
FILE FORMAT DETECTION
Creating file detection heuristics for 200 formats is difficult and
most of those formats are undocumented or otherwise not easily recog‐
nizable. Therefore we have to detect some formats by file name prefixes
and postfixes which can easily cause problems. For example, many dif‐
ferent protracker variants are named with 'mod' prefix and the format
lacks version number inside the data file making it rather hard to rec‐
ognize proper mod variant. Sound output can be buggy with some unrec‐
ognizable 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 con‐
flicts with other plugins. 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 dis‐
abling conflicting XMMS plugins if convenient.
COMMAND LINE OPTIONS-1, --one Play at most one subsong per file.
-@ filename, --list=filename
Play song files listed in the file.
--ao-option=x:y
Set option for libao, where 'x' is an audio driver specific
option and 'y' is a value. Note 'x' may not contain ´:´ charac‐
ter, but 'y' may. This option can be used multiple times to
specify multiple options.
Example for alsa09 plugin: --ao-option=dev:default
--buffer-time=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.
--cygwin
Enable Cygwin workaround mode that converts X:\foo style Windows
names into /cygdrive/X/foo. This can be set by default with
"cygwin" keyword in uade.conf.
-d, --debug
Turn debug mode on. Experts only.
--detect-format-by-content
Set file magic mode. The songs are only detected by file con‐
tents. File name based heuristics (prefixes and postfixes) are
not used.
--disable-timeouts
Disable timeouts. The frontend will never timeout a song.
--enable-timeouts
Enable timeouts. The frontend will normally timeout a song.
-e format
Set output file format (au, raw, wav). Use with -f.
-f filename
Output sound data to filename.
--filter
Enable filter emulation. It is enabled by default but could be
disabled from uade.conf.
--filter=x
Set filter emulation mode to x. x is a500, a1200 or none. A500
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 differ‐
ence 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 :-)
--force-led=x
Force Amiga filter on or off. 0 means "OFF" and 1 means "ON".
--frequency=x
Set output frequency to x Hz. The default is 44,1 kHz. Note that
this option applies to all frontends (including Audacious and
XMMS plugins).
-G, --gain=x
Set volume gain to x. x must be a non-negative value. The
default value is 1,0.
-g, --get-info
Print playername and subsong information to stdout and then
exit. This is useful for recording script.
--headphones
Enable headphones postprocessing effect.
--headphones2
Enable headphones 2 postprocessing effect.
-h, --help
Print command line help.
-i, --ignore
Force eagleplayer to play the song.
-j x, --jump=x
Jump to song position of x seconds.
-k x, --keys=x
Turn action keys on (x = 1) or off (x = 0).
-n, --no-ep-end-detect
Play music ad infinitum by ignoring song end reported by the
eagleplayer. Note that this does not affect timeouts.
--ntsc Set NTSC mode. This can be buggy.
--pal Set PAL mode. This is the default.
-p x, --panning=x
Set panning effect to x. This means mixing left and right chan‐
nel affinely together. n is a value between 0 and 2. 0 is full
stereo, 1 is mono and 2 is inverse stereo.
-P playerfile
Set filename of the eagleplayer.
-r, --recursive
Play directories recursively.
--repeat
Play playlist over and over again.
--resampler=s
Set resampling method to s. It can be default, sinc or none.
See RESAMPLERS section for more information.
-s n, --subsong=n
Choose subsong n.
-S 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.
--scope
Turn on audio register debug mode. Prints Paula hardware regis‐
ter hits on the command line. Support for this option has to be
enabled from the configure script (--with-text-scope).
--set="option1 option2 ..."
Set song.conf options for given songs. uade123 will not play
anything if --set is used. --set makes uade123 remember song
specific options for future playback. For example, this option
is useful for working around bugs in ripped songs (and even uade
;-). Example: Set volume gain to 2 for mod.foo:
uade123 --set="gain=2" mod.foo.
Another example: Force mod.uptim8 to be played as a Startrekker
4 song:
uade123 --set="player=PTK-Prowiz epopt=type:flt4" mod.uptim8
--speed-hack
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.
--stderr
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.
-t x, --timeout=x
Set song time out to x seconds. Default is infinite (-1).
-w x, --subsong-timeout=x
Set subsong timeout to x seconds. -1 means infinite. Default is
512 seconds.
-v, --verbose
Turn verbose mode on. This is useful for debugging strange situ‐
ations.
-x, --ep-option=y
Use eagleplayer option y. For example, to force a module to be
played as a Protracker 1.1b module, execute: uade123-x
type:pt11b mod.foobar
-y x, --silence-timeout=x.
Set silence timeout to x seconds. If x seconds of silence is
detected the (sub)song ends.
-z, --shuffle
Randomize playlist order before playing.
ACTION KEYSuade123 can be controlled interactively on the command line by pressing
specific action keys.
[0-9] Change subsong.
'<' Previous song.
'.' Skip 10 seconds forward.
SPACE, 'b' Next subsong.
'c' Pause.
'f' Toggle filter (takes filter control away from eagle‐
player).
'g' Toggle gain effect.
'h' Print keyboard commands (this list)
'H' Toggle headphones effect.
RETURN, 'n' Next song.
'p' Toggle postprocessing effects.
'P' Toggle panning effect. Default value is 0,7.
'q' Quit.
's' Toggle between shuffle mode and normal play.
'v' Toggle verbose mode.
'x' Restart current subsong.
'z' Previous subsong.
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 com‐
ment lines. Empty lines are ignored.
eagleplayer.conf
Each line in eagleplayer.conf sets eagleplayer specific options. It is
used, among other things, to specify file name extensions to different
formats. It has the format:
playername prefixes=prefix1,prefix2,... [opt1 opt2 ...] [comment]
playername refers to an existing eagleplayer in players/ directory.
prefixes is a list of file prefixes and postfixes that are associated
with this eagleplayer. opt1, opt2 and so forth are options that can be
given to the player.
Valid options for eagleplayer.conf are listed in the song.conf section.
Some example lines for eagleplayer.conf:
custom prefixes=cust
fred prefixes=fred broken_song_end
PTK-Prowiz prefixes=mod,pha,pp10 always_ends
EMSv6 prefixes=emsv6 speed_hack
foobar comment: this format is not detected by a filename
prefix but file content as it should be
song.conf
song.conf is a configuration file for applying work-arounds for songs
that have problems with eagleplayers. Protracker is especially notori‐
ous for having many incompatible versions, and modules do not have ver‐
sion information about the editor which was used to create them.
The file shall have lines of following format:
md5=XXX option1 [option2 ...] [comment: YYY]
Valid options for eagleplayer.conf and song.conf:
a500 Use A500 filter emulation
a1200 Use A1200 filter emulation
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.
broken_song_end Song end reported by the eagleplayer is ignored
detect_format_by_content A song can only be detected by contents,
never by filename prefix or postfix
detect_format_by_name eagleplayer.conf only: the eagleplayer is
detected by name extension only. Furthermore,
any eagleplayer that recognizes the same file by
content is ignored. Do not use this option
without a good reason. Name extensions are
unreliable.
epopt=x Append option x for eagleplayer. Valid options
are listed in section "EAGLEPLAYER OPTIONS".
gain=x Set gain value to x
ignore_player_check Eagleplayer tries to play the song even if it is
not recognized as being in proper format. One
can use this option with bad eagleplayers in
eagleplayer.conf and bad rips in song.conf.
led_off Force LED off
led_on Force LED on
no_ep_end_detect Song end reported by the eagleplayer is ignored
no_filter No filtering (avoid this option, using a1200 is
better)
no_headphones, No headphone effect
no_panning No panning
no_postprocessing No postprocessing effects
ntsc Uses NTSC timing (can be buggy)
one_subsong Play only one subsong per file
pal Uses PAL timing
panning=x Set panning value to x
player=name Set eagleplayer, where name is the directory entry
in players/ dir. This option is not allowed in
eagleplayer.conf.
reject Reject a song (usable for blacklisting). This
option is not allowed in eagleplayer.conf.
resampler=x Set resampling method
silence_timeout=x Set silence timeout
speed_hack Enable speed hack
subsongs=x,y,... Set playable subsong (not implemented yet)
subsong_timeout=x Set subsong timeout
timeout=x Set timeout
vblank Play in vblank mode (works only for protracker
variants)
comment is a tag after which everything is considered just a comment
about the line.
Those options should be self-explanatory ;) A few example lines for
song.conf:
md5=09ad7aed28ec0043e232060546259767 broken_subsongs comment cust.Bub‐
ble_Bobble reports wrong subsong numbers
md5=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx speed_hack comment this is the
only song in format foo that needs speedhack
md5=yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy led_off comment this song just
sucks with filtering
md5=zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz led_on comment turning LED ON
makes this song sound c00l
md5=wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww no_panning subsongs=2,5 comment
only subsongs 2 and 5 sound good
md5=c351076a79033336a0ea1747b6d78783 ntsc comment Play Platoon song in
NTSC mode
uade.conf
uade.conf sets default variables for configuration settings. Each line
may contain at most one command. The configuration file is read from
users home directory ( $HOME/.uade2/uade.conf ) if it exists. If it
does not exist, it is tried from $PREFIX/share/uade2/uade.conf
. Making a copy of the uade.conf into $HOME/.uade2/ can be useful for
users. The same uade.conf controls settings for all frontends. Specifi‐
cally, this includes the XMMS plugin too.
The valid commands are:
action_keys x Set action keys "off" or "on".
ao_option x:y Set libao driver option with key=x and value=y.
See --ao-option=x:y for more information.
Example: ao_option dev:default
buffer_time x Set audio buffer length to x milliseconds.
cygwin Set Cygwin path name workaround mode.
See help for --cygwin option.
detect_format_by_content Only detect files by content. Do not
use file name based heuristics.
disable_timeout A song will never timeout.
enable_timeout A will timeout normally.
filter x Set filter emulation mode to be A500, A1200
or none.
force_led x Force LED "on" or "off"
force_led_off Same as "force_led off"
force_led_on Same as "force_led on"
frequency x Set output frequency to x Hz. The default is
44,1 kHz.
gain x Set gain value to x which is a non-negative
value. The default value is 1,0.
headphones Enable headphone effect.
headphones2 Enable headphone effect 2.
ignore_player_check Force eagleplayers to recognize any given
song.
no_ep_end_detect Disable eagleplayers ability to end song.
See --no-ep-end-detect.
no_filter Same as "filter none".
ntsc Set NTSC mode. (might not work properly)
one_subsong Play only one subsong per file.
pal Set PAL mode.
panning x Set panning value to x inside range [0, 2].
The default is 0.
random_play Set random play or shuffle mode. Used for
uade123 only.
recursive_mode Scan directories recursively. Used for uade123
only.
resampler x Set resampling method to x. It is either
default, sinc or none.
silence_timeout x Set silence timeout value to x seconds.
song_title x Set song title for GUI plugins according to
given specification x. See section SONG TITLE
SPECIFICATION.
speed_hack Enable speed hack mode.
subsong_timeout x Set subsong timeout value to x seconds. -1
implies no timeout.
timeout x Set timeout value to x seconds. -1 implies
no timeout.
verbose Enable verbose mode
SONG TITLE SPECIFICATION
Song title for GUI frontends can be specified by using song_title
option in uade.conf. The default value for specification is %F %X [%P].
Following items are allowed in the specification:
%F - filename %T - songtitle
%P - player or formatname
%A - minimum subsong %B - current subsong
%C - maximum subsong %X - only display subsongs when more
than one
An example of alternative specification that displays the song name
received from the eagleplayer (as opposed to file name):
song_title %T %X [%P]
EAGLEPLAYER OPTIONS
Eagleplayers can be given song specific or general options in song.conf
and eagleplayer.conf. Use epopt=x to set one option. It can be used
many times. You can also issue eagleplayer options from the command
line (so that they are not stored into song.conf) by using -x option:
"uade123 -x type:nt10 mod.foobar" will play mod.foobar as a Noise‐
tracker 1.0 module. With -x option "epopt=" prefix must be dropped.
Valid options for eagleplayers:
PTK-Prowiz epopt=vblank
epopt=type:<tracker>
<tracker> can be one of the following:
st20 (Soundtracker 2.0 - 2.3)
st24 (Soundtracker 2.4)
nt10 (Noisetracker 1.x)
nt20 (Noisetracker 2.x)
m&k. (Noisetracker M&K.)
flt4 (Startrekker 4ch)
pt10c (Protracker 1.0c)
pt11b (Protracker 1.1b - 2.1a)
pt23a (Protracker 2.3)
pt30b (Protracker 3.0b)
example: uade123-x type:nt20 mod.foobar
Infogrames epopt=timer=x
This option is used to set playback speed.
Higher value means slower playback. This is the
CIA timer register value.
x is a hexadecimal value. The default is 1a00.
example: uade123-x timer=24ff gobliins31.dum
SUPPORTED FORMATS
Quite a few. See documentation, eagleplayer.conf and players/ direc‐
tory.
RESAMPLERS
Internally Amigas Paula chip operates at 3,5 MHz, and in theory, it is
possible to generate a 1,75 MHz output signal. However, maximum DMA
based sample rate, which is approximately 28876 Hz, is limited by chip
memory access slots. These frequencies are not well supported with cur‐
rent computer equipment, and synthesizing samples at 3,5 MHz would be
very slow. Regardless, in principle UADE "samples" Paula's output at
3,5 MHz and then immediately resamples it to playback frequency, which
is usually 44,1 kHz or 1/80th of the sample rate of Paula. This output
frequency is configurable, see uade.conf section.
UADE currently supports three resampling methods: none that directly
discards 79 of the 80 samples; default that estimates the true output
value by averaging the last 80 samples together (also known as boxcar
filter). This is the recommended resampler; and sinc that trades cpu
for best high-frequency component removal through low-pass filtering
the audio with a sinc function.
The default resampler is a very good choice because it is pretty accu‐
rate and very fast, but loses some treble and causes some aliasing dis‐
tortion. For high frequencies (above 44,1 kHz), sinc becomes an option
and is probably the best choice.
FILTERS
The Amiga output circuitry contains a fixed low-pass filter on most
models, and a dynamic lowpass filter connected to the power LED (known
as the "LED filter"), which can be toggled on and off. On the Amiga
1000, which was the first Amiga computer, the LED filter was perma‐
nently enabled. In the succeeding models, such as the Amiga 500, the
LED filter was made optional, but another, permanent RC filter circuit
was added on the audio output. Finally, for Amiga 1200, the static fil‐
ter was removed altogether, and only the LED filter remains.
These low-pass filters were most likely added in order to make Amiga's
pulse-based audio sound softer, and to make lower sampling frequencies
useful for audio playback: by removing some of the treble, the hard
edges of a pulse waveform become rounder and the waveform undulates
more smoothly, mimicking many instrument sounds more accurately at
lower sampling rates. The downside of fixed filtering is that the
smoothing occurs with all the higher sampling rates, too.
However, with the introduction of Amiga 1200 and its AGA graphics modes
and spacious chip memory, it became possible to read more than 28876
samples per second from chip memory, and we guess that the fixed low‐
pass filter was removed entirely in favour for accurate treble
response.
The filter emulation is based on hi-fi measurements made on two partic‐
ular Amiga computers, Amiga 500 and Amiga 1200. The Amiga 500 output
path was found to contain a 6 dB/oct lowpass RC filter circuit with
cutoff at 5000 Hz. (Some early Amiga 500 revisions may have had 4500
Hz tuning for this filter.) The LED filter was found to be a 12 dB/oct
Butterworth lowpass filter with cutoff value at approximately 3300 Hz.
The details of the Amiga 1000 filter arrangements are not known,
because nobody has been able to provide any samples.
Accurate digital simulation of analog filters is usually not possible
without some upsampling. When "default" method is used, the samples are
generated at the playback frequency, and the post-processing step that
applies filtering is composed with a series of hand-fitted first-order
IIR filters that together approximate the correct frequency response
for the expected synthesis frequencies of 44,1 kHz or 48 kHz.
The sinc resampling method, in turn, emulates the filters directly at
Paula's 3,5 MHz sampling frequency by folding the filters directly into
the shape of the fundamental synthesis unit, the BLEP. In the sinc
mode, the filters are realised by fitting the digital models for
(slightly modified) butterworth and RC filters with the parameters men‐
tioned above. Therefore sinc can be used on all frequencies above 44.1
kHz without quality loss (or increase, for that matter).
UAERC
You can edit PREFIX/share/uaerc to edit Amiga emulation related vari‐
able.
INCREASING AMIGA MEMORY FOR LARGE MODULE FILES
uaerc can be edited to increase Amiga memory. The variable named chip‐
mem_size (4 by default) controls the memory allocation. The allocated
memory size is determined by formula chipmem_size * 512 KiB, and thus,
there is 2 MiB of memory available for modules by default. This vari‐
able can be set up to 16, which would mean 8 MiB of memory for modules.
FILES
PREFIX/bin/uade123
Player executable.
PREFIX/share/uade2/eagleplayer.conf or $(HOME)/.uade2/eagleplayer.conf
PREFIX/share/uade2/score
MC68000 sound core file
PREFIX/share/uade2/players
MC68000 eagleplayer binaries
PREFIX/share/uade2/song.conf or $(HOME)/.uade2/song.conf
PREFIX/share/uade2/uade.conf or $(HOME)/.uade2/uade.conf
Main configuration file
PREFIX/share/uade2/uaerc
Configuration file for UAE
PREFIX/share/doc/uade-*
UADE documentation
PREFIX/share/man/man1/uade123.1
This man page.
EXAMPLESuade123-zr /path
Play files under /path recursively in random order.
uade123-f output.wav mod.foo
uade123 --set=epopt=type:pt10 mod.foo
Set protracker compatibility to Protracker 1.0c for mod.foo.
After this uade will remember epopt=type:pt10 for mod.foo. See
-x option also.
TIPS AND WORKAROUNDS
1. uade123 users libao to play audio. However, some distributions
have a broken or badly configured libao. This can be
workarounded with a simple shell script that uses ALSA's aplay
for playback. It works for ordinary cases. You can call it
hackuade and issue "hackuade -zr /music/chip" on the command
line. Put hackuade script somewhere in your command $PATH:
#!/bin/sh
uade123-c "$@" |aplay
INFORMATION SOURCES
Public web forum
(primary place for all discussion):
http://board.kohina.net/index.php?c=5
Project home:
http://zakalwe.fi/uade
IRC channel:
#amigaexotic at IRCNet
Project manager:
Heikki Orsila <heikki.orsila@iki.fi>
VERSION CONTROL SERVER
To access the version control you need Git: http://git.or.cz
Execute:
# git clone git://zakalwe.fi/uade uade.git
AUTHORS
UADE 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, resampling and postprocessing effect code).
Heikki Orsila and Michael Doering 2007-02-16 UADE(1)
