Playing Digitised Samples Through POKEY

Atari text screen headed TIMER IRQ SAMPLE PLAYER, with horizontal stripes of brown and orange shades in the border

Every POKEY voice has a 4-bit digital-to-analogue converter hiding behind its volume setting. Set bit 4 of an AUDC register and POKEY stops generating a tone on that voice: whatever value sits in the low four bits goes straight to the output. Change that value thousands of times a second and the speaker reproduces recorded sound, from drum hits and speech to whole songs. Advanced POKEY shows the principle with a 16-step loop. This guide goes the rest of the way: real sample data, packing it into memory, choosing a rate, and timing playback properly.

What you'll learn: how volume-only output behaves, how to convert and pack a sample, three ways to time playback (delay loop, WSYNC and timer interrupts), and a tested interrupt-driven player that leaves the screen and your main program running.

What you need: an assembler (the listings are for MADS), Python 3 for preparing data, and an emulator or real machine. Any Atari 8-bit with at least 32K of RAM will do.

1. Volume-only output

With bit 4 of AUDC set ($1x), the voice's frequency divider, noise generators and filters are ignored and the output is held at volume x. Writing a new value moves the speaker cone to a new position and leaves it there until the next write. So each write is one sample, and the time between writes sets the sample rate.

Some details from the hardware worth knowing:

  • Sixteen levels is all you get. The steps are not quite even either: the gaps between levels 3 and 4, 7 and 8, and 11 and 12 are a little wider than the rest.
  • POKEY's mixer is roughly linear only up to a combined volume of about 15. Use one voice for a sample and keep the other voices quiet or low, or the peaks are squashed.
  • Volume-only voices always add together, unlike tone voices, where voices 1 and 3 can cancel out.
  • Changing a voice's level shifts its DC output. Start and finish a sample near its resting level (8 for most data) to avoid a click.

2. Preparing a sample

Sample playback is mostly a memory problem. Each sample needs four bits, so the usual trick is to pack two samples per byte, high nibble first. Ed Stuart's "Talk Is Cheap" (Antic, July 1983) did exactly that. His program digitised speech through a joystick port and recorded about 4,500 samples per second into a 16K buffer from $4000 to $7FFF. Here is what packed data costs at the rates used later in this guide:

Rate (NTSC) How it is timed Bytes per second Seconds in 16K
3,995 Hz Timer, AUDF1 = 15 about 2,000 8.2
7,850 Hz WSYNC, every 2nd line about 3,925 4.2
7,990 Hz Timer, AUDF1 = 7 about 3,995 4.1
15,700 Hz WSYNC, every line about 7,850 2.1

Stuart's speech at 4.5 kHz was recognisable but hissy. Higher rates sound clearer and cost proportionally more memory.

To convert a recording, resample it on a PC to mono, 8-bit unsigned, raw (headerless) data at your playback rate. sox or Audacity will do it. Two tips from experienced sample coders: apply a low-pass filter at half the playback rate before resampling, to avoid aliasing, and normalise the sound first, so that it uses the whole range and doesn't end up as three effective bits. If you export a WAV file instead of raw data, cut off its 44-byte header. Then this Python script rounds the samples to four bits and packs them:

import sys
raw = open(sys.argv[1], 'rb').read()          # 8-bit unsigned mono samples
nib = [min(15, (b + 8) >> 4) for b in raw]    # round to 4 bits (0-15)
if len(nib) % 2:
    nib.append(8)                             # pad with a mid-level sample
packed = bytes(nib[i] << 4 | nib[i + 1] for i in range(0, len(nib), 2))
open(sys.argv[2], 'wb').write(packed)
print(len(raw), 'samples ->', len(packed), 'bytes')

The examples below use a synthetic "boing" made the same way: a falling 440 Hz tone with a decaying envelope, 8,192 samples packed into 4,096 bytes. They play it from a page-aligned buffer at $3000 and loop it forever.

3. Timing method 1: a delay loop with the screen off

The simplest player outputs a sample, burns a fixed number of cycles, and repeats. The delay sets the rate. Count the cycles of the whole loop, including the branch back, and divide 1,789,773 (NTSC) or 1,773,447 (PAL) by the total to get samples per second.

Two things wreck that timing. ANTIC's screen DMA steals cycles at irregular points in every scan line, and the vertical blank and display list interrupts take the CPU away for long stretches. Delay-loop players therefore blank the screen (store 0 in DMACTL, $D400) and disable interrupts (SEI, plus 0 in NMIEN, $D40E, and IRQEN, $D20E). Bob Fraser's VONLY example in De Re Atari and Stuart's speech program both work that way. The listing in Advanced POKEY is a complete example of this method.

