---------- MAD PLAY  1.00 (24.10.1998) -----------
---------- Coderight 1992-1998 by Jochen Knaus (knaus@ruf.uni-freiburg.de)
---------- Code by Jochen Knaus, Falcon buserror patch by Fabrice Girardot

This is a little program to play synthetic Atari ST musics, taken from
games or demos.

You can find several hundreds of tunes, informations about composers,
tools like composing programms, charts etc... at the ST Sound Pleasuredome
(http://www.brainbug.ch/stsound).


WHAT ARE ATARI ST SYNTHETIC MUSICS?
-----------------------------------

The original Atari ST machines only have a three voice Yamaha soundchip
in them (STE/TT/Falcon got hardware to play samples, too). This chip is,
to say the truth, not such a hit. It isn't able to produce great sound
like (for example) the C64 SID chip, or -of course- the sample hardware
in the Amiga.
Unlike the sample based tracker format develloped on Amiga, all musicians
needed to write own soundroutines to get the maximum out of the tiny
soundchip. Some of them invented digidrums, that means, single channel
sample sound. Later, even a SID-voice equal was invented.
Good editors arived late (like SID-mon, MusicMon or BlipBlobber), so only
musicians with assembler knowledge got good sound. Early games got really
bad sound, it was to the demoscene to devellop the first high quality (for
this chip) routines and musics. Namely Mad Max aka Jochen Hippel (who did
hundreds of demotunes and later commercial tunes for Thalion, Hewson,
Factor-5, Starbyte and others) pushed the soundchip-usage forwards. Other
composers followed (Big Alec, Scavenger, Lotus, Lap, ENS...). The SID
voice brought possibilities for real cool sounds, it was invented by
Scavenger and Rapido.
In later games, it was good style to use module sound (like on Amiga), but
playing these musics on a normal ST (not STe) needed quite a lot of CPU
time, reducing possibilities for the main programm. So chip-music (and the
blipping, buzzy, blopping sound) included to programms until the ninthees,
the end of the golden years on the ST (normal chiproutines need 5-15%
CPU time, depending on techniques uses (digidrums need more CPU time).

Personally I really LOVE that strange sounds in the musics, I got lot of
tracker-modules, I got an SID-emulator on my PC, I have a good HiFi-
equipement with lotsa CDs, but sometimes, I really love to listen to that
real cool old tunes from the real cool times on the real cool Atari ST.


Why?
-------

It is fuckin easy to run a tunefile using a simple Assemblerprogramm. Also
there are many many other players (as it is so easy) for the Atari ST.

So why doing "MAD PLAYER"? I started doing Mad player 6 years ago on the
Atari ST. I owned a monochrome monitor, and most of the tunes run too fast
on this kind of system, as their playrout rout in the so calles 
"VBL-interrupt", which is 50/60 HZ on RGB and 71HZ on the Atari monochrome
monitor. So I wrote a little player to play the musics on monochrome in the
correct speed. I use some timer routines to do that. Sadly later (for the
ST world) techniques use the timers themself (like digidrums or SID voice),
in this case, VBL needs to be used.
As the Falcon appeared, complications improved. Monitor frequency is free
(range from 50 to about 100Hz with extensions), musics doesn't work anymore,
as Atari removed some hidden registers on this machine, many composers used
in their routines (also some other little things like stack handling 
changed (due to 68030 processor)).

So finally, after six years and many 0.3 and 0.4x versions there is the
version 1!


MAD PLAYER
----------

MAD PLAYER is able to use a soundformat called "SNDH", which contains text
informations about the composer, the tune title, amount of tunes, and - very
useful - some informations about the needed technique.
I guess 95% at the ST Sound Pleasuredome are currently in this format.
For ST and emulator (e.g. Pacifist) users, for each tune there are 
informarmations displayed. Nothing more.
For Falcon users, switching to 50Hz is included, together with some patches
(thanks to Fabrice) for some changes on Falcon. Many ST tunes can be played
now without patching them using Disassembler and Debugger.


USE ON ATARI-ST and EMULATORS
-----------------------------

Your proggy is "MAD_PLAY.TTP".
Connect the file extension ".SND" to this program, and voila, 3.5 kB prg,
you got a SNDH-able player, working even in shells like Mupfel.


USE ON FALCON
-------------

Due to the fact, many monitors doesn't work with 50Hz frequency, and the
SNDH header includes informations about the need of this frequency, 
MAD PLAYER is able to switch automatically to 50Hz on VGA and RGB monitors.
This kicks the OS-screen, but just until you leave the player (so no
multitasking music-enjoy is possible for these tunes).

Three ways:

   1.) MAD_PLAY.TTP   : If you don't like the player to change to 50Hz
                        screenmode if needed. The tunes run a bit faster
                        in this case. Nothing more. Best for all multi-
                        tasking users, as only a TOS-console is used
                        by MAD PLAYER.
   2.) MAD_F030.TTP   : Normal TOS interface for tunes able to run with
                        Timer-A (I think about 70% does work).
                        If VBL is needed (digidrum or SID-voice tunes),
                        the Player switch to 50Hz on all monitors (sadly
                        Multitasking is needed to be kicked here).
                        Normal choice for all Falcon users.
   3.) MADFCOOL.TTP   : Immidiately switches to the High-Colour Player
                        screen, leaving the SNDH informations undisplayed.
                        Best choice for freaks knowing each tune
                        and it's informations yet. Most "demo-spirit".

