View source for AMOS Music Bank format

'''[[AMOS Music Bank|AMOS music banks]]''' are one of the standard [[AMOS file formats]].

All multi-byte integers are in big-endian format.

The format is divided into sections. The format typically starts with a Standard AMOS bank header, which may be truncated or damaged depending on how it was ripped:

{| class="infotable"
!Offset!!Size!!Description
|-
|0||4 bytes||'''AmBk''' ID (0x416D426B)
|-
|4||2 bytes||bank number (should be 3)
|-
|6||2 bytes||flags
|-
|8||4 bytes||bank length, only in bits 27-0 
|-
|12||8 bytes||bank type (should be "<tt style="white-space:pre">Music   </tt>")
|}

Whatever the format of the standard AMOS bank header, it is immediately followed by the music bank's main header:

{| class="infotable"
!Offset!!Size!!Description
|-
|0||4 bytes||offset from start of this header to instrument data section
|-
|4||4 bytes||offset from start of this header to to song data section
|-
|8||4 bytes||offset from start of this header to to pattern data section
|-
|12||4 bytes||always 0
|}

These offsets point to other sections of the file, which might not be consecutive or even in the order given. 

== Instrument data section ==
{| class="infotable"
!Offset!!Size!!Description
|-
|0||2 bytes||number of instruments (''n'')
|-
|2||''n'' * 32 bytes||each instrument's data, in this format:

{| class="infotable"
!Offset!!Size!!Description
|-
|0||4 bytes||offset from start of instrument data section to the sample data for this instrument.
|-
|4||4 bytes||offset from start of instrument data section to the repeating section of this instrument's sample data
If the sample doesn't repeat, this will point to either 4 or 2 bytes of zeroes
|-
|8||2 bytes||In a repeating sample, this is the offset of the repeating part (in 4-byte longwords, from the start of the sample data for that sample)
In a non-repeating sample, it is the length of the sample (in 2-byte words).
|-
|10||2 bytes||length (in 2-byte words) of repeating section of sample data
If the sample doesn't repeat, this will either be 2 or 1.
|-
|12||2 bytes||default volume of sample, from 0x00 (min) to 0x40 (max)
It may also accidentally include a Protracker finetune value in the upper 8 bits, which the AMOS player ignores
|-
|14||2 bytes||sample length (in 2-byte words)
|-
|16||16 bytes||sample name (ASCII text, padded with spaces or null bytes)
|}

|-
|2 + ''n'' * 32||? bytes||raw sample data
|-
|}

'''WARNING:''' samples lengths can often be incorrect. Do not rely on the "sample length" field here. To find the true length of a sample, it is necessary to take all sample offsets and sort them into order. Each sample's length is that of its offset subtracted from the offset of the next sample. For the final sample, its offset should be subtracted from the overall length of the instruments data block (which will be the offset of the instruments block subtracted from the offset of the section following it, or the overall length of the file if no other section follows it).

== Song data section ==
The song data section starts with a list of offsets to songs:
{|class="infotable"
!Offset!!Size!!Description
|-
|0||2 bytes||number of songs (''n'')
|-
|2||''n'' * 4 bytes||offsets from start of song data section to each song
|}

Each song has this format:
{| class="infotable"
!Offset!!Size!!Description
|-
|0||2 bytes||default tempo, 1-100, default is 17. not used by player!
|-
|2||2 bytes||offset from start of this song to audio channel 0 playlist
|-
|4||2 bytes||offset from start of this song to audio channel 1 playlist
|-
|6||2 bytes||offset from start of this song to audio channel 2 playlist
|-
|8||2 bytes||offset from start of this song to audio channel 3 playlist
|-
|10||2 bytes||seems to be unused, should be zero
|-
|12||16 bytes||name of song (ASCII text, padded with spaces or null bytes)
|}

A playlist is a stream of 2-byte words, giving the list of patterns to play in order for that channel.

Valid pattern numbers start from 0 and go up to however many patterns there are. The list is terminated with 0xFFFE, sometimes 0xFFFF.

