SNDH

The format has the same idea as the AY-files for the ZX Spectrum. SNDH is an ICE-compressed or non-compressed data block consisting of entry points, tags and a native player with data for an Atari ST or Atari STe computer.

The format is intended for use on the Atari ST itself, but it is also supported on other platforms through emulation (it is enough to emulate the MC68000 processor, sound systems, VBL interrupts and MFP timers, some system variables and several Atari ST/STe TOS traps).

The main difference from the AY-format is the player and its data must be relocatable. It is quite easy to do this on the MC68000 processor, because for commands working with absolute addresses, there are analogues for working with relative ones.

The format is well documented and evolving. The latest revision can be found in the file sndhv21.txt, its text is given at the end.

The main problem of the format is not new, it allows the music duration fields absence, and if they are present, the accuracy is not great (just 1 second). For known files, both problems are solved in Ay_Emul using the SNDH music duration database from Benjamin Gerard (described in detail at the section "What is Ay_Emul"), there the duration is stored with the VBL interrupt accuracy.

Support was not added immediately into Ay_Emul, since for many years there was an attempt to deal with the format within my Micro ST project. Nevertheless, it was not possible to achieve the operability of all 100% of the SNDH files available on Internet. However, almost everyone is now playing in Ay_Emul, despite a number of simplifications in the Atari ST emulation itself.

The main reason that I was interested in the SNDH format is the presence of the YM2149F sound chip on Atari ST/STe (as once on my Pentagon 128K). And the main reason for the simplified approach in Atari ST/STe emulation is my lack of both the computer itself and experience with it and the MC68000 processor. This was also influenced by the AY format, which requires very simplified ZX Spectrum 48K emulation to play, and the Micro ST project developed in an attempt to repeat the same approach in the SNDH player.

-------Begin of sndhv21.txt----------

; SNDH file structure, Revision 2.10

; Original SNDH Format devised by Jochen Knaus
; SNDH V1.1 Updated/Created by Anders Eriksson and Odd Skancke 
; SNDH V2.0 by Phil Graham
; SNDH V2.1 by Phil Graham

; This document was originally created by Anders Eriksson, updated and 
; adapted with SNDH v2 structures by Phil Graham.

; October, 2012
; 
;
; All values are in MOTOROLA BIG ENDIAN format


;---------------------------------------------------------------------------
;Offset         Size    Function                    Example
;---------------------------------------------------------------------------
;0              4       INIT music driver           bra.w  init_music_driver
;                       (subtune number in d0.w)
;4              4       EXIT music driver           bra.w  exit_music_driver
;8              4       music driver PLAY           bra.w  vbl_play
;12             4       SNDH head                   dc.b   'SNDH'



;---------------------------------------------------------------------------
;Beneath follows the different TAGS that can (should) be used.
;The order of the TAGS is not important.
;---------------------------------------------------------------------------

;---------------------------------------------------------------------------
; TAG   Description      Example                           Termination
;---------------------------------------------------------------------------
; TITL  Title of Song    dc.b 'TITL','Led Storm',0         0 (Null)
; COMM  Composer Name    dc.b 'COMM','Tim Follin',0        0 (Null)
; RIPP  Ripper Name      dc.b 'RIPP','Me the hacker',0     0 (Null)
; CONV  Converter Name   dc.b 'CONV','Me the converter',0  0 (Null)
; ##??  Sub Tunes        dc.b '##04',0                     0 (Null)
; TA???  Timer A         dc.b 'TA50',0                     0 (Null)
; TB???  Timer B         dc.b 'TB60',0                     0 (Null)
; TC???  Timer C         dc.b 'TC50',0                     0 (Null)
; TD???  Timer D         dc.b 'TD100',0                    0 (Null)
; !V??  VBL              dc.b '!V50',0                     0 (Null)
; YEAR  Year of release  dc.b '1996',0                     0 (Null) SNHDv2
; #!??  Default Sub tune dc.b '#!02',0                     0 (Null) SNDHv21
; #!SN  Sub tune names	 dc.w x1,x2,x3,x4                  None
;                        dc.b "Subtune Name 1",0	   0 (Null) SNDHv21
;                        dc.b "Subtune Name 2",0	   0 (Null) SNDHv21
;                        dc.b "Subtune Name 3",0	   0 (Null) SNDHv21
;                        dc.b "Subtune Name 4",0	   0 (Null) SNDHv21
; TIME  (sub) tune time  dc.b 'TIME'                       None     SNDHv2
;       (in seconds)     dc.w x1,x2,x3,x4      
; HDNS  End of Header    dc.b 'HDNS'                       None     SNDHv2