Gimmick for Falcon users: On 50Hz mode, some high colour volumeters appear,
displaying a nice plasma (not realtime, but colourful indeed), giving a
bit more demo-spirit as the TOS version...

In 50Hz mode, Option "r" (resistant) isn't avaible.


CONTROL
-------

Several tunes feature more than one music in a file. In the SNDH header
the number is stored. So just look how many tunes are in there, and press
the keys to change tune (e.g. three tunes: press "1", "2" or "3" to start
the tunes). At beginning, allways tune one is started. If no SNDH header
is avaible, press all keys, probably the programm could crash then (belongs
to the music you play).

Use key "r" to leave the player, but keep the music played in the background
            (not avaible in Falcon 50Hz mode).
Press "ESC" for forward (does not work on all tunes).


SNDH-Format Description (for coders only...)
--------------------------------------------

If you want to convert tunes to SNDH format, it's quite simply.
The format adds a unique header to single tunefiles, adding start, end and
(if needed) VBL routs for a tune. Also (of course), informations about
the composer and the tune.

The format consists of a header using three branches (init, exit, VBL),
which is standart Mad Max format (tunes using this header are playable
with MAD PLAYER even without SNDH header).

Important: All tunes need to be fully PC-relative, this is just to run
them on any non-ST machine (like Falcon, TT), too, and making exit without
crashing possible.

  init  :  Tune number is delivered in d0.w (first song is 1).
  exit  :  Before leaving the player, this rout is called. Used to
           clear Timers etc.
  VBL   :  Routine's called with 50Hz (most players use). Some players
           have own Timers etc, you can activate them using "MuMo" tag.
           
The header informations can be in the first some hundred bytes of the tune
(probably it is needed to have code after the branches bevore the header
could be).
All information strings are C-strings, mean no fixed length, they need
to be null-determinated.

The header allways start with a single "SNDH" tag, optional tags with
optional informations following.

The tags:	("Str" is nulldeterminated string)

    SNDH        -   Indicates header avaible
    COMM Str    -   Composer name (also "COMP" is possible)
    TITL Str    -   Title of the tune
    RIPP Str    -   Who ripped the tune
    CONV Str    -   Who converted the tune to SNDH
    ##xx        -   Amount of tunes in this file (xx is number (e.g. 02))
    !V50        -   Tune needs to run with 50Hz VBL, VBL isn't emulated
                    via Timer-A (for many digidrum/SID routines needed)
    MuMo        -   MusicMon digidrums (need to be relocated to other
                    adress (player support extra buffer).

An example (things are really easy):

        org     $0
		
        bra     init        ; the three branches at the top of file.
        bra     exit        ; Include two "rts" commands here if not needed
        bra     sound+8

; probably include some code here.

		dc.b    'SNDH'
        dc.b    'COMM','Mad Max (Jochen Hippel)',0
        dc.b    'TITL','Ghostbattle, the tunes...',0
        dc.b    'RIPP','Titan / Animal Mine',0
        dc.b    'CONV','BDCannibal',0
        dc.b    '##04'
        even

; player brings number 1-4 (depend on SNDH information!)
; Remember: probably somebody uses the file in own code and number is
; wrong (or tune needs first tune as 0).
init:      subq.w #1,d0			; Not a must, do what you think so...
           bpl.s  ok
           moveq  #0,d0
ok:        cmp.w  #3,d0
           ble.s  ok2
           moveq  #3,d0
ok2:       bsr    sound+12		; digidrum init, whatever
           bra.s  sound

exit:      ; Clear Timers, whatever
           ; if not needed, jump in header branch directly in tune
           bsr    sound+y
           bra    sound+x

sound:     inline "d:\ghost1.mus"		; Include original tune, PC-relative.


-----------------------------------------------------

Have fun and enjoy the cool sound of the ST games and demos.

Greetings, Jochen aka BDCanniba / AURA (knaus@ruf.uni-freiburg.de)