Disclaimer: This is an archive document which has been preserved incase the original source is lost. It has been tidied by removing ASCII art which cannot be rendered in modern web browsers. Some typographic errors have been corrected. This document is for informational purposes only and is copyright the original author. Any errors, questions, ommissions or corrections should be directed to the original author.
Original document link: here

Written by Arnaud Carre. (arnaud.carre@freesurf.fr)

NEW: "YM3b" Format !!! See below...

WARNING: YM4! format is changed !!!

Many people asked me how to find new YM files. Well, the problem is
that it takes me too much time to convert new modules. Then I decide to give
you my YM-File format, so you can generate YM-File by yourself !

As you probably know, YM is only an YM2149 Chip emulator, not a true
MC68000 emulator. (For the moment !). YM-Files does not contain any 68000
code routine. A music-file is composed of YM2149 registers generated by the
original play-routine for each 50th seconds. As the YM2149 has 14 registers
8 bits each, that means 14 bytes for 1/50 second, so 700 bytes for one
second of soundchip.

When I convert an ATARI music, I play the music on the ATARI, and I
store YM2149 registers set each 1/50sec (Vertical Blank time, VBL) in a big
file as follow:

store reg0,reg1,reg2,...,reg12,reg13 (14 regs)
store reg0,reg1,reg2,...,reg12,reg13 (14 regs)

store reg0,reg1,reg2,...,reg12,reg13 (14 regs)

The problem is that is takes a lot of disk-space. Just count: A 10
minutes song will take 420000 bytes on disk. But don't panic, the music are
compressed with LHARC method (using LHA program from Haruyasu Yoshizaki).
To reach best compression ratio, I store registers in a different order:

VBL1 reg0, VBL2 reg0, VBL3 reg0 .... VBLn reg0

VBL1 reg1, VBL2 reg1, VBL3 reg1 .... VBLn reg1

VBL1 reg14,VBL2 reg14,VBL3 reg14.... VBLn reg14

So, here is the old YM3 file format:

Offset Size Name Value Comments
0 4 ID 'YM3!' File type Identificator.

then YM2149 registers starts a offset 4.

The number of used VBL for music can be computed as follow:

nvbl = (ymfile_size-4)/14;

The LHA compression must be called AFTER the file is generated. ALWAYS
USE THE HEADER TYPE 0 when compressing (-h0).
Ex: You just create your binary file, starting with 'YM3!' ID, then
all YM registers. The music is 2 minutes long, that means your
binary is 2*60*700 + 4 = 84004 bytes long. you must compress it before
using the file with YM.EXE: (ex: your binary is TEST.BIN)


Then a file TEST.LHA is created, wich is DIRECTLY a valid YM file.
just type:

ren test.lha test.ym

Then you can hear the file with YM.EXE

(I use LHA.EXE v2.13).

Some old and specific music starts with header 'YM2!', don't use this

SPECIAL: Register 13!

Creating a binary with YM registers for each VBL is easy. However
there is special case concerning register 13. Reg13 is used for the volume
envelope wave-form on the YM2149. The problem is writing to that register
"restarts" the wave-form at beginning. That is, you CAN'T access this regis-
ter each VBL if the original play-routine does not. So, if the original
player does not write to register 13 on VBL n, write 0xff value.
(So when YM.EXE read 0xff as reg13, the internal emulator register is not

That's all for 'YM3!' file.

That's all for the 'YM3!' format. As you see, it is very simple (then
not very powerfull) but you can convert many ATARI soundchip tunes with that
format. (Especially old game-music, wich use very simple play-routine, or

But if you know the ATARI demos, you probably know there is many
tricks used by sound-player to produce real-drums or distorted sound: sample
for drums, additional tone synthesis using TIMER etc... The 'YM3!' format can
not play such music so...


These days you can find many YM tunes on Internet World Wide Web. Many
of these are generated with automatic program. (See the ATARI program written
by Jochen Knaus). The problem is that for each music, the generating program
must know the music time. (And even the loop position if it exists !). So I
write a PC program (YMTOOL.EXE) wich:
-Read an YM file.
-Display infos about it.
-Search loop automaticly in the music.
-Save a new YM file with fine loop.

The new YM file supports the loop point to be at the middle of a music (not
only at the beginning, as the YM3 format). So a new format is born: "YM3b".
The only difference is "YM3b" instead of "YM3!" and the music file contains
one DWORD (32bits integers) at the end of the file, wich contains the frame
number at wich the loop restart.
Ex: If a music is 5600 frames and the loop restarts at frame 432, just write
"YM3b", then 5600*14 bytes of YM registers, then 432.

Go to my web-page to habe link to download YMTOOL.EXE or to find link to
Jochen Knaus homepage:



The 'YM4!' format is not currently implemented in the YM emulator, but
I have written the most complete format to play all "evoluated" music such as
SCAVENGER or ETERNAL tunes. If you convert a music wich the player does not use
any "hardware" trick such digi-drum or synth-tune, use 'YM3!' format describe
above: it will be faster and easyer to create. (Almost all standart YM file
existing around the world (exept DIGI-Drums ones) can be written in YM3

If you want to convert a SPECIAL music wich use many tricks to produce
strange sound, you must be familiar with ATARI-ST sound programing and follow
next instructions...

Additional sound effects used by strange-player are only two types differents:

1) Digi-Drums

Generally digi-drums is a bunch of sample in the orignal play-rout.
You will have to localize and extract them. In the YM file, you have to
store the sample with their respective size. (see next part)
when playing, a digi-drum is defined with one value: timer frequency
to replay sample.

2) Tone synthesis

To produce very funny sound, some player use the ATARI-ST timer
controller to change YM2149 volume more than 1 time per VBL. Generally
the routine in the player is as follow:

