; SNDH file structure, Revision 2.2
;
; 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
; SNDH v2.2 by Phil Graham and Benjamin Gerard
;
; This document was originally created by Anders Eriksson, updated and
; adapted with SNDH v2 structures by Phil Graham. V2.2 structures
; conceived and adapted by Benjamin Gerard and Phil Graham.
;
; January 2026
;
; 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  play_music_driver
;12             4       SNDH head                    dc.b   'SNDH'
;
;-------------------------------------------------------------------------------------------
; 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','Mr Hacker',0		0 (Null)
; CONV		Converter Name		dc.b 'CONV','Who Knows',0		0 (Null)
; ##??		Sub Tunes		dc.b '##04'				None
; 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 'YEAR','1996',0			0 (Null)
; #!??		Default Sub tune	dc.b '#!02'				None
; #!SN		Sub tune names		dc.b '#!SN'				None, Even boundary
;					dc.w x1,x2,x3,x4			SNDHv21 Updated
;					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
; FRMS	(sub) tune			dc.b 'FRMS'				None SNDHv22
;	(in frames)			dc.l x1,x2,x3,x4
; FLAG					dc.b 'FLAG','~', as below		SNDHv22
;					,"a",0					Timer A
;					,"b",0					Timer B
;					,"c",0					Timer C
;					,"d",0					Timer D
;					,"e",0					STe
;					,"f",0					SFX
;					,"g",0					Digital
;					,"h",0					HBL
;					,"j",0					Jingles
;					,"k",0					Kill System
;					,"l",0					lmc
;					,"p",0					AGA
;					,"s",0					DSP
;					,"x",0					SFX
;					,"y",0					YM2149
;					,"0",0					6.25 kHz DMA (STe)
;					,"1",0					12.5 kHz DMA (STe/Falcon)
;					,"2",0					25 kHz DMA (STe/Falcon)
;					,"3",0					50 kHz DMA (STe/Falcon)
;					,"4",0					12.2 kHz DMA (Falcon)
;					,"5",0					14 kHz DMA (Falcon)
;					,"6",0					16.3 kHz DMA (Falcon)
;					,"7",0					19.6 kHz DMA (Falcon)
;					,"8",0					24.5 kHz DMA (Falcon)
;					,"9",0					32.8 kHz DMA (Falcon)
;					,"A",0					49.1 kHz DMA (Falcon)
;					,"B",0					Blitter
;					,"C",0					68020
;					,"F",0					Filters
;					,"S",0					Stereo
; HDNS	End of Header			dc.b 'HDNS'				None, Even boundary

;---------------------------------------------------------------------------
;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 use 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 occurs directly after the
; #!SN tag.
; See example header below.
;---------------------------------------------------------------------------


;---------------------------------------------------------------------------
; FRMS Tag
;---------------------------------------------------------------------------
; The FRMS tag is followed by 'x' long words ('x' being the number of
; tunes). Each long word contains the number of frames of each sub tune.
; For example, a 1 minute song played at 50hz would equal 3000 frames.
; (60 seconds x 50). If the long word is null then it is assumed that the
; tune endlessly loops. The FRMS tag has replaced TIME (SNDH v2 and earlier)
;---------------------------------------------------------------------------


;---------------------------------------------------------------------------
; HDNS Tag
;---------------------------------------------------------------------------
; The HDNS signifies the end of the SNDH header and the start of the actual
; music data/driver. 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   'FLAG','~','3',0
;      dc.b   'TITL','Mindbomb - Digi Synth',0
;      dc.b   'COMM','Spaz',0
;      dc.b   'RIPP','Grazey',0
;      dc.b   'CONV','Quartet-2-SNDH (c) PHF',0
;      dc.b   '##06'
;      dc.b   'TC200',0
;      dc.b   '#!01'
;      even
;      dc.b	'#!SN'			; Subtune names
; .tagbase	dc.w   .t1-.tagbase	; Initial offset
;	dc.w	.t2-.t1
;	dc.w	.t3-.t2
;	dc.w	.t4-.t3
;	dc.w	.t5-.t4
;	dc.w	.t6-.t5
;
;.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'
;	dc.b  'FRMS'
;	dc.l  3000,4760,5420,2900,3224,7208
;	even
;	dc.b  'HDNS'
;
;
;
;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


;https://sndh.atari.org/

;(EOF)
