Calling and loading audio

Read the output's manifest.json; addresses are not interchangeable between module.bin and player.bin. Assemble again to relocate. Public API offsets from audio_api are fixed: init +0, AY4/5k +3, AY4/6k +6, DPCM3/6k +9, AY start +12, AY tick +15, stop +18. Generated absolute labels are also exported.

Memory and hardware

CPU: 3,528,000 Hz. AY: 1,764,750 Hz. Display interrupts: approximately 60.1145 Hz; Fuse frame arithmetic uses 58,688 T states. Select register using $FFF5, write using $FFF6. This player owns sound registers R0–R13 and does not write joystick registers R14/15. One/two-channel conversion mutes unused channels; it is not a concurrent AY channel mixer.

Small cartridge demo: HSR $30 selects only contiguous DOCK4/5 ROM. $FF=0 selects HOME/DOCK rather than EXROM and primary display. Screen files occupy HOME $4000–$5AFF and $6000–$7AFF; second display is demo animation only. Native RAM $C000–$C100 is the 257-byte IM2 table, with JP stub at $C1C1 outside it. State is $C210–$C21F. Stack starts at $FF00. Never select DOCK6 or DOCK7 for writable state. DCK descriptors 1/3 are not a substitute for physical RAM on PicoROM-28.

Expanded comparison cartridge

aydemo DCK output uses contiguous ROM chunks 0–7 (64K total). Resident code is in chunk 4, $8000–$9FFF; baseline HSR is $10. The other seven chunks provide 56K of audio and compressed UI storage. All DCK chunk descriptors are ROM-only (2), and picorom.bin maps bytes directly to physical addresses.

Native HOME RAM holds wave frames at $A000–$A7FF, the IM2 table at $C000–$C100, the vector stub at $C1C1, audio state at $C210, wave pointer at $C220 and UI state from $C230. SP starts at $C2FF. Audio records are copied to $D000–$FDFF before playback (maximum 11,776 bytes per record). The normal bounce buffer is $7C00; source chunk 3 instead uses $5B00.

Version 3 uses optional lossless LZ storage for audio records. A compressed record is first loaded at $D000, copied to native $A800–$BFFF (maximum 6144 bytes), then expanded back into $D000–$FDFF. All banks are restored before decompression. The original playback stream is preserved exactly. Records that do not shrink or do not fit the compression scratch buffer remain raw. The record-compression table and ui+16 hold the flag; source code documents literal/backreference tokens. Menu RLE records remain unchanged. Manifest stored_bytes is physical audio storage; bytes is the expanded stream size.

The loader disables interrupts, selects a source chunk alongside resident chunk 4, copies at most 256 bytes to the bounce buffer, then restores HSR10. Only after restoring HOME does it access the stack or copy into the destination staging buffer. This matters especially when chunk 6 hides the native stack and state. The banked interval uses straight-line OUT/LDIR/OUT, without CALL, PUSH, POP or interrupt access. Each record may cross physical chunk boundaries.

The AY/idle ISR copies a 128-byte sine frame per display interrupt. DAC loops copy eight bytes at a time within balanced 340 T slots, only during the known early blanking window. Keep the supplied ISR synchronization and timing checks when changing this demonstration. These are prepared sine frames, not decoded audio visualizations. The standalone callable runtime has no such dependency.

With --spectra, ui+17 holds the S-key view selector. Each audio entry has an additional 64-byte record: 32 original and 32 modeled FFT bar heights 0..31. A shared RLE lower-screen template follows those records. The selected codec glyph row is copied to the spectrum header; two-pixel bars are drawn in native screen RAM while interrupts are disabled during redraw. This occurs only on selection/view changes. Spectrum state and loading add no per-sample or ISR work. spectrum_ui.py documents the display addresses; spectrum.py performs all FFT/modeling work on the host. Spectrum screens still need the declined Fuse check; assembly and offline numerical validation are separate evidence.

Callable modules do not initialize IM2, change HSR, or initialize SP. They reserve the 16 state bytes above. audio_init/audio_stop restore standard video mode via port $FF; applications using ECM should adapt that line or restore their mode after stopping. Exact DAC timing assumes code, data and stack in uncontended address ranges (normally $8000+, or ROM below $4000). The builder allows code origins $6000–$BFFF, but $6000–$7FFF is contended and is not suitable for cycle-exact DAC or the two-screen demo.

Digitized playback

        di                      ; do not interrupt a sample loop
        ld hl,CLIP_ADDRESS      ; manifest data_address + entry offset
        ld de,CLIP_GROUPS       ; entry count, NOT bytes or samples
        call DAC6               ; use generated api.inc
        ei                      ; caller decides whether to re-enable

The routine initializes the AY DAC, plays, silences it and returns with interrupts still disabled. It clobbers AF, BC, DE, HL, IX and IY. A zero count returns without reading data. audio_init and the DAC functions preserve no general caller state beyond their explicitly supplied parameters. No code is self-modifying and all mutable state lives in HOME RAM.

AY4 low-nibble-first: AY4/5k groups are 10 samples/5 bytes; AY4/6k groups are 2 samples/byte. Both store actual logarithmic AY volume codes, not linear PCM. DPCM3 groups are eight 3-bit codes packed LSB-first into three bytes. Start at AY level 11; each code indexes deltas [-4,-2,-1,0,1,2,4,8], then clamp to 0..15. Reset the accumulator for each clip. Tail groups are padded; the manifest reports exact source sample count and padded duration.

The standalone reference routines have no animation. The demo's generated variant waits for one display interrupt and keeps a 58,688 T software phase. It changes display file only in the first group after frame wrap, within blanking, and balances both branches to 133 T. Its ISR must complete in under about 5,000 T before the initial return; the provided demo does. Do not copy this synchronization into an arbitrary application's long ISR unchanged. Unrestricted memory/ULA writes inside DAC padding introduce contention.

Interrupt AY playback

        di
        call AUDIO_INIT
        ld hl,CLIP_ADDRESS
        ld de,FRAME_COUNT
        call AY_START
        ei

my_isr:
        push af
        push bc
        push de
        push hl
        call AY_TICK             ; once per DISPLAY interrupt, not game tick
        ; Other bounded interrupt work can go here.
        pop hl
        pop de
        pop bc
        pop af
        ei
        reti

ay_start: HL=data, DE=frame count; publishes state and active flag under DI. ay_tick: clobbers AF/BC/DE/HL; does not enable interrupts or return with RETI. Each frame contains exactly 14 bytes R0..R13. R13=255 means skip the write, not write 255: a real shape write restarts the shared envelope. It writes R0..12 every active update. The last frame remains sounding for one full interrupt period; the following tick silences the chip and clears active byte $C215. Poll that byte, not remaining-frame count, for completion. audio_stop immediately mutes volumes and clears active/count. Serialize init/start/stop with the ISR. No nesting or thread safety is provided.

Reloadable libraries

With --separate-data, load module.bin at origin and data.bin at the manifest's data_address. Stop playback under DI before overwriting data. The default data buffer is $D000; the builder accepts $C300–$FDFF and checks the entire payload fits. Reload another generated raw data file there, then call the appropriate entry with the new offset/count. No absolute pointers are stored in the payload, so its contents are location independent. The module is origin-dependent. Loading tape/files and keeping metadata are the host program's responsibility; never load over an actively playing buffer.