lab1: move.l #$08000f00,$ffff8800.w
move.l #lab2,$134.w

lab2: move.l #$08000000,$ffff8800.w
move.l #lab1,$134.w

So the volume is set to 15 then to 0 then to 15 etc... many times
in the same VBL at a given frequency. In fact, the volume switch always
between 0 and vmax. So a tone-synthesis is define by two values: vmax and
timer frequency.

3) 'YM4!' File format:

Here is the description of the binary YM4 file. After the file is
created, you can compress it with LHA -h0 as above.

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 below)
20 4 DWORD Nb of digi-drum sample (can be 0)
24 4 DWORD Frame loop start (generally 0)

For each digidrum sample:
.. 4 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:

This is the non-interleaved format block.

The data block can be on a different form:


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

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

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


Well, it seems that BEFORE I acheive the YM4 format loading rout, some
of you (particulary Mage!) ask me to change a bit the format to add extra
information. So here is YM5 format: (the YM4 is obsolete now)

Offset Size Type Comment
0 4 DWORD ID of YM5 format. ('YM5!')
4 8 string[8] Check String ('LeOnArD!')
12 4 DWORD Nb of valid VBL of the file.
16 4 DWORD Song attributes (see below)
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 futur
additinal data.
(must be 0 for the moment)

For each digidrum sample:
.. 4 DWORD sample size
.. ? BYTES sample data (8bits per sample)

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

Ok, YM4 Expert had notice there is no major change.

4) Pfff....

That's all for the YM4 format wich allow you to encode most
of the demo-soundchip from the ATARI. If some of you think the file format is
a bit hard to assume I agree with you. I only prefer a complex but shorter
format than simple and big one...

If you have any trouble, problem or questions about YM3 or YM4 format,
write or mail me:

Internet E-Mail:

WEB Page:

Have a nice day !


Written by Arnaud Carr,

YM6 File Format spec.


  1. News and rumours about StSound
  2. YM6 format spec.


News and rumours about StSound

If you're an StSound fanatic, you probably notice there is no regulary update. In fact, I (leonard) work on different projects these times.
First of all, I work with James Boulton on a brillant ST Emulator called "SainT". We plane to release it for the STNICC 2000.
Second, HTML and old StSound code takes me a lot of time, and I'm very lazy for that kind of work.
And third (but not least !!!) I just crashed my soundblaster card !!! Unfortunatly I try an Ensoniq Soundscape but it does not work too. I think my ISA slot is dead... :-(

So, don't worry about StSound: it is always alive, and I'm very happy (proud :-)) to see what's people do with YM (see the 8bits players, that's great !).

The next StSound release will surely consist of a new Winamp plugin and some update on the StSound page. (You're too many registered users now, I have to update all your names !!)

Other thing important ! I change my email adress so please write me at arnaud.carre@freesurf.fr now ! (StSound web page don't change: www.multimania.com/leonard )

YM6 format spec.

First of all, if you really want to make an YM file reader, you MUST read the first YmFormat.txt, convering all stuff you have to know before read YM6 format. You must be YM5 familiar because I'll use some words / expressions used in YmFormat.txt.

Ok, let's assume you're an YM5 specialist now.

Let's call data registers r0, r1, etc... YM6 is a 16 bytes per frame format, as YM5. The big change is that YM6 can play 1 or 2 special effects in a frame. (To play tunes with two sid voices for exemple).

R1, bit 4-5: Special effect 1 voice (00: No special effect 1, 01: Effect 1 on voice A, 02: Voice B, 03: Voice C)
R1, bit 6-7: Special effect type (00: SID voice, 01:Digidrum, 10:Sinus SID (TAO), 11: Sync Buzzer (TAO)

For each effect, timer predivisor is stored in R6, bits 5-7, and timer count is stored in R14, bits 0-7. All that stuff is available for the second special effect, you just have to replace R1,R6,R14 by R3, R8 and R15).

Let's now see these new special effects:

SID Sound

As YM5, SID is composed of a single value: VMAX. VMAX is contained in bits 0-3 of the volume registers of the voice effect. (Remember, voice effect is stored in R1 b4-5)


As YM5, Digidrum is composed of a sample number, wich is stored in bits 0-4 (5 bits lenght) of the volume voice register (R8,R9 or R10, it depends).


Sinus SID is a TAO specific trick to produce sinus waves. "Sinus SID" is not a great name for the effect, wich is just a looped sample. (But I use it in my first source code and I don't change it ! :-)). The sample is composed of 8 bytes of volume value. So you have to loop in these 8 bytes. I personally use that table:

static void sinVolBuild(void)
for (int vol=0;vol<16;vol++)
for (int pos=0;pos<8;pos++)
double a = (((double)pos)*2.0*PI)/8.0;
int amp = (int)(32767.0*sin(a)*SIDSINPOWER);
amp = (amp*vol)/16;
sinVolTab[vol*8+pos] = amp;

Sync Buzzer

Again a TAO effect, wich is, to my opinion, one of the greatest effect in ATARI music world (just after the SID of course). In fact, it's very simple ! It's a SID technique on the volume shape. As you're an YM specialist now, you probably know that writing in YM2149 registers 13 set a new volume shape, but RESTART the shape ! So, by writing in R13 in a timer rout, you can modulate the shape frequency, producing some nice sound. (Try the new TAO tunes).
SyncBuzzer uses only one data: the env shape used. It's stored in bits 0-3 (4 bits lenght) of the effect volume voice register (R8,R9 or R10).


Ok I hope it will help all of you asking me some YM6 support, and have a nice day !

Arnaud Carr, aka Leonard / OXYGENE