ZX-Player File Formats

ASC(E)PSGFXMNewAYOUTSTC/ZXSVortexYMZX50ZXAY
FORMATS-HOME

YM

Emulator: StSound, SainT, PaCifiST, Arnold, CPCe
Author: Arnaud Carre (Leonard/OXYGENE)

Leonard/OXYGENE designed this format for his AY-emulator StSound.
At the beginning this emulator was an Atari ST sound chip emulator, but nowadays this is a Multi-Computer Sound Emulator able to play AY/YM sounds and some Amiga/Paula chip modules.
Now this project consists of many programs (players, converters) and archives of music. But Spectrum-archives are in very bad condition.
Don't forget to set chip frequency to 2.000.000 Hz for Atari and to 1.000.000 Hz for Amstrad while listening YM2 and YM3 files with Atari and Amstrad music (this subtypes do not care about frequency settings).

A AY/YM-file consist of an LHA-archive (type 5) created by the LhA.exe by Haruyasu Yoshizaki with the -h0 switch enabled. This will create an "H0" Header (Type 5).

YM2!

First four bytes is the ASCII identifier "YM2!".
AY Emulator doesn't know the difference between YM2 and YM3 types.

YM3!

First four bytes is again the ASCII identifier "YM3!".
Offset Size Name Value Contents
0 4 ID "YM3!" File type Identificator

The next bytes are the data block of AY chip registers values.

Registers are updates one time per VBL interrupt. If music length is N interrupts, then block consist first N bytes for register 0, further N bytes for register 1 and so on. In total: N*14 bytes.
The number of used VBL for music can be computed as follow: nvbl = (ymfile_size-4)/14;
  VBL1:
    store reg0,reg1,reg2,...,reg12,reg13  (14 regs)
  VBL2:
    store reg0,reg1,reg2,...,reg12,reg13  (14 regs)
        ..........
  VBLn:
    store reg0,reg1,reg2,...,reg12,reg13  (14 regs)

If the current interrupt features no output to register 13 then the byte of the data block for this interrupt and for this register has the value 255 ($FF).

YM3b!

This format is nearly identical with YM3. It adds only the ability to use loops.

First four bytes is the ASCII identifier "YM3b".
The following bytes are the data block (see YM3 description).
But last four bytes is a DWORD (32bits integers) data and contains the frame number at wich the loop restart. That's all.

YM4!

Legend: BYTE            8bits integer.
        WORD            16bits integer.
        DWORD           32bits integer.
        string[n]       Ascci string of n bytes long.
        NT-String       NULL-Terminated string.

WARNING: All DWORD or WORD are stored in MOTOROLA order in the file (INTEL reverse)

Offset Size Type Comment
0 4 DWORD ID of YM4 format. ('YM4!')
4 8 string[8] Check String ('LeOnArD!')
12 4 DWORD Nb of valid VBL of the file
16 4 DWORD Song attributes (see bellow)
20 4 DWORD Nb of digi-drum sample (can be 0)
24 4 DWORD Frame loop start (generally 0)

For each digidrum sample:

{
.. ?? DWORD sample size
.. ?? BYTES sample data (8bits per sample)
}

.. ? NT-String Name of the song
.. ? NT-String Name of the author
.. ? NT-String Comments (Name of the YM converter !)
.. ? All YM2149 registers
.. 4 DWORD End-File check ('End!')

So you've seen in the YM3 format that all 14 registers of the YM2149 are saved in file each VBL. Now, I had to add 2 "virtual" registers to store extended information. So there is 16 bytes in the file for each VBL. Now the VBL number n will be noticed "Vn" and register m "Rm". First VBL is V0 and first register is R0. (R0 to R15)
        The file data block will be composed of:

        V0R0,V0R1,V0R2,....,V0R14,V0R15
        V1R0,V1R1,V1R2,....,V1R14,V1R15
        .....
        This is the non-interleaved format block.



        The data block can be on a different form:

        V0R0,V1R0,V2R0,....,VnR0
        V0R1,V1R1,V2R1,....,VnR1
        ....
        V0R15,V1R15,V2R15,....,VnR15

        This is the interleaved format block.