4. Timing method 2: WSYNC

Writing any value to WSYNC ($D40A) halts the CPU until the horizontal blank at the end of the current scan line. A sample written right after a WSYNC therefore lands at exactly the same point in every line, and DMA cannot disturb it. One write per line plays at the scan-line rate: 15,700 Hz on NTSC and 15,557 Hz on PAL. Two WSYNCs per sample halve that. The screen can stay on, but the vertical blank and DLIs must be off, and the CPU spends the whole sample playing it:

; WSYNC-paced sample loop: one sample every two scan lines
AUDC1   = $D201
AUDCTL  = $D208
SKCTL   = $D20F
IRQEN   = $D20E
NMIEN   = $D40E
WSYNC   = $D40A
COLBK   = $D01A
ptr     = $CB

        org $2000
start   sei             ; no IRQs...
        lda #0
        sta IRQEN
        sta NMIEN       ; ...and no VBI/DLI to disturb the timing
        sta AUDCTL
        lda #3
        sta SKCTL
again   lda #<sample
        sta ptr
        lda #>sample
        sta ptr+1
        ldy #0
loop    lda (ptr),y
        tax
        lsr
        lsr
        lsr
        lsr
        ora #$10
        sta WSYNC       ; wait for the end of a scan line
        sta WSYNC       ; and another: about 7.8 kHz
        sta AUDC1
        sta COLBK
        txa
        and #$0F
        ora #$10
        sta WSYNC
        sta WSYNC
        sta AUDC1
        sta COLBK
        iny
        bne loop
        inc ptr+1
        lda ptr+1
        cmp #>sample_end
        bne loop
        beq again       ; play it forever

        org $3000
sample  ins 'boing.bin'
sample_end

        run start

The sta COLBK lines are a free oscilloscope: each sample also sets the background colour. Fed with test data that alternates 0 and 15, this loop paints stripes exactly two scan lines high in atari800, confirming one sample per two lines.

5. Timing method 3: a POKEY timer interrupt

The most flexible method lets POKEY keep time. With AUDCTL = 0, voice 1's divider counts the 64 kHz clock (63,920 Hz on NTSC, 63,337 Hz on PAL) and underflows every AUDF1 + 1 ticks. With bit 0 set in IRQEN, every underflow raises an IRQ. AUDF1 = 7 gives 7,990 interrupts a second on NTSC (7,917 on PAL), and AUDF1 = 15 gives 3,995 (3,959 on PAL). Voice 1 is used only as a timer, with its volume at 0, and the sample plays on voice 2.

The OS offers a timer-1 vector, VTIMR1 at 528 ($210), but the OS IRQ handler checks the serial-port interrupts before it gets there. Counted in atari800 with the Graphics 0 screen on, a handler hooked into VTIMR1 receives only about 6,670 of the expected 7,940 interrupts per second on PAL; on NTSC it loses a similar share. The missing ones fell due while the CPU was still busy with the previous one, and POKEY has only one status bit per timer to remember them. Taking over the main IRQ vector, VIMIRQ at 534 ($216), and handling timer 1 first recovers all of them (7,944 counted). So that's what this player does, passing every other interrupt on to the OS:

; Timer-IRQ sample player: packed 4-bit samples, screen stays on
AUDF1   = $D200
AUDC1   = $D201
AUDC2   = $D203
AUDCTL  = $D208
STIMER  = $D209
IRQEN   = $D20E         ; write: IRQ enable
IRQST   = $D20E         ; read: IRQ status (0 bit = pending)
SKCTL   = $D20F
COLBK   = $D01A
POKMSK  = $10           ; OS shadow of IRQEN
SAVMSC  = $58           ; screen memory address
VIMIRQ  = $0216         ; main IRQ vector
CH      = $02FC         ; last key pressed
ptr     = $CB           ; 2 bytes: current sample byte
half    = $CD           ; 0 = high nibble next, 1 = low nibble next

        org $2000
start   ldy #0          ; put a title on the screen
msg     lda text,y
        bmi go
        sta (SAVMSC),y
        iny
        bne msg