Each channel has its own set of patterns, so pattern 0 on channel 0 is not the same as pattern 0 on channel 1.

== Pattern data section ==
The pattern data section starts with a list of patterns
{| class="infotable"
!Offset!!Size!!Description
|-
|0||2 bytes||number of patterns (''n'')
|-
|0x02||''n'' * 8 bytes||pattern offsets:
{| class="infotable"
!Offset!!Size!!Description
|-
|0||2 bytes||offset from start of pattern data section to this pattern for channel 0
|-
|2||2 bytes||offset from start of pattern data section to this pattern for channel 1
|-
|4||2 bytes||offset from start of pattern data section to this pattern for channel 2
|-
|6||2 bytes||offset from start of pattern data section to this pattern for channel 3
|}
|}

A pattern is a stream of 2-byte word commands and notes.

Commands have bit 15 set ($8000-$FFFF). Notes do not have bit 15 set ($0000-$7FFF).

Commands come before notes and are executed immediately. When a note appears, processing the pattern finishes for that vertical blank, and processing will re-commence once the delay counter elapses (see the delay command below).

Unlike SoundTracker, which allows one command per note, there can be any number of commands per note, although generally it's not useful, as repeating the same command again and again would simply overwrite its value.

=== Notes ===
For a note, all that matters is bits 12 to 0 ($000-$FFF). This, like Soundtracker, is an Amiga hardware note period (audXper).

When a note is triggered, the current note volume is set to the default volume for the instrument being played.

<!-- TODO: what does this mean?

ABK Music Banks Support two different Note formats. The new format never has bit 14 set and is documented above. The older format has bit 14 set and includes an in built delay. A second word then encodes the note. i.e. 0x7F[DD] 0xF[PPP] where DD is the delay in positions (similar to executing a command 0x10[DD]) and PPP is the the Amiga note period (audXper) the same as a new note format. If an old note format is found with 0 delay and 000 audio this signifies the end of the pattern. 

-->

A note cannot be played before the first "set instrument" command, as notes do not implicitly have an instrument associated with them.

=== Commands ===

Each command has a parameter, although many commands don't need and therefore ignore their parameter. The command value is the bits 14 to 8 of each word, the parameter value is bits 7 to 0.

All "effect" commands which have a lasting effect, between notes are assumed to continue running forever until they are changed to another effect, or stopped with the "stop effect" command. A channel can only run one effect. So if AMOS did a "shift down" command, a "delay" of 14 and then a "stop effect", the equivalent in SoundTracker would be to repeat the portamento down command 14 times, once in each position, and positions after that would simply have the empty command (000).

There is no implicit delay of one position between commands or notes, as there is in SoundTracker. Instead, a "delay" (0x10) command must be executed.

Other than the "set tempo" and "low pass filter on/off" commands, the effect of every command is limited to the channel it runs on.

The commands are as follows:

