musix 0.3.3

Music player library for esoteric audio formats (music from C64,Amiga etc)
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
.\" 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" "2007-02-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
audacious.

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 and other frontends.
.BR eagleplayer.conf
is used for eagleplayer plugin specific configurations.
.BR song.conf
is used for song specific configurations which can be used to change
sound effects or avoid problems.
.BR 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.
The filename based heuristics may cause
unrecognized songs in uade123.
In audacious plugin they can cause conflicts with other plugins.

.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\-\-ao\-option\fR=x:y
Set option for libao, where 'x' is an audio driver specific
option 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
.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, \-\-debug\fR
Turn debug mode on. Experts only.
.TP
\fB\-\-detect\-format\-by\-content\fR
Set file magic mode. The songs are only detected by file contents.
File name based heuristics (prefixes and postfixes) are not used.
.TP
\fB\-\-disable\-timeouts\fR
Disable timeouts. The frontend will never timeout a song.
.TP
\fB\-\-enable\-timeouts\fR
Enable timeouts. The frontend will normally timeout a song.
.TP
\fB\-e\fR format
Set output file format (au, raw, wav). 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, 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
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\-\-frequency=\fRx
Set output frequency to x Hz. The default is 44,1 kHz. Note that this option
applies to all frontends (including Audacious plugin).
.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\-\-headphones\fR
Enable headphones postprocessing effect.
.TP
\fB\-\-headphones2\fR
Enable headphones 2 postprocessing effect.
.TP
\fB\-h, \-\-help\fR
Print command line help.
.TP 
\fB\-i,	\-\-ignore\fR
Force eagleplayer to play the song.
.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\-n, \-\-no\-ep\-end-detect\fR
Play music ad infinitum by ignoring song end reported by the eagleplayer.
Note that this does not affect timeouts.
.TP
\fB\-\-ntsc\fR
Set NTSC mode. This can be buggy.
.TP
\fB\-\-pal\fR
Set PAL mode. This is the default.
.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\-\-repeat\fR
Play playlist over and over again.
.TP
\fB\-\-resampler=\fRs
Set resampling method to
.BR s .
It can be
.BR default ,
.BR sinc
or
.BR none .
See RESAMPLERS section for more information.
.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\-\-scope\fR
Turn on audio register debug mode. Prints Paula hardware register hits on
the command line.
\fBSupport for this option has to be enabled from the
configure script (--with-text-scope). \fR
.TP
\fB\-\-set=\fR"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:
.sp 1
uade123 --set="gain=2" mod.foo.
.sp 1
Another example: Force mod.uptim8 to be played as a Startrekker 4 song:
.sp 1
uade123 --set="player=PTK-Prowiz epopt=type:flt4" mod.uptim8
.sp 1
mod.level6h in the "Disposable Hero" requires vblank timing for the
protracker replayer:
.sp 1
uade123 --set='epopt=vblank' mod.level6h

.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\-x, \-\-ep-option=\fRy
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
.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
Randomize playlist order before playing.
.SH ACTION KEYS
uade123 can be controlled interactively on the command line by pressing
specific action keys.
.br
 [0-9]         Change subsong.
.br
 '<'           Previous song.
.br
 '.'           Skip 10 seconds forward.
.br
 SPACE, 'b'    Next subsong.
.br
 'c'           Pause.
.br
 'f'           Toggle filter (takes filter control away from eagleplayer).
.br
 'g'           Toggle gain effect.
.br
 'h'           Print keyboard commands (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
sets eagleplayer specific options. It is used, among other things,
to specify file name extensions to different formats. It 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 for eagleplayer.conf are listed in the
.BR song.conf
section.
.sp 1
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.
One can program song.conf rules for songs by using the --set option
in uade123. For example, forcing a module into vblank timing, do:
"uade123 --set='epopt=vblank' mod.level6h"

The file shall have lines of following format:
.sp 1
md5=XXX option1 [option2 ...] [comment: YYY]
.sp 1
Valid options for eagleplayer.conf and song.conf:
.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
broken_song_end      Song end reported by the eagleplayer is ignored
.br
detect_format_by_content  A song can only be detected by contents,
                     never by filename prefix or postfix
.br
epopt=x              Append option x for eagleplayer. Valid options
                     are listed in section "EAGLEPLAYER OPTIONS".
.br
gain=x               Set gain value to x
.br
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.
.br
led_off              Force LED off
.br
led_on               Force LED on
.br
no_ep_end_detect     Song end reported by the eagleplayer is ignored
.br
no_filter            No filtering (avoid this option, using a1200 is
                     better)
.br
no_headphones,       No headphone effect
.br
no_panning           No panning
.br
no_postprocessing    No postprocessing effects
.br
ntsc                 Uses NTSC timing (can be buggy)
.br
one_subsong          Play only one subsong per file
.br
pal                  Uses PAL timing
.br
panning=x            Set panning value to x
.br
player=name          Set eagleplayer, where name is the directory entry
                     in players/ dir. This option is not allowed in
                     eagleplayer.conf.
.br
reject               Reject a song (usable for blacklisting). This
                     option is not allowed in eagleplayer.conf.
.br
resampler=x          Set resampling method
.br
silence_timeout=x    Set silence timeout
.br
speed_hack           Enable speed hack
.br
subsongs=x,y,...     Set playable subsong (not implemented yet)
.br
subsong_timeout=x    Set subsong timeout
.br
timeout=x            Set timeout
.sp 1
.BR comment
is a tag after which everything is considered just a comment
about the line.
.sp 1
Those options should be self-explanatory ;) A few example lines for song.conf:
.sp 1
md5=09ad7aed28ec0043e232060546259767 broken_subsongs comment cust.Bubble_Bobble reports wrong subsong numbers                        
.sp 1
md5=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx speed_hack 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
.sp 1
md5=c351076a79033336a0ea1747b6d78783 ntsc comment Play Platoon song in NTSC mode
.SH uade.conf
.BR 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 (
.BR $HOME/.uade/uade.conf
) if it exists. If it does not
exist, it is tried from
.BR $PREFIX/share/uade/uade.conf
 . Making a copy of the
