Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
UADE(1)								       UADE(1)

       UADE - Unix Amiga Delitracker Emulator

       uade123 [options] files ...

       uade123	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  au-

       Section	 COMMAND LINE OPTIONS	documents  command  line  options  for

       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  al-
       tering 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.

       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.

       -1, --one Play at most one subsong per file.

       -@ filename, --list=filename
	      Play song	files listed in	the file.

	      Set option for libao, where 'x' is an audio driver specific  op-
	      tion and 'y' is a	value. Note 'x'	may not	contain	':' character,
	      but 'y' may. This	option can be used multiple times  to  specify
	      multiple options.

	      Example for alsa09 plugin: --ao-option=dev:default

	      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.

	      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.

	      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.	The frontend will never	timeout	a song.

	      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.

	      Enable  filter  emulation. It is enabled by default but could be
	      disabled from uade.conf.

	      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 Amiga filter on or off. 0 means "OFF" and 1	means "ON".

	      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  de-
	      fault value is 1,0.

       -g, --get-info
	      Print  playername	 and  subsong  information  to stdout and then
	      exit. This is useful for recording script.

	      Enable headphones	postprocessing effect.

	      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 ea-
	      gleplayer.  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.

	      Play playlist over and over again.

	      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 re-
	      leases may help revealing	the problem source.

	      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

	      uade123 --set="gain=2"

	      Another example: Force mod.uptim8	to be played as	a  Startrekker
	      4	song:

	      uade123 --set="player=PTK-Prowiz epopt=type:flt4"	mod.uptim8

	      Enable speedhack.	Emulate	all instructions to be executed	in one
	      m68k cycle. Some players,	such as	EMS v6,	take too many m68k cy-
	      cles 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.

	      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-

       -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 de-
	      tected the (sub)song ends.

       -z, --shuffle
	      Randomize	playlist order before playing.

       uade123 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-
	'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.

       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.

       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  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
       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
       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
       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

       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

       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  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
	   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
	   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
	   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 for GUI frontends can	be specified by	using  song_title  op-
       tion  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 re-
       ceived from the eagleplayer (as opposed to file name):

	   song_title %T %X [%P]

       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
				      <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

       Quite a few. See	documentation, eagleplayer.conf	 and  players/	direc-

       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.

       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 re-

       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,  be-
       cause 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).

       You can edit PREFIX/share/uaerc to edit Amiga emulation	related	 vari-


       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.

	      Player executable.

       PREFIX/share/uade2/eagleplayer.conf or $(HOME)/.uade2/eagleplayer.conf

	      MC68000 sound core file

	      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

	      Configuration file for UAE

	      UADE documentation

	      This man page.

       uade123 -zr /path
	      Play files under /path recursively in random order.

       uade123 -f output.wav

       uade123 --set=epopt=type:pt10
	      Set  protracker  compatibility  to  Protracker 1.0c for
	      After this uade will remember epopt=type:pt10 for   See
	      -x option	also.

       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:


	      uade123 -c "$@" |aplay

       Public web forum
	      (primary place for all discussion):

       Project home:

       IRC channel:
	      #amigaexotic at IRCNet

       Project manager:
	      Heikki Orsila <>

       To access the version control you need Git:
       # git clone git:// uade.git

       UADE project  was  started  by  Heikki  Orsila  <>.
       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 <> (Amiga filter em-
       ulation,	resampling and postprocessing effect code).

Heikki Orsila and Michael Doering 2007-02-16			       UADE(1)


Want to link to this manual page? Use this URL:

home | help