{|class="infotable
!Command value!!Description of effect
|-
|$80xx||'''end of pattern''': advance to the next pattern in the playlist
Also stops any currently running effects like the "stop effect" command
|-
|$81xx||'''old slide up''': not supported by player. identical to slide up?
|-
|$82xx||'''old slide down''': not supported by player. identical to slide down?
|-
|$83xx||'''set volume'': sets the volume of the note currently playing
This is equivalent to the SoundTracker "C" command.
Uses the commmand value, valid range 0 to 63 (therefore $8300 - $833F)
Surprisingly, the valid maximum Amiga volume 64 ($40) isn't supported by the player and will be rounded down to 63
|-
|$84xx||'''stop effect''': stops any currently running effect
|-
|$85xx||'''repeat''': set or jump to the repeat mark
If the parameter is zero, this is the "repeat mark".

If the parameter is non-zero, jump back to the repeat mark for the number of times given by the parameter

This is equivalent to the Protracker "E50" and "E6x" commands
|-
|$86xx||'''low-pass filter on''': equivalent to the SoundTracker "E01" command
|-
|$87xx||'''low-pass filter off''': equivalent to the SoundTracker "E00" command
|-
|$88xx||'''set tempo''': sets the tempo of replay

The parameter is between 1 and 100 (therefore $8801 - $8864)

AMOS has a different tempo system from SoundTracker.

* SoundTracker's speed is a number between 1 and 255, and that is the number of vertical blanks between advancing one position in the pattern.
* AMOS keeps a counter and adds the tempo value to it once per vertical blank. When the counter is greater or equal to 100 (or 120 for NTSC), AMOS advances the position and reduces the counter by 100 (or 120 for NTSC)
          
This gives an average SoundTracker speed of (100/tempo) at 50Hz or (120/tempo) at 60Hz, which gives a (tempo/2) Hz change in position, regardless of frame rate. This is quite nice, but as timing is still in 50 or 60Hz multiples, it's possible that instruments may sound fractionally out of time -- for example, tempo=17 has a cycle of 8 positions advancing every 6 vertical blanks and the 9th position advancing after 5 vertical blanks.

To convert from SoundTracker speeds to AMOS tempos, the converter uses the formula: amos_tempo = 100 / soundtracker_speed

That's not an accurate conversion, and conversion back is even more fun. For simple conversion, I recommend the following roughly accurate speeds:
{|class="infotable"
!AMOS tempo!!SoundTracker speed
|-
|1||100 (F64) *
|-
|2||50 (F32) *
|-
|3||33 (F21) *
|-
|4||25 (F16)
|-
|5||20 (F14)
|-
|6||17 (F11)
|-
|7||14 (F0E)
|-
|8||12 (F0C)
|-
|9||11 (F0B)
|-
|10||10 (F0A)
|-
|11||9 (F09)
|-
|12||8 (F08)
|-
|13-15||7 (F07)
|-
|16-18||6 (F06)
|-
|19-22||5 (F05)
|-
|23-28||4 (F04)
|-
|29-40||3 (F03)
|-
|41-66||2 (F02)
|-
|67-100||1 (F01)
|}

Note: the first three speeds are not possible with Protracker, which uses F20 and above to set the CIA tempo.
|-
|$89xx||'''set instrument''': sets the instrument that the next note command will use
Parameter is from 0 (first instrument) to the last instrument
|-
|$8Axx||'''arpeggio''': arpeggiates the current instrument
The parameter is broken into the upper 4 bits and lower 4 bits. Equivalent to the SoundTracker "0" command.

This effect will continue until a new effect, or change of pattern
|-
|$8Bxx||'''tone portamento''': causes the currently playing note to slide towards the pitch of the next note
Equivalent to the SoundTracker "3" command.

This effect will continue until a new effect, or change of pattern
|-
|$8Cxx||'''vibrato''': varies the currently playing note's pitch according to a sine wave
The upper 4 bits of the parameter give the speed of the vibrato, the lower 4 bits give the depth.

Equivalent to the SoundTracker "4" command

This effect will continue until a new effect, or change of pattern
|-
|$8Dxx||'''volume slide''': Raises or lowers the volume of the currently playing note
The upper 4 bits of the parameter will raise the volume by that amount every vertical blank. If zero, the lower four bits are considered. They lower the volume by that amount every vertical blank.

Equivalent to SoundTracker "A" command
|-
|$8Exx||'''portamento up''': raises the pitch of the currently playing note
Decreases the note period by the amount given by the parameter every vertical blank, to the lowest period of 113

Equivalent to SoundTracker "1" command

This effect will continue until a new effect, or change of pattern
|-
|$8Fxx||'''portamento down''': lowers the pitch of the currently playing note
Increases the note period by the amount given by the parameter every vertical blank, to the highest period of 856

Equivalent to SoundTracker "2" command

This effect will continue until a new effect, or change of pattern
|-
|$90xx||'''delay''': states that after the current list of commands and final note has been played
The channel will wait for the number of positions given by the parameter, before executing any more commands and notes

Each note played should have a corresponding delay command.
|-
|$91xx||'''position jump''': changes the position in the song
The position is taken from the parameter (position 0 = start of song) and then "end of pattern" command fires

Equivalent to SoundTracker "B" command
|}

[[Category:AMOS]]
[[Category:File formats]]