Files

8.4 KiB
Raw Permalink Blame History

Sound Lab — diagnostic disk

Sound Lab is a standalone, keyboard-driven CoCo program for comparing the Tandy Speech/Sound Cartridge in VCC Plus, on a real CoCo, and eventually in the research FPGA core. It does not change VCC Plus's speech/sound implementation. This first disk provides a useful listening baseline; coverage identifies the larger diagnostic specification's remaining work explicitly.

Start here

Keep SOUNDLAB.DSK as an unchanged master. Make a writable copy for each test environment. The disk is ordinary single-sided Disk BASIC: 35 tracks, 18 sectors per track, 256 bytes per sector, 161,280 bytes in total. No cartridge ROM is in the disk or delivery archive.

  1. Use a 64-KiB-or-larger CoCo, Disk BASIC, a Speech/Sound Cartridge and normal CPU speed. Start with low speaker volume. In VCC Plus, use Disk BASIC with the Speech/Sound Cartridge configured. Do not use an OS-9 preset.
  2. Insert the writable disk in FD0, then type DOS and press Return. Alternatively type RUN"SOUNDLAB". The supplied BASIC loader uses PCLEAR1 and CLEAR32 before loading the machine-language program at $1600. Do not bypass that setup with a bare LOADM in an arbitrary existing session.
  3. Choose the platform, CoCo model and NTSC/PAL setting. These are descriptions, not automatic cartridge detection. Confirm your own physical cartridge, MPI arrangement and speaker path separately. The program does not switch MPI banks or enable double-speed mode.
  4. Choose D to save reports to the writable FD0 copy, or M for screen-only operation. Use the diagnostic disk, never an important software/data disk.
  5. Start 1 — Meet the Robot. The brief showcase includes a greeting, a tone, rising notes, a chord, noise, a small original tune and a spaceport voice. 2 selects more guided examples. 3 requires explicit confirmation for the larger engineering set. 4 runs a case ID from the manifest.

Disk loading and simultaneous cartridge use require compatible hardware routing, usually a Multi-Pak plus disk controller. Do not hot-swap powered cartridges to work around a single cartridge slot. Screen-only mode suppresses report disk I/O; it does not invent a new way to load the program.

Listen, repeat and recover

Read the listening prompt, then press Return to play (or X for the menu). Each result waits for your response:

Key Meaning
H Heard the expected example
W Heard something wrong
N No sound
U Unsure
R Record this attempt and repeat the example
S Skip
T Add a short note, then choose a result
X Return to the menu; also interrupts bounded playback waits

The first five allophone addresses are pauses: silence is intentional. Three AY tone channels mix to mono; they are not three stereo positions. A saved AUTO=OBSERVED describes register/timing observations, not successful listening. Only your response supplies HUMAN=HEARD. Test timing is in video-frame ticks; PAL/NTSC, polling overhead and firmware latency prevent treating it as calibrated audio duration. Analog tolerances remain MEASURE_BASELINE.

Sound Lab resets the cartridge at each case's beginning to establish a consistent timer/buffer baseline. It records that prelude separately from the vector bytes. It sends the documented stop-both command after each case, or resets after an interrupted/unfinished packet or timeout. The cartridge's stored buffers are diagnostic scratch space. Q saves the final report, resets the cartridge and returns to BASIC with the saved PIA audio routing restored. It leaves the CPU speed and MPI selection alone. The loader's text mode/graphics-page allocation is part of this standalone program, not a preserved running CoCo application.

Reports

The program reserves unused SND0001.TXT, SND0002.TXT, … filenames. Existing reports are never intentionally replaced. It flushes observations between cases, not during sound playback. The small CoCo RAM log rolls into additional numbered files; retain all of them. The displayed attempt number is a session sequence and distinguishes repeats and later re-selection of the same case.

Keep the disk inserted during a session. Before updating a checkpoint, the program checks the saved file's bytes against its prior checkpoint. A changed or swapped file is refused with error250. Disk errors leave the current RAM log available: use 5 to page/photograph it, or 6 to retry saving after fixing the original media problem. A partially failed physical write may require keeping the RAM photographs rather than retrying over an uncertain file. Do not swap a different disk into the open report. No formatting or repair is attempted.

In screen-only mode, a full log pauses before the next case. Photograph its pages before explicitly choosing C to clear it for another report segment. X keeps it and returns to the menu. There is no silent log eviction.

Safely save/eject the disk in VCC Plus, or transfer the physical disk image using your normal hardware workflow. Work from a saved host copy:

python3 host/soundlab_reports.py extract MYTEST.DSK --output extracted
python3 host/soundlab_reports.py convert extracted/SND0001.TXT \
  --output readable --manifest SOUNDLAB-manifest.json

See host report instructions for comparison and JSON/CSV/HTML exports. Keep the original modified DSK, raw TXT files, manifest and any WAVs or photographs. The pristine disk hash changes when reports are saved; this is expected and does not invalidate the original build receipt.

Optional WAV analysis accepts manually marked intervals and measures signal levels, clipping and qualified isolated-tone estimates. It never relabels measurements as human listening or analog hardware acceptance.

Rebuild and validate

In the VCC Plus repository:

python3 examples/sound-lab/build.py
python3 -m unittest discover -s examples/sound-lab/tests -v

For the isolated real-ROM run, use the retained core library and explicit private ROM folder (these inputs are never copied into the delivery):

python3 examples/sound-lab/check.py \
  --core .build/371-release-native/Build/Products/Release/libVCCCore.a \
  --roms platforms/macos/LocalResources/ROMs

The default output is .build/sound-lab. An exported project accepts explicit --toolchain /path/to/Toolchain --output /path/to/new-build arguments. Use the bundled VCC Plus toolchain, CMOC0.1.101, with its matching LWTools, SSC and public-domain decbfile libraries. The supported driver uses ordinary Disk BASIC ROM services; no separately licensed standalone disk driver is copied here. Python is only a build/reporting dependency on the host, not on the CoCo.

SOUNDLAB-manifest.json binds the short guest build ID and vector CRCs to full source/artifact SHA-256 hashes. SHA256SUMS covers the BIN, BASIC loader and DSK. The host BASIC source uses LF; its disk member uses the disk writer's explicit leading-CR and CR line-ending conversion. Both forms contain the same loader. The compiler's $7A00 limit and retained map check ordinary memory bounds. The text-only guest uses the otherwise unused, PCLEAR1-reserved PMODE page at $0E00–$13FF as a1536-byte log. Compiled assembly is checked for one actual LDB $FF7E per status-reader call. Ready and completion loops have elapsed-tick and independent iteration limits.

The native runner boots the disk through actual Disk BASIC and FD502 emulation with existing private local ROM inputs. It does not launch or operate the user's app. The build receipt records what was tested. Physical CoCo listening, physical disk behavior and future FPGA acceptance remain separate.

Sources and license

Sound Lab guest, generator, original vectors, host utilities and tests are GPL-3.0-or-later, like the VCC Plus SDK. The tiny DOS bootstrap retains Pierre Sarrazin's public-domain attribution. CMOC library/dependency notices remain in the toolchain distribution; this project does not redistribute the compiler or private firmware. The delivery's COPYING is the GPL license text.

Packet/source notes cite a downloaded, hashed OCR/typeset reproduction of Tandy's original publication. It is not a photographic scan. The diagnostic bytes are newly authored; manual PDFs and ROM contents are not included in the disk or source archive. No checksum establishes redistribution rights or proof of hardware fidelity.