go      sei
        lda #<sample
        sta ptr
        lda #>sample
        sta ptr+1
        lda #0
        sta half
        sta AUDCTL      ; 64 kHz base clock
        sta AUDC1       ; voice 1 is only a timer: keep it silent
        lda #3
        sta SKCTL       ; POKEY out of init mode
        lda #7
        sta AUDF1       ; 63921/(7+1) = 7990 IRQs/s (NTSC)
        lda VIMIRQ      ; keep the OS handler for other IRQs
        sta oldirq
        lda VIMIRQ+1
        sta oldirq+1
        lda #<irq
        sta VIMIRQ
        lda #>irq
        sta VIMIRQ+1
        lda POKMSK
        ora #$01        ; enable timer 1 interrupt
        sta POKMSK
        sta IRQEN
        sta STIMER      ; restart all POKEY timers
        cli
        lda #255
        sta CH
wait    lda CH          ; main program is free: wait for a key
        cmp #255
        beq wait
        sei
        lda POKMSK
        and #$FE        ; timer 1 interrupt off
        sta POKMSK
        sta IRQEN
        lda oldirq      ; give the vector back
        sta VIMIRQ
        lda oldirq+1
        sta VIMIRQ+1
        cli
        lda #0
        sta AUDC2
        jmp ($0A)       ; DOSVEC

irq     pha
        lda IRQST
        lsr             ; bit 0 clear = timer 1 fired
        bcs notme
        lda POKMSK      ; acknowledge: clear and re-set
        and #$FE        ; the enable bit
        sta IRQEN
        lda POKMSK
        sta IRQEN
        tya
        pha
        ldy #0
        lda (ptr),y
        ldy half
        bne lo
        lsr             ; high nibble first
        lsr
        lsr
        lsr
        inc half
        bne out         ; always taken
lo      and #$0F        ; then the low nibble
        dec half
        inc ptr         ; next byte
        bne out
        inc ptr+1
        ldy ptr+1
        cpy #>sample_end
        bne out
        ldy #>sample    ; end reached: loop the sample
        sty ptr+1
out     ora #$10        ; volume-only bit
        sta AUDC2
        sta COLBK       ; show the level in the border
        pla
        tay
        pla
        rti
notme   pla             ; not ours: let the OS handle it
        jmp (oldirq)

oldirq  dta a(0)
text    dta d'TIMER IRQ SAMPLE PLAYER',$FF

        org $3000       ; page-aligned, 4096 bytes
sample  ins 'boing.bin'
sample_end

        run start

Points to notice:

  • Acknowledging the interrupt. A POKEY IRQ stays pending until its enable bit is cleared, so the handler writes IRQEN without bit 0 and then restores it, using the OS shadow POKMSK (location 16) so the keyboard and serial interrupts stay as the OS left them.
  • Unpacking. The half flag alternates between the high and low nibble. The pointer only advances after the low nibble.
  • SKCTL must be 3. If POKEY is left in initialisation mode (SKCTL bits 0–1 clear), its 64 kHz clock is frozen and the timer never fires.
  • Restart with STIMER. Writing STIMER ($D209) reloads all the dividers, so the first interrupt comes one full period later.

Troubleshooting

  • Nothing plays. Check SKCTL = 3, that the IRQEN bit is set in both POKMSK and IRQEN, and that CLI was executed.
  • The sample plays slow and low. Interrupts are being lost. Hook VIMIRQ rather than VTIMR1, shorten the handler, or lower the rate.
  • Crackle and wobble with a delay loop. DMA or interrupts are still active. Turn them off, or switch to WSYNC or a timer.
  • The keyboard stops working. You wrote IRQEN directly without keeping POKMSK in step.
  • Playback stops during disk access. The OS serial routines reprogram POKEY, so stop the sample before any SIO call and restart it afterwards.
  • PAL and NTSC sound different. The clocks differ by about 1%, so the same AUDF value plays about 1% slower on PAL.

Further reading

  • De Re Atari (Atari, Inc., 1982), Chapter 7: "Volume Only Sound" and the VONLY program.
  • Ed Stuart, "Talk Is Cheap", Antic, July 1983: speech through a joystick port, with packed samples.
  • Matthew Ratcliff, "Covox Coach", Antic, May 1989: adding digitised speech from the Covox Voice Master Junior to your own programs.
  • Avery Lee, Altirra Hardware Reference Manual, Chapter 5: volume-only mode, the DAC and timer behaviour in detail.
  • On this site: Advanced POKEY, Vertical Blank Interrupts, Realtime Clock and Timers and Getting Started with RASTER Music Tracker.

Credits