Playing Digitised Samples Through POKEY
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
halfflag 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
- Picture: The timer-IRQ player from section 5 in atari800. Each sample is also written to the border colour, so the stripes trace the waveform. — Program authors; screenshot by the site
- De Re Atari, Chapter 7: Sound (Volume Only Sound) — Bob Fraser (Section 7 of De Re Atari)
- Altirra Hardware Reference Manual (Avery Lee), Chapter 5: volume control, volume-only mode, high-pass, initialization mode, clock table (Table 9); Chapter 4 scan-line rates — Avery Lee (Altirra)
- Mapping the Atari (revised) — 16 POKMSK, 528 VTIMR1, 534 VIMIRQ, 53768 AUDCTL, 53769 STIMER, 53774 IRQEN — AtariArchives.org
- Atari 400/800 OS rev. A source listing (ksquiggle mirror) — IRQ handler SYIRQ: dispatch order, VTIMR1 jump with A on stack — ksquiggle
- Ed Stuart, Talk Is Cheap — Antic, July 1983 — Ed Stuart; AtariMagazines.com (Kevin Savetz), 1983
- Matthew Ratcliff, Covox Coach and Yak-Spell — Antic, May 1989 — AtariMagazines.com (Kevin Savetz), 1989
- AtariAge — Looking routine to play sample sounds (packed nibble loops, WSYNC/timer rates, conversion advice) — AtariAge forum members
- AtariAge — POKEY TIMER INTERRUPTS (VTIMR1 handler, custom VIMIRQ advice) — AtariAge forum members
- AtariAge — RMT during SIO? (OS SIO resets sound registers) — AtariAge forum members
