Sound Lab host reports
python3 soundlab_reports.py requires Python 3.10 or later and only the standard
library. It reads existing disk images and report files; it does not run the
emulator, touch a mounted disk, contact a service or modify source inputs.
Extract and preserve reports
Quit or safely eject/save the writable diagnostic disk first, then copy it to a host working folder. Extract from that saved copy:
python3 examples/sound-lab/host/soundlab_reports.py extract /path/to/SOUNDLAB.DSK \
--output /path/to/run-exports
The input must be a raw, single-sided, standard 35-track Disk BASIC disk image:
35 tracks × 18 sectors × 256 bytes = 161,280 bytes. DMK, images with headers and
other geometries are rejected rather than guessed. Selected filenames are
SND0000.TXT through SND9999.TXT, case-insensitively. Reports must have the
Disk BASIC ASCII flag FF; the guest writes directory type 3 (text). The tool
preserves every selected file's exact bytes, normalizes its output filename to
uppercase, and writes extraction.json with the original disk's SHA-256, each
report's SHA-256/byte count and its granule chain.
Validation covers the directory, file type/ASCII flag, final-sector byte count, FAT values, fragmented chains, cycles, free granules in a file chain, duplicate names, unsafe names and crosslinks involving any active file. The directory track is excluded from granule addressing. Unclaimed FAT allocations are allowed because interrupted writes can leave them; the extractor does not repair them. It validates filesystem structure, not the authenticity of the disk's contents.
An existing output is never replaced implicitly. Prefer a fresh output folder
for each run. --overwrite permits replacement of ordinary output files only;
symlinks, inputs and hardlinks to inputs are still rejected. Keep the source
.DSK and extracted .TXT as original evidence. The extractor never reformats,
repairs or writes back to the disk.
Convert and compare
python3 examples/sound-lab/host/soundlab_reports.py convert \
/path/to/run-exports/SND0001.TXT --output /path/to/readable-run \
--manifest .build/sound-lab/SOUNDLAB-manifest.json
python3 examples/sound-lab/host/soundlab_reports.py compare \
/path/to/vcc/SND0001.TXT /path/to/real-coco/SND0001.TXT \
--output /path/to/comparison \
--manifest .build/sound-lab/SOUNDLAB-manifest.json
Conversion writes JSON, CSV and a self-contained readable HTML file. The JSON retains all recorded run metadata and per-case fields; CSV keeps raw timing/status fields as columns. The HTML escapes report text and includes no scripts or remote assets. No audio files or listening claims are manufactured.
The optional authoritative manifest has this supported structure (other fields such as artifact hashes may also be present):
{
"build_id": "BUILD-IDENTITY",
"vector_set_crc16": "1234",
"vectors": [{"case_id": "TON01-A", "crc16": "7ABC"}]
}
The vector list may alternatively be an object such as
"vectors": {"TON01-A": "7ABC"}. CRC values in the manifest may be four-digit
hex strings, strings prefixed with 0x, or JSON integers. Use ordinary four-digit
hex in report records. Uppercase manifest keys BUILD_ID and
VECTOR_SET_CRC16 are accepted aliases. A manifest binds the guest's short build
and vector IDs to the host build receipt; a CRC is not a cryptographic signature.
The separate artifact hashes establish which binary/disk bytes were built.
Comparison requires the same nonempty BUILD_ID, VECTOR_SET_CRC16 and matching
per-case VECTOR_CRC16. With a manifest, both reports must match its declared
identities too. Without one, the result explicitly states
identity_basis=REPORT_CLAIMS_ONLY. Different/missing identities, missing cases,
partial reports or failed integrity checks produce NOT_COMPARABLE, with the
recorded evidence still shown. Comparable cases show SAME or DIFFERENT and
list differing metrics, raw status, timings or notes. Matching these values does
not establish matching audible output or equal analog timing precision.
AUTO and HUMAN are separate columns. AUTO=OBSERVED never becomes
HUMAN=HEARD. Missing outcomes remain UNKNOWN; unknown timing resolution stays
unknown. The tool checks report consistency and identities; it does not certify
the author's automatic verdict or make hardware pass/fail assertions.
Exit status is 0 for successful valid conversion/comparison or extraction, 1 for
an unreadable/unsupported input or refused output, and 2 when result files were
written but evidence is partial, invalid or not comparable. Inspect the JSON/HTML
issues instead of treating exit 2 as a completed run. Optional absent checksum or
count fields are explicitly NOT_PROVIDED, never VERIFIED.
SOUNDLAB-1 record contract
The first nonblank line is exactly FORMAT=SOUNDLAB-1. Subsequent ordinary lines
contain space-separated KEY=VALUE tokens with uppercase keys and nonempty values.
Values containing whitespace belong in escaped NOTE records. CRLF is preferred;
LF is accepted. Bare CR, non-ASCII bytes and unescaped control characters are
rejected. Empty/whitespace-only lines are ignored for record counts and checksums.
Unknown metadata and per-case keys are retained for forward-compatible evidence.
A different FORMAT requires a new parser version.
A header declares the run, target and build/vector identity. A case starts with
CASE=... VECTOR_CRC16=HHHH AUTO=... HUMAN=...; subsequent lines carry its metrics.
ENDCASE must match that case's identity. A per-case REPEAT=0 field identifies
the first attempt, REPEAT=1 the next, and so on. Each (CASE, REPEAT) pair must
be unique within a report. Omitted REPEAT defaults to 0 for early SOUNDLAB-1
compatibility. Attempts are retained separately in JSON/CSV/HTML and compared by
that pair, even if recorded in a different order. An interrupted case/run is preserved
and marked incomplete. Case IDs and outcome enumerations compare
case-insensitively; the original text/fields remain available.
Allowed automatic values: PASS, FAIL, OBSERVED, TIMEOUT, NOT_RUN,
NOT_APPLICABLE. Allowed human values: HEARD, WRONG, NO_SOUND, UNSURE,
NOT_OBSERVED, SKIPPED.
An optional note consists of two consecutive records inside a case:
NOTE_LENGTH=18
NOTE=FIRST LINE\nSECOND!\n
NOTE_LENGTH counts decoded ASCII bytes, not the serialized escape length.
Escapes are \\, \n, \r, \t and \xHH (ASCII 00–7F). NOTE= consumes the
rest of its line, including spaces. Length mismatch, unknown escapes, a dangling
length or a note outside a case is reported as invalid/incomplete evidence.
A finished run ends with one footer, with no following nonblank records:
ENDRUN=0001 COMPLETE=YES RECORD_COUNT=8 CHECKSUM_CRC16=1234
The run number must match RUN. COMPLETE=NO explicitly retains an interrupted
run. Footer integrity fields are optional for interoperability; the diagnostic
writer supplies both. RECORD_COUNT is the number of preceding nonblank lines,
including FORMAT and every case, note and ENDCASE line, excluding the footer.
CHECKSUM_CRC16 is CRC-16/CCITT-FALSE: polynomial 1021, initial FFFF, no
reflection, no final XOR. It covers those same original nonblank lines joined
with CRLF, including a final CRLF, and excludes the footer. Lowercase and
uppercase hex are equivalent. Example footer values above are schematic.
ROM-free checks
python3 -m unittest discover -s examples/sound-lab/tests -p test_reports.py -v
The authored fixtures cover fragmented disks across the reserved track, full sectors/granules, truncation, malformed FAT and loops/crosslinks, report end markers, notes, count/checksum validation, independent outcome comparisons, manifest identities, raw metric differences and output preservation. They use no private ROMs, real reports or actual hardware recordings.