Files

6.7 KiB
Raw Permalink Blame History

Sound Lab packet contract

The generator authors new diagnostic packets. It does not copy a manual's BASIC listings, include ROM bytes, call an emulator-private interface, or alter the SDK. Run it with the standard Python library:

python3 examples/sound-lab/vectors/generate.py --output .build/sound-lab/generated
python3 -m unittest discover -s examples/sound-lab/tests -p test_vectors.py -v

vectors.json records exact command-port bytes, byte counts, SHA-256 and CRC-16/CCITT-FALSE for each stable case ID. vector_set_crc16 covers those bytes concatenated in manifest order. Its checksum is an identity, not a claim that a cartridge produced the intended sound. The manifest SHA covers canonical sorted JSON before its own manifest_sha256 property is appended.

vectors.h is generated into the requested output folder. Each SoundVector has id, title, prompt, tx, length, crc16, wait_mask, hold_ticks, and group. Group bits are 1 showcase, 2 short guided lab, 4 engineering sweep. The titles and prompts fit the guest's 32-column presentation with wrapping. The wait_mask conventions are current SDK/model observations: 40 speech idle, 20 sound idle, 60 both. They must be logged as observations and never used to infer physical cartridge presence. hold_ticks adds a bounded observation time before the runner sends a safety stop. An NTSC60Hz tick assumption belongs in the report; a PAL machine must be identified separately.

Before each TX byte, including terminators, poll ready80 at FF7E with a bounded timeout. The runner owns reset, machine/sound routing preservation, timeout recovery, report I/O, manual sound checks and the safety stop after every case. The runner must record any timer/reset/control prelude and cleanup separately from these vector bytes so their receipt does not silently disagree with actual bus traffic. Use the same prelude, TX bytes and cleanup on all three platforms. Reset/control operations are not inferred from the text of a listening prompt.

Source qualification

The primary publication is Tandy's1984 owner's manual. sources.json identifies the retrieved54-page2004 Tim Lindner OCR/typeset reproduction by URL, SHA-256 and byte count. This is a reproduction of the primary publication, not a photographic scan. The command-table, direct-register and event-grammar page pixels were rendered and inspected. Original-paper/photographic comparison remains pending; that limitation must remain visible in the build's qualification notes.

The Archive's old filename no longer downloads. Its currently downloadable Speech-Sound Cartridge Manual (Tandy).pdf is a newer57-page re-typeset edition. It is retained only as discovery evidence and is not silently substituted for the edition/page numbering cited here. No PDF is tracked or included on disk.

The primary source contains inconsistencies. Printed24 says register1–13 in introductory prose but its table, note and printed25 example use register0. Appendix B describes R8–R10 bit4 for envelope amplitude although the compact printed24 table only lists fixed amplitudes0–15. Printed19 contains contradictory parenthetical wording about noise replacement; the explicit Byte2 bit7 paragraph defines retain-previous-amplitude behavior. We preserve these qualifications rather than inventing undocumented commands.

Source-qualified packet grammar

All numbers below are hexadecimal. Sources are printed pages in the54-page edition, with1-based PDF page equal to the printed page.

Operation Bytes Primary source
Immediate text printable uppercase ASCII, space,0D pp9–11; space is Sound Lab's explicit flush policy
Stored text slot n 90+n, text, space,0D; execute D0+n Appendix A pp26–28
Allophone slot n B0+n, codes00–3F, final pause00–04,FF; execute F0+n pp13–14, Appendix A pp27–29
Sound slot n 98+n, complete events,FF; execute D8+n pp15–20, Appendix A pp26–29
Register-string slot n B8+n, register/value pairs,FF; execute F8+n Appendix A pp28–30
Direct AY register writes AF, register,value pairs,FF pp24–25, Appendix A p27
Timer base 8F,value00–FF Appendix A p26
Speech stop C7 Appendix A p28
Sound stop CF Appendix A p28
Stop both, retain buffers 00 Appendix A p30

Slots n range0–7. Text/allophone representations use the same eight speech slots. Sound events/register strings use the same eight sound slots. Consecutive multi-buffer operations exist but are deliberately outside this initial single-slot packet validator. Its conservative maximum64-byte body includes the terminator. It rejects overflow instead of relying on firmware truncation.

Tone event: channel00/20/40 OR amplitude00–0F (or envelope bit10), coarse00–0F, fine00–FF,duration00–FF. Noise event:80/A0/C0 OR amplitude, period00–1F with optional retain-amplitude bit80,duration. Envelope event:60 OR shape00–0F, coarse00–FF,fine00–FF,duration. The manual also permits bit7 set on the envelope operation; Sound Lab uses the simpler60 family.

An FF at a sound-event boundary ends the stream. FF consumed as a tone fine period, duration or envelope operand is data. In direct/register strings, FF is an end marker only where a register number is expected; a register's value may be FF when its field width permits it. It is not correct to split all packets at the first FF byte.

Event duration is the interval before the next event; it does not turn off the final note. Finite vectors include explicit amplitude-zero events. REG01, REG02 and MIX01 deliberately hold an audible output, then depend on the runner's bounded stop. TIM01 intentionally changes the timer base; the runner resets or restores a declared baseline between cases. Absolute milliseconds, ready-poll counts, intonation, analog waveform fidelity and comparative envelope shape are MEASURE_BASELINE, never an invented source pass.

Existing SDK conventions kept separate

The source of the current SDK helpers is useful integration evidence, not a substitute for the publication. Its text62-character cap and appended space are conservative API rules. Its cold one-shot envelope prime/retrigger sequence is an implementation workaround: these vectors instead issue the documented envelope-enabled tone immediately followed by its envelope event. Allophone mnemonics are labels only; an observed or heard sound still needs a HUMAN result.

The generator's eight stored speech and eight stored sound cases exercise slot addressing independently. The64 allophone cases include five explicit silent pause cases. The16 envelope cases request each shape without asserting that the current emulator or future FPGA is already physically accurate. No audible or real-hardware validation is claimed by successful Python tests.