Those who are reading till now have noticed that the YM3 format is an interleaved format. In fact, the YM4 format can be interleaved or not. (Interleaved format offers a very powerfull compression ratio when compressed with LHA).

        Let's see the DWORD "song attribute":
        (bn represent the bit n of the DWORD)

        b0:     Set if Interleaved data block.
        b1:     Set if the digi-drum samples are signed data.
        b2:     Set if the digidrum is already in ST 4 bits format.

        b3-b31: Not used yet, MUST BE 0.

        Here come valid bits for standard 14 first registers:
        (Same as YM3 Format.)
        (- means Unused, X means used)

        NOTE: Now, digi-drum will be noticed DD and Timer-Synth will be
              noticed TS.



                b7 b6 b5 b4 b3 b2 b1 b0
        r0:      X  X  X  X  X  X  X  X         Period voice A
        r1:      -  -  -  -  X  X  X  X           "      "   "
        r2:      X  X  X  X  X  X  X  X         Period voice B
        r3:      -  -  -  -  X  X  X  X           "      "   "
        r4:      X  X  X  X  X  X  X  X         Period voice C
        r5:      -  -  -  -  X  X  X  X           "      "   "
        r6:      -  -  -  X  X  X  X  X         Noise period
        r7:      X  X  X  X  X  X  X  X         Mixer control
        r8:      -  -  -  X  X  X  X  X         Volume voice A
        r9:      -  -  -  X  X  X  X  X         Volume voice B
        r10:     -  -  -  X  X  X  X  X         Volume voice C
        r11:     X  X  X  X  X  X  X  X         Waveform period.
        r12:     X  X  X  X  X  X  X  X            "       "
        r13:     -  -  -  -  X  X  X  X         Waveform shape.

        New "virtual" registers to store extra data:

        r14:     -  -  -  -  -  -  -  -         Frequency for DD1 or TS1.
        r15:     -  -  -  -  -  -  -  -         Frequency for DD2 or TS2.

As we've seen, r13 has a particular status. If the value stored in the file is 0xff, YM emulator will not reset the waveform position.

The YM4 format provides to start or run 1 TS and 1 DD during the same VBL.

You notice there is a least 28 free bits in the 14 standard registers. YM4 format use them to store "extra" information. Let's see the "extra" bits:

        r1 free bits are used to code TS:
        r1 bits b5-b4 is a 2bits code wich means:

        00:     No TS.
        01:     TS running on voice A
        10:     TS running on voice B
        11:     TS running on voice C

r1 bit b6 is only used if there is a TS running. If b6 is set, YM emulator must restart the TIMER to first position. (You must be VERY sound- chip specialist to hear the difference).

        r3 free bits are used to code a DD start.
        r3 b5-b4 is a 2bits code wich means:

        00:     No DD
        01:     DD starts on voice A
        10:     DD starts on voice B
        11:     DD starts on voice C

WARNING:If a DD starts on voice V , the volume register corresponding to V (Ex r8 for voice A, r9 for B and r10 for C) contains the sample number in 5 low bits. (That mean you have 32 digiDrum max in a song)

Concerning DD and TS, both effects need to be played at a given frequency. On the ATARI-ST, play routine use the MFP-TIMER chip. That is, any frequency can be coded on 11bits: 8bits for timer count, and 3bits for timer predivisor. The MFP runs at 2457600 Hz and has a preset of predivisor:

        000:    Timer stop.
        001:    Prediv by 4
        010:    Prediv by 10
        011:    Prediv by 16
        100:    Prediv by 50
        101:    Prediv by 64
        110:    Prediv by 100
        111:    Prediv by 200

        The 8 bits timer count value is named TC and 3bits prediv value
        is named TP.

        Some ex to endserstand how it works:

        TP      TC      Frequency (Hz)
        1       28      (2457600/4)/28   = 21942 Hz
        4       150     (2457600/50)/150 = 327 Hz

Encode: 
        TP for TS is stored in the 3 free bits of r6 (b7-b5)
        TP for DD is stored in the 3 free bits of r8 (b7-b5)
        TC for TS is stored in the 8 bits of r14
        TC for DD is stored in the 8 bits of r15

        4bits volume value (vmax) for TS is stored in the 4 free bits of r5 (b7-b4)



YM5!

This is the actual and most common used format and consist consists of additional information: chip frequency, player frequency, title, author name, comment and specific Atari ST data (Digi-Drum and SID effects).
In AY_Emulator this additional Atari effects are not supported.

The AY/YM5 file format:
Offset Size Type Comment
0 4 DWORD ID of YM4 format. ('YM4!')
4 8 string[8] Check String ('LeOnArD!')
12 4 DWORD Nb of valid VBL of the file
16 4 DWORD Song attributes (see bellow)
20 2 WORD Nb of digi-drum sample (can be 0)
22 4 DWORD YM2149 External frequency in Hz
(ex:2000000 for ATARI-ST version,
1000000 for AMSTRAD CPC)
26 2 WORD Player frequency in Hz
(Ex: 50Hz for almost player)
28 4 DWORD VBL number to loop the song. (0 is default)
32 2 WORD Size (in bytes) of future additinal data.
(must be 0 for the moment)

For each digidrum sample:

{
.. ?? DWORD sample size
.. ?? BYTES sample data (8bits per sample)
}
.. ? NT-String Name of the song
.. ? NT-String Name of the author
.. ? NT-String Comments (Name of the YM converter !)
.. ? All YM2149 registers
.. 4 DWORD End-File check ('End!')


Data block contents now values for 16 registers (14 AY registers plus 2 virtual registers for Atari special effects).
If bit 0 of field Song Attributes is set, data block are stored in YM3-style order (interleaved). If this bit is reset, then data block consists first 16 bytes of first VBL, then next 16 bytes for second VBL and so on. In second case YM5 file is compressed more badly.

YM6!

This format is equivalent to YM5!, but can use yet another special Atari effect. More info about YM files can be found in official ST-Sound package or on ST-Sound Project Homepage (http://leonard.oxg.free.fr/).