162 lines
8.4 KiB
Markdown
162 lines
8.4 KiB
Markdown
# 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.
|