Files

162 lines
8.4 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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](COVERAGE.md) 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:
```sh
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](host/README.md) 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](audio/README.md) 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:
```sh
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):
```sh
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](native/run.cpp) 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](vectors/PROTOCOL.md) 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.