uade.conf into $HOME/.uade/ can be useful for users. The same uade.conf
controls settings for all frontends. Specifically, this includes the audacious
plugin too.

The valid commands are:
.sp 1
    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
.br
    buffer_time x      Set audio buffer length to x milliseconds.
.br
    cygwin             Set Cygwin path name workaround mode.
                       See help for --cygwin option.
.br
    detect_format_by_content  Only detect files by content. Do not
                       use file name based heuristics.
.br
    disable_timeout    A song will never timeout.
.br
    enable_timeout     A will timeout normally.
.br
    filter x           Set filter emulation mode to be A500, A1200
                       or none.
.br
    force_led x        Force LED "on" or "off"
.br
    force_led_off      Same as "force_led off"
.br
    force_led_on       Same as "force_led on"
.br
    frequency x        Set output frequency to x Hz. The default is
                       44,1 kHz.
.br
    gain x             Set gain value to x which is a non-negative
                       value. The default value is 1,0.
.br
    headphones         Enable headphone effect.
.br
    headphones2        Enable headphone effect 2.
.br
    ignore_player_check    Force eagleplayers to recognize any given
                           song.
.br
    no_ep_end_detect   Disable eagleplayers ability to end song.
                       See --no-ep-end-detect.
.br
    no_filter          Same as "filter none".
.br
    ntsc               Set NTSC mode. (might not work properly)
.br
    one_subsong        Play only one subsong per file.
.br
    pal                Set PAL mode.
.br
    panning x          Set panning value to x inside range [0, 2].
                       The default is 0.
.br
    random_play        Set random play or shuffle mode. Used for
                       uade123 only.
.br
    recursive_mode     Scan directories recursively. Used for uade123
                       only.
.br
    resampler x        Set resampling method to x. It is either
                       default, sinc or none.
.br
    silence_timeout x  Set silence timeout value to x seconds.
.br
    speed_hack         Enable speed hack mode.
.br
    subsong_timeout x  Set subsong timeout value to x seconds. -1
                       implies no timeout.
.br
    timeout x          Set timeout value to x seconds. -1 implies
                       no timeout.
.br
    verbose            Enable verbose mode
.br

.SH "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 Noisetracker
1.0 module. With -x option "epopt=" prefix must be dropped.
.sp 1
Valid options for eagleplayers:
.sp 1
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)
.sp 1
                    example: uade123 -x type:nt20 mod.foobar
.sp 1
Infogrames          epopt=timer=x
.br
                        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.
.sp 1
                        example: uade123 -x timer=24ff gobliins31.dum
.br
.SH "SUPPORTED FORMATS"
Quite a few. See documentation, eagleplayer.conf and players/ directory.
.SH "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 current
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
.BR uade.conf
section.
.sp 1
UADE currently supports three resampling methods:
.BR none
that directly discards 79 of the 80 samples;
.BR 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
.BR sinc
that trades cpu for best high-frequency component removal through
low-pass filtering the audio with a sinc function.
.sp 1
The default resampler is a very good choice because it is pretty accurate
and very fast, but loses some treble and causes some aliasing distortion.
For high frequencies (above 44,1 kHz), sinc becomes an option and is probably
the best choice.
.SH "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
permanently 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 filter was
removed altogether, and only the LED filter remains.
.sp 1
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.
.sp 1
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 lowpass
filter was removed entirely in favour for accurate treble response.
.sp 1
The filter emulation is based on hi-fi measurements made on two particular
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.
.sp 1
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.
.sp 1
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
mentioned above. Therefore sinc can be used on all frequencies above
44.1 kHz without quality loss (or increase, for that matter).
.SH "UAERC"
You can edit PREFIX/share/uaerc to edit Amiga emulation related
variable.
.sp 1
.B INCREASING AMIGA MEMORY FOR LARGE MODULE FILES
.sp 1
uaerc can be edited to increase Amiga memory. The
variable named chipmem_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 variable can be set up to 16, which would
mean 8 MiB of memory for modules.
.SH "FILES"
.TP 
PREFIX/bin/uade123
Player executable.
.TP
PREFIX/share/uade/eagleplayer.conf or $(HOME)/.uade/eagleplayer.conf
.TP 
PREFIX/share/uade/score
MC68000 sound core file
.TP 
PREFIX/share/uade/players
MC68000 eagleplayer binaries
.TP
PREFIX/share/uade/song.conf or $(HOME)/.uade/song.conf
.TP
PREFIX/share/uade/uade.conf or $(HOME)/.uade/uade.conf
Main configuration file
.TP
PREFIX/share/uade/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
.TP
\fBuade123 \--set=epopt=type:pt10 mod.foo\fR
.br
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.

.SH "TIPS AND WORKAROUNDS"
.TP
\fB1.\fR
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
\fBaplay\fR
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

.SH "INFORMATION SOURCES"
.TP
.B Public web forum
(primary place for all discussion):
.br
http://board.kohina.net/index.php?c=6
.TP
.B Project home:
.br
http://zakalwe.fi/uade
.TP
.B IRC channel:
.br
#amigaexotic at IRCNet
.TP
.B Project manager:
.br
Heikki Orsila <heikki.orsila@iki.fi>
.SH "VERSION CONTROL SERVER"
To access the version control you need Git: http://git.or.cz
.br
Execute:
.br
# git clone git://zakalwe.fi/uade uade.git
.SH "AUTHORS"
\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, resampling and postprocessing effect code).