;---------------------------------------------------------------------------
;Calling method and speed
;---------------------------------------------------------------------------
;This a very important part to do correctly.
;Here you specify what hardware interrupt to use for calling the music 
;driver.
;
;These options are available;
;dc.b  '!Vnn'       VBL (nn=frequency)
;dc.b  'TAnnn',0    Timer A (nnn=frequency)
;dc.b  'TBnnn',0    Timer B (nnn=frequency)
;dc.b  'TCnnn',0    Timer C (nnn=frequency)
;dc.b  'TDnnn',0    Timer D (nnn=frequency)
;
;VBL           - Is NOT recommended for use. There is no change made to the 
;                VBL frequency so it will play at the current VBL speed.
;
;Timer A       - Is only recommended if Timer C is not accurate enough. Use 
;                with caution, many songs are using Timer A for special
;                effects.
;
;Timer B       - Is only recommended if Timer C is not accurate enough. Use
;                with caution, many songs are using Timer B for special
;                effects.
;
;Timer C       - The default timer if nothing is specified. Default speed
;                is 50Hz. Use Timer C playback wherever possible. It hooks
;                up to the OS 200Hz Timer C interrupt and leaves all other
;                interrupts free for special effects.
;
;                For songs with a replay speed uneven of 200Hz, SND Player
;                uses a smart routine to correct for the wrong speed. The
;                result is usually very good. If the result isn't good 
;                enough,then consider another Timer, but be careful with
;                Timer collisions!
;
;Timer D       - Is only recommended if Timer C is not accurate enough. 
;                Use with caution, many songs are using Timer D for 
;                special effects.

;---------------------------------------------------------------------------
; Default Tune Tag (!#??)
;---------------------------------------------------------------------------
; The !# Tag is followed by a two character ascii value signifying the
; default sub-tune to be played. If this tag is null then a sub-tune of
; 1 is assumed. 
;---------------------------------------------------------------------------

;---------------------------------------------------------------------------
; Sub Tune Names (!#SN)
;---------------------------------------------------------------------------
; The !#SN Tag is followed by a table of word offsets pointing to the ascii
; text of sub tune names. The base offset is the actaul !#SN tag. See 
; example header below. 
;---------------------------------------------------------------------------


;---------------------------------------------------------------------------
; TIME Tag
;---------------------------------------------------------------------------
; The TIME tag is followed by 'x' short words ('x' being the number of 
; tunes). Each word contains the length of each sub tune in seconds. If the
; word is null then it is assumed that the tune endlessly loops.
;---------------------------------------------------------------------------


;---------------------------------------------------------------------------
; HDNS Tag
;---------------------------------------------------------------------------
; The HDNS signifies the end of the SNDH header and the start of the actual 
; music data. This tag must be on an even boundary.
;---------------------------------------------------------------------------


;---------------------------------------------------------------------------
;Example of a complete SNDH header/file
;---------------------------------------------------------------------------
;
;      section text
;
;      bra.w  sndh_init
;      bra.w  sndh_exit
;      bra.w  sndh_vbl
;
;      dc.b   'SNDH'
;      dc.b   'TITL','Mindbomb - Digi Synth',0
;      dc.b   'COMM','Spaz',0
;      dc.b   'RIPP','Grazey/PHF',0
;      dc.b   'CONV','Quartet-2-SNDH (c) PHF',0
;      dc.b   '##06',0
;      dc.b   'TC200',0
;      dc.b   '!#01',0
;      even
;.subt dc.b   '!#SN'             ; Subtune names
;      dc.w   .t1-.subt          ; Offset from .subt
;      dc.w   .t2-.subt
;      dc.w   .t3-.subt
;      dc.w   .t4-.subt
;      dc.w   .t5-.subt
;      dc.w   .t6-.subt
;
;.t1   dc.b   'What a Bummer',0
;.t2   dc.b   'Paninaro',0
;.t3   dc.b   'Fade to a Pinkish Red',0
;.t4   dc.b   'Revenge of the Mutant Wafer Biscuits',0
;.t5   dc.b   'Mind Bomb (Theme)',0
;.t6   dc.b   'In The Night',0
;	
;      even
;  dc.b  'YEAR','1990',0
;  dc.b  'TIME'
;  dc.w  $e1,$60,$78,$11c,$40,$5f
;  even
;  dc.b  'HDNS',0

;
;
;sndh_init:
;  movem.l d0-a6,-(sp)
;  bsr.w  player
;  movem.l  (sp)+,d0-a6
;  rts
;
;sndh_exit:
;  movem.l d0-a6,-(sp)
;  bsr.w  player+4
;  movem.l  (sp)+,d0-a6
;  rts
;
;sndh_vbl:
;  movem.l d0-a6,-(sp)
;  bsr.w  player+8
;  movem.l  (sp)+,d0-a6
;  rts
;
;  section data
;
;player:
;  incbin  'replaycode.bin'
;  even


;http://phf.atari.org

;(EOF)

-------End of sndhv21.txt----------