Tutorial: How to Write a 1-Bit Music Routine (Page 1 of 3)

Part 3: Calculating Note Counters

So you've got your sound loop and your data loader all set up, but now you need to actually fill in some music data. For that, you will need to know how
to calculate the note/frequency counter values.

Basically, all you need to know is the magic formula

fn = int(f0 / (a)^n) 

where...
... f0 is the base note counter value you want to use
... n is the distance to the base counter value in halftones
... fn is the frequency of the note n halftones away from the base note
... a is the twelth root of 2, approx. 1.059463094

Unless you want concert pitch, it doesn't really matter so much which base value (f0) you use, so you might as well use something high, e.g. 254.
Now, to calculate the value for the base note plus one halftone, you do:

f1 = int(254 / 1.059463094^1) = 239

For the base value plus two halftones, it's

f2 = int(254 / 1.059463094^2) = 226

As you can see, the lower the note, the higher the counter value. This makes sense because we decrement these values in the sound loop. A higher value means it takes longer for the counter to reach zero and reset, therefore the output is activated/toggled less frequently - which of course results in a lower frequency.

Part 5: Improving the Sound

You've followed this tutorial series and have come up with a little 1-bit sound routine of your own design. Only problem - it still sounds crap - notes are detuned, there are clicks and crackles all over the place, and worse of all, you hear a constant high-pitched whistle over the music. So, it's time to address some of the most common sources of unwanted noise in 1-bit sound routines, and how to deal with them.

Timing Issues

In order to keep the pitch stable, you need to make sure that the timing of your sound routine is as accurate as possible, ie. that each iteration of the sound loop takes exactly the same time to execute.

Let's take a look again at the first example from part 1. We can see that that code is not well timed at all:

soundLoop:
  
       xor a                    ;4
       dec b                    ;4
       jr nz,skip1              ;12/7
       ld a,#10                 ;7
       ld b,c                   ;4
skip1: 
       out (#fe),a              ;11
  
       xor a                    ;4
       dec d                    ;4
       jr nz,skip2              ;12/7
       ld a,#10                 ;7
       ld d,e                   ;4
skip2:
       out (#fe),a              ;11
  
       dec hl                   ;6
       ld a,h \ or l            ;8
       jr nz,soundLoop          ;12
                                ;78/92t

Due to the two jumps, there are four different paths through the core (no jump taken, jump 1 taken, jump 2 taken, both jumps taking), and the sound loop length thus varies up to 12 t-states - that's more than 15% of the sound loop length, and therefore clearly unacceptable. We need to make sure that the sound loop will always take the same amount of time regardless of the code path taken. One possible solution would be to introduce an additional time-wasting jump:

soundLoop:
  
       xor a                    ;4
       dec b                    ;4
       jr nz,wait1              ;12/7----
       ld a,#10                 ;7
       ld b,c                   ;4
       nop                      ;4-------7+7+4+4=22
skip1: 
       out (#fe),a              ;11
  
       xor a                    ;4
       dec d                    ;4
       jr nz,wait2              ;12/7
       ld a,#10                 ;7
       ld d,e                   ;4
       nop                      ;4
skip2:
       out (#fe),a              ;11
  
       dec hl                   ;6
       ld a,h \ or l            ;8
       jr nz,soundLoop          ;12
                                ;100/100t
                
wait1:
       jp skip1                ;12+10=22
       
wait2:
       jp skip2

There are other possibilities, but I'll leave that for another part of this tutorial.

Row Transition Noise

A common moment for unwanted noise to occur is ironically not during the sound loop, but between notes - the moment when you're reading in new data and updating your counters etc. This is called row transition noise.

Row transition noise is very difficult to avoid. Your focus should therefore be on reducing transition noise rather than trying eliminating it. The key to this is to read in data as fast and efficiently as possible. Not much else can be said about this, except: Make sure you optimize your code. For starters, WikiTI has an excellent article on optimizing Z80 code.

Theoretically, there is a way for eliminating transition noise, though in practise very few existing beeper engines use it (Jan Deak's ZX-16 being a notable example). That way is to do parallel computation, ie. read in data while the sound loop is running. Obviously this is not only rather difficult, but also it is usually only feasible on faster machines - on ZX Spectrum, it will most likely slow down your sound loop too much.

Which brings us to another problem...

Discretion Noise

Discretion noise, also known as parasite tone, commonly takes the form of a high-pitched whistling, whining, or hissing. It inevitably occurs when mixing software channels into a 1-bit output and cannot be avoided. It is usually not a big deal when doing PFM, but can be a major hassle with Pulse Interleaving. The solution is to push the parasite tone's frequency above the audible range. In other words, if you hear discretion noise, your sound loop is too slow. As a rule of thumb, on ZX Spectrum (3,5 MHz) your sound loop should not exceed 250 t-states.

Let's take a look at the asm example from part 4 again. At the end of the sound loop, there is a relative jump back to the start (jr nz,soundLoop). A better solution would be to use an absolute jump (jp nz,soundLoop) instead, because an absolute jump always takes 10 t-states, but a relative jump takes 12 if the jump is actually taken, which we assume to be the case here.

Also, leading up to the jump we have

   dec ix
   ld a,ixh \ or ixl
   jr nz,soundLoop

which takes a whopping 38 t-states. It may be a good idea to replace it with

   dec ixl
   jr nz,soundLoop
   dec ixh
   jp nz,soundLoop

This will take only 20 t-states except when the first jump is not taken. It will introduce a timing shift every 256 sound loop iterations, but this is usually not a major problem, as it happens at a frequency below audible range.

I'll cover some more tricks for speeding up synthesis in one of the following parts.

IO Contention

This section addresses a problem that is specific to the ZX Spectrum. You can most likely skip this section if you're targetting another platform.

IO Contention is an issue that occurs on all older Spectrum models up to and including the +2. The implication is that in certain circumstances, writing values to the ULA will introduce an additional delay in the program execution. You don't need to understand the full details of this, but if you are curious you can read all about IO contention here.

What's important to know is that delay caused by IO contention affects our sound loop timing. Which is bad, as I've explained above. For sound cores with only one OUT command the solution is rather trivial: You just need to make sure that the number of t-states your sound loop takes is a multiple of 8. For ideal sound in cores with multiple OUTs however, the timing distance between each OUT command must be a multiple of 8. Naturally this is pretty tricky to achieve (and chances are your core will sound ok without observing this), but keep it in mind as a general guideline.

Edit 15-12-01: Added/changed info as suggested by introspec.

Part 7: Variable Pulse Width

Alright, if you've come this far, you should be able to write a pretty decent basic 1-bit sound routine. But the real fun of 1-bit coding has only started. From this point on, coding for 1-bit sounds becomes somewhat of an art form - you've got to use your creativity and imagination in order to build a routine that does something out of the ordinary.

I'm by no means an assembly expert, and don't understand half of what all these crazy beeper engines out there are doing. So I can only share those few tricks and techniques that I have so far discovered/reverse-engineered/been told about.

Ok, let's talk about variable pulse width. Varying the pulse width has a number of useful effects, most importantly the ability to produce more interesting timbres when used in conjunction with the pulse interleaving method. (In conjunction with PFM, it can be used to create volume envelopes, but this is not what this part of the tutorial is about.)

Imagine a classic pulse interleaving routine with 16-bit counters, as explained in part 4. The basic procedure for updating a channel's state and counters is:

  counter := base + counter
  IF carry THEN
    state := state XOR ch_toggle
  ENDIF
  OUTPUT state

This will output a square wave with a 50:50 duty cycle, because half of the time the output is 0, and the other half it's 1.
Well, there is another of way of doing this.

  counter := base + counter                       ld hl,nnnn \ add hl,bc \ ld b,h \ ld c,l

  IF counter < 8000h THEN                         ld a,h \ cp #80
    state := off                                  ld a,0 \ jr nc,skip
  ELSE
    state := on                                   ld a,#10
  ENDIF                                    skip:
 
  OUTPUT state                                    out (#fe),a

So, instead of waiting until the counter wraps from FFFFh to 0h, we now check if it has wrapped from FFFFh to 0h or from 7FFFh to 8000h. So in effect we change the state twice as often, but we will still get a 50:50 square wave. Now what happens if we compare against a value other than 8000h? You probably can guess: Yes, that will change our duty cycle. So, to get a 25:75 square wave for example, we'd compare against 4000h, for 12.5:87:5 we compare against 2000h, and so forth. Simple, right?

If only we wouldn't have to deal with that ugly conditional jump that ruins our timing. Well, in Z80 asm there's a handy trick. It is used in Shiru's Tritone, for example.

  ld hl,nnnn \ add hl,bc \ ld b,h \ ld c,l       ;do the counter math as usual
  ld a,h \ cp nn                                 ;compare against our chosen value
  sbc a,a                                        ;A will become 0 if there was no carry, else it becomes FFh
  and #10                                        ;ANDing 10h will leave A set to either 0 or 10h, depending the on previous result
  out (#fe),a

Thanks Shiru, that's a great explanation.
Now there's one thing that I still don't understand myself - if you or someone else has the time, please do explain: How do engines like e.g. Zilog's Squeeker or the infamous Spectone-1 demo (the one in the "hidden" part that can be reached with key A) work?

That's an awesome tutorial we have there! Thank you, I was missing the one on the other forum, but this new version has much more content. I don't understand everything, because I don't know ASM, but it will help to read routine codes.

If it can help some people, I've found this image useful to learn the difference between PFM and PWM:

Wow, very impressive write-up. Congratulations, utz!

You can actually combine those ideas. Let me explain...

Part 9: More Soundloop Tweaks

In this part, I'll discuss two advanced tricks that you can use to open up new possibilities and further speed up your sound loops. I've learned these tricks from code by introspec and Alone Coder, respectively.

Accumulating Pin Pulses

The first trick applies to the PFM/pin pulse method of synthesis. First, let's take a look again at our PFM engine code from Part 5, and modify it to use 16-bit counters.

BC = base frequency channel 1
IX = freq. counter ch1
DE = base freq. ch2
IY = freq. counter ch2
HL = timer

soundLoop:
       add ix,bc                ;update counter ch1
       sbc a,a                  ;A = #FF if carry, else A = 0
       and #10                  ;A = #10 || A = 0
       out (#fe),a              ;output state ch1
       
       add iy,de                ;same as above, but for ch2
       sbc a,a
       and #10
       out (#fe),a
       
       dec hl                   ;decrement timer
       ld a,h
       or l
       jp z,soundLoop           ;and loop until timer == 0

Now, instead of outputting the pin pulses immediately after the counter updates, we can also "collect" them. This will potentially save some time in the sound loop and will give better sound, because the pin pulses will be longer.

In the following example, register A holds the number of pulses to output, and A' will hold #10.

soundLoop:
       add ix,bc                 ;counter.ch1 := counter.ch1 + basefreq.ch1
       adc a,0                   ;IF carry, increment pulseCounter
       
       add iy,de                 ;counter.ch2 := counter.ch2 + basefreq.ch2
       adc a,0                   ;IF carry, increment pulseCounter

       or a
       jp nz,outputOn     
       out (#fe),a              ;OUTPUT state
       nop\nop\nop              ;adjust timing
       
                                ;now we can't use A to check the counter, hence...       
       dec l                    ;decrement timer lo-byte
       jp z,soundLoop           ;and loop if != 0
                                ;this is faster on average anyway, so use it whenever you can.      
       dec h
       jp z,soundLoop           ;and loop until timer == 0
       
outputOn:
       ex af,af'
       out (#fe),a
       ex af,af
       dec a                    ;decrement pulseCounter
       
       dec l                    ;decrement timer lo-byte
       jp z,soundLoop           ;and loop if != 0
                                ;this is faster on average anyway, so use it whenever you can.      
       dec h
       jp z,soundLoop           ;and loop until timer == 0

Even better, you can use this trick to simulate different volume levels, by adding a number >1 to the pulse counter on carry. Just don't overdo it, because eventually the engine will overload, ie. it will take too long until the engine works through the "backlog" of pulses to output. This method is used in OctodeXL, btw.

Skipping Counter Updates

You have a great idea for a sound core, but just can't get it up to speed? Well, here's a trick you can use to make your loop faster.
This trick is mostly relevant to pulse-interleaving engines with more than 2 channels.

The idea here is that you don't have to update all counters on each iteration of the sound loop. It is however important that you output all the states every time,
and that the volume (read: time taken) of each of the channels is equal across loop iterations.

Here's a theoretical, not very optimized example.

DE  = base frequency ch1
IX  = counter ch1
H   = output state ch1
SP  = base frequency ch2
IY  = counter ch2
L   = output state ch2
B   = timer

       ld hl,0                    ;initialize output states
       ld c,#fe                   ;port value, needed so we can use out (c),r command
       
soundLoop:
                         ;---LOOP ITERATION 1---
       out (c),h         ;12      ;OUTPUT state ch1
                         ;^ch2: 40
       add ix,de         ;15      ;counter.ch1 := counter.ch1 + basefreq.ch1
       out (c),l         ;12
                         ;^ch1: 27
       sbc a,a           ;4       ;IF carry, toggle state ch1
       and #10           ;7
       ld h,a            ;4
       ld a,r            ;9       ;adjust timing
       nop               ;4
 
                         ;---LOOP ITERATION 2--- 
       out (c),h         ;12
                         ;^ch2: 40
       add iy,sp         ;15      ;counter.ch2 := counter.ch2 + basefreq.ch2
       out (c),l         ;12
                         ;^ch1: 27
       sbc a,a           ;4
       and #10           ;7       ;IF carry, toggle state ch2               
       ld l,a            ;4
       djnz soundLoop    ;13      ;decrement timer and loop if !0

Just noticed that this needs a tiny correction. This advice is only correct when the sound loop contains only a single OUT command. In the case when there are several OUT commands, this won't be good enough. What you actually need to ensure is that the timings from any OUT command in your sound loop to any other OUT command in your sound loop is a multiple of 8. This automatically ensures the number of t-states in the sound loop is a multiple of 8, but this is, generally speaking, a stricter requirement.

I think it depends on the type of mixing that you use. The engines with narrow spikes, e.g. Tim Follin engines or Shiru's "Octode" are less sensitive to it, so for them it maybe difficult to even notice the difference. However, for longer duty cycles, e.g. "Savage", the difference is clear and pronounced. Due to relatively low quality of the beeper sound the distortions produced by the contention may be considered insignificant, however, they are easy to hear and are very unmusical, because they result in unstable timing, as well as introduce a 50Hz component into the sound.

I never did everything I hoped to do with the "Savage" due to the lack of time. When I find the time, I will rebuild the classical "Savage" tunes with the new engine, so that everyone can see what's the big deal.

OK, got you, will try to do it when I have a bit more time.

Ok, then we have no choice but to duel it out
I just had a glance at my 7d7 engines, seems it would be possible in more cases than I thought, though I don't see it for all of them, namely not quattropic and xtone (and especially the latter would actually benefit greatly from it). Well, I'll definately give it more thought in the future, though I'm still not totally convinced. As a matter of fact, I've got a new, very fast wavetable player in the works where it definately won't work, as the sound core consists of little more than repeatedly doing out (#fe),a, rrca