Files
VCCPlusDiagnostics/examples/sound-lab/vectors/generate.py
T

265 lines
13 KiB
Python

#!/usr/bin/env python3
# SPDX-License-Identifier: GPL-3.0-or-later
"""Authored Sound Lab vectors; no emulator, ROM or third-party Python required."""
import argparse
import hashlib
import json
from pathlib import Path
ROOT = Path(__file__).resolve().parent
def crc16(data):
"""CRC-16/CCITT-FALSE: poly1021, initFFFF, refin=false, xorout0000."""
crc = 0xFFFF
for byte in data:
crc ^= byte << 8
for _ in range(8):
crc = ((crc << 1) ^ (0x1021 if crc & 0x8000 else 0)) & 0xFFFF
return crc
def sound_events(data):
"""Parse event boundaries; FF is legal inside operands, not at a boundary."""
pos = 0
events = []
while pos < len(data):
op = data[pos]
if op == 0xFF:
if pos != len(data) - 1:
raise ValueError('bytes after sound terminator')
return events
width = 4 if op & 0x60 == 0x60 or not op & 0x80 else 3
if pos + width >= len(data):
raise ValueError('incomplete sound event or missing terminator')
if width == 4 and op & 0x60 != 0x60 and data[pos + 1] > 15:
raise ValueError('tone coarse period outside 12-bit range')
if width == 3 and data[pos + 1] & 0x60:
raise ValueError('noise reserved period bits set')
events.append(data[pos:pos + width])
pos += width
raise ValueError('missing sound terminator')
def register_pairs(data):
pos = 0
while pos < len(data):
reg = data[pos]
if reg == 0xFF:
if pos != len(data) - 1:
raise ValueError('bytes after register terminator')
return
if reg > 13 or pos + 1 >= len(data):
raise ValueError('invalid or incomplete register pair')
maximum = (15 if reg in (1, 3, 5, 13) else
31 if reg in (6, 8, 9, 10) else 63 if reg == 7 else 255)
if data[pos + 1] > maximum:
raise ValueError('register value outside documented field width')
pos += 2
raise ValueError('missing register terminator')
def validate_tx(data):
"""Validate the deliberately bounded, single-slot command subset used here."""
if not data or any(type(b) is not int or not 0 <= b <= 255 for b in data):
raise ValueError('TX must contain bytes')
pos = 0
while pos < len(data):
cmd = data[pos]
pos += 1
if cmd in (0, 0xC7, 0xCF) or 0xD0 <= cmd <= 0xDF or 0xF0 <= cmd <= 0xFF:
continue
if cmd == 0x8F:
if pos == len(data):
raise ValueError('timer lacks operand')
pos += 1
continue
if 0x20 <= cmd < 0x80 or 0x90 <= cmd <= 0x97:
start = pos - 1 if cmd < 0x80 else pos
try:
end = data.index(13, start)
except ValueError:
raise ValueError('text lacks CR') from None
payload = data[start:end]
if not payload or any(not 32 <= b <= 126 for b in payload):
raise ValueError('non-printable text')
if len(payload) + 1 > 64:
raise ValueError('single text buffer exceeds 64 bytes')
pos = end + 1
continue
if 0x98 <= cmd <= 0x9F:
start = pos
while pos < len(data):
op = data[pos]
if op == 255:
pos += 1
break
pos += 4 if op & 0x60 == 0x60 or not op & 0x80 else 3
body = data[start:pos]
sound_events(body)
elif 0xB0 <= cmd <= 0xB7:
start = pos
while pos < len(data) and data[pos] != 255:
if data[pos] > 63:
raise ValueError('allophone outside AL2 range')
pos += 1
if pos == len(data) or pos == start or data[pos - 1] > 4:
raise ValueError('allophones need final pause and FF')
pos += 1
body = data[start:pos]
elif cmd == 0xAF or 0xB8 <= cmd <= 0xBF:
start = pos
while pos < len(data) and data[pos] != 255:
pos += 2
if pos == len(data):
raise ValueError('register packet lacks boundary terminator')
pos += 1
body = data[start:pos]
register_pairs(body)
else:
raise ValueError(f'unsupported command {cmd:02X}')
if cmd != 0xAF and len(body) > 64:
raise ValueError('single buffer exceeds 64 bytes')
return True
def tone(channel, period, volume=10, ticks=15):
if not 0 <= channel <= 2 or not 0 <= period <= 4095 or not 0 <= volume <= 31:
raise ValueError('invalid tone fields')
return [channel * 32 + volume, period >> 8, period & 255, ticks]
def noise(channel, period, volume=8, ticks=15):
return [0x80 + channel * 32 + volume, period, ticks]
def stored_sound(events, slot=0):
return [0x98 + slot] + events + [255, 0xD8 + slot]
def authored_vectors():
out = []
def add(identity, title, prompt, tx, wait=0x20, hold=0, group=2,
source='TANDY-SOUND', expectation='MEASURE_BASELINE'):
validate_tx(tx)
out.append(dict(id=identity, title=title, prompt=prompt, tx=tx,
wait_mask=wait, hold_ticks=hold, group=group,
source_claims=[source], expectation=expectation))
def text(s):
return list((s + ' \r').encode('ascii'))
add('TXT01', 'MEET YOUR ROBOT', 'HEAR THE GREETING?',
text('HELLO BRIAN. WELCOME TO THE SOUND LAB.'), 0x40, group=3,
source='TANDY-TEXT')
add('TXT02-READ', 'WORDS AND NUMBERS', 'WORDS CLEAR? NOTE PRONUNCIATION.',
text('READY PLAYER ONE. LEVEL TWO. SCORE ONE HUNDRED.'), 0x40,
source='TANDY-TEXT')
add('TXT03-LONG', 'SHORT THEN LONG', 'COMPARE WITH THE FIRST GREETING.',
text('THE ROBOT CAN SPEAK A LONGER SENTENCE.'), 0x40,
source='TANDY-TEXT')
for channel in range(3):
add('TON01-' + 'ABC'[channel], 'TONE ' + 'ABC'[channel],
'ONE CLEAR PITCH; THEN SILENCE.',
stored_sound(tone(channel, 254) + tone(channel, 254, 0, 0)),
group=3 if channel == 0 else 2)
add('TON04', 'RISING STEPS', 'DO THE THREE NOTES RISE?',
stored_sound(sum((tone(0, p, 10, 12) for p in (428, 339, 254)), []) + tone(0, 254, 0, 0)), group=3)
add('TON05', 'THREE VOICE CHORD', 'THREE NOTES TOGETHER, THEN OFF.',
stored_sound(tone(0, 428, 8, 0) + tone(1, 339, 8, 0) + tone(2, 285, 8, 24)
+ tone(0, 428, 0, 0) + tone(1, 339, 0, 0) + tone(2, 285, 0, 0)), group=3)
add('AMP01', 'SOFT TO LOUD', 'DO THE FOUR STEPS GET LOUDER?',
stored_sound(sum((tone(0, 254, v, 10) for v in (2, 5, 9, 13)), []) + tone(0, 254, 0, 0)))
add('NOI01', 'NOISE COLORS', 'NOISE CHANGES FROM HISS TO RUMBLE.',
stored_sound(sum((noise(0, p, 7, 12) for p in (1, 8, 31)), []) + noise(0, 31, 0, 0)), group=3)
add('NOI02', 'NOISE CONTINUE', 'TWO NOISE EVENTS; SAME VOLUME.',
stored_sound(noise(0, 8, 7, 15) + noise(0, 0x80 | 16, 0, 15) + noise(0, 16, 0, 0)), group=4)
# AF writes an audible fixed tone. Parent waits hold_ticks, sends00 and confirms silence.
add('REG01', 'DIRECT AY REGISTERS', 'STEADY TONE; PANIC MUST SILENCE.',
[0xAF, 0, 254, 1, 0, 7, 62, 8, 9, 255], 0, 40, 2, 'TANDY-REGISTERS')
add('REG02', 'FF IS REGISTER DATA', 'STEADY TONE; FF DATA IS NOT END.',
[0xAF, 0, 255, 1, 0, 7, 62, 8, 8, 255], 0, 40, 4, 'TANDY-REGISTERS')
add('CMD01', 'STOP AND CONTROL', 'NO SOUND AFTER ALL THREE STOPS.',
[0xC7, 0xCF, 0], 0x60, group=4, source='TANDY-COMMANDS', expectation='DOCUMENTED_CONTROL')
add('TIM01', 'BASE TIMER', 'RECORD DURATION; NO FIXED MS CLAIM.',
[0x8F, 16] + stored_sound(tone(0, 254, 8, 4) + tone(0, 254, 0, 0)), group=4,
source='TANDY-TIMER')
add('TIM02', 'FF IS DURATION DATA', 'LONG EVENT, THEN SILENCE.',
stored_sound(tone(0, 254, 8, 255) + tone(0, 254, 0, 0)), group=4)
add('FUN01-TUNE', 'ORIGINAL SHORT TUNE', 'HEAR A SMALL RISING AND FALLING TUNE.',
stored_sound(sum((tone(0, p, 9, 9) for p in (428, 339, 285, 254, 285, 339, 428)), [])
+ tone(0, 428, 0, 0)), group=3)
# Shared speech slots and independent sound slots; each case executes only its own slot.
for slot in range(8):
add(f'BUF01-SP{slot}', f'SPEECH SLOT {slot}', 'HEAR THE CORRECT SLOT NUMBER?',
[0x90 + slot] + text('BUFFER ' + ('ZERO','ONE','TWO','THREE','FOUR','FIVE','SIX','SEVEN')[slot])
+ [0xD0 + slot], 0x40, group=4, source='TANDY-COMMANDS')
add(f'BUF02-SN{slot}', f'SOUND SLOT {slot}', 'MATCH SLOT AND SHORT TONE.',
stored_sound(tone(0, 428 - 24 * slot, 8, 8) + tone(0, 254, 0, 0), slot),
group=4, source='TANDY-COMMANDS')
names = ('PA1 PA2 PA3 PA4 PA5 OY AY EH KK3 PP JH NN1 IH TT2 RR1 AX MM TT1 DH1 IY EY DD1 UW1 AO AA YY2 AE HH1 BB1 TH UH UW2 AW DD2 GG3 VV GG1 SH ZH RR2 FF KK2 KK1 ZZ NG LL WW XR WH YY1 CH ER1 ER2 OW DH2 SS NN2 HH2 OR AR YR GG2 EL BB2').split()
for code, name in enumerate(names):
add(f'ALP01-{code:02d}', f'ALLOPHONE {code:02d} {name}',
'PAUSE: EXPECT NO VOICE.' if code < 5 else 'RECORD WHAT YOU HEAR.',
[0xB0, code, 0, 255, 0xF0], 0x40, group=4, source='TANDY-ALLOPHONES')
for shape in range(16):
# Documented grammar: envelope-enabled tone immediately followed by envelope event.
events = tone(0, 254, 16, 0) + [0x60 | shape, 3, 0, 35] + tone(0, 254, 0, 0)
add(f'ENV01-{shape:02d}', f'ENVELOPE {shape:02X}', 'COMPARE SHAPE AND END SILENCE.',
stored_sound(events), group=2 if shape == 10 else 4, source='TANDY-ENVELOPE')
add('MIX01', 'ROBOT SPACEPORT', 'VOICE OVER AN AMBIENT TONE.',
stored_sound(tone(0, 339, 5, 0)) + text('WELCOME TO THE SPACE PORT.'),
0x40, 20, 3, 'TANDY-COMMANDS')
return out
def build_manifest():
vectors = authored_vectors()
for case in vectors:
raw = bytes(case['tx'])
case.update(case_id=case['id'], crc16=f'{crc16(raw):04X}',
tx_hex=raw.hex(' ').upper(), byte_count=len(raw),
crc16_ccitt_false=f'{crc16(raw):04X}', sha256=hashlib.sha256(raw).hexdigest())
identities = [v['id'] for v in vectors]
if len(set(identities)) != len(identities):
raise ValueError('duplicate vector ID')
body = dict(schema='vccplus.sound-lab.vectors.v1', vector_version='1.0',
vector_set_crc16=f"{crc16(bytes(b for case in vectors for b in case['tx'])):04X}",
authored=True, crc='CRC-16/CCITT-FALSE',
result_policy='HUMAN listening is never an AUTO pass; timings are MEASURE_BASELINE.',
source_catalog=json.loads((ROOT / 'sources.json').read_text()), vectors=vectors)
canonical = json.dumps(body, sort_keys=True, separators=(',', ':')).encode()
body['manifest_sha256'] = hashlib.sha256(canonical).hexdigest()
return body
def emit(output):
manifest = build_manifest()
output.mkdir(parents=True, exist_ok=True)
(output / 'vectors.json').write_text(json.dumps(manifest, indent=2) + '\n')
lines = ['/* Generated by vectors/generate.py; do not edit. */', '#ifndef SOUND_LAB_VECTORS_H',
'#define SOUND_LAB_VECTORS_H',
'typedef struct { const char *id; const char *title; const char *prompt;',
'const unsigned char *tx; unsigned length; unsigned crc16;',
'unsigned char wait_mask; unsigned char hold_ticks; unsigned char group; } SoundVector;']
for i, case in enumerate(manifest['vectors']):
lines.append('static const unsigned char sound_tx_%u[] = {%s};' %
(i, ','.join('0x%02X' % b for b in case['tx'])))
lines.append('static const SoundVector sound_vectors[] = {')
for i, case in enumerate(manifest['vectors']):
lines.append('{%s,%s,%s,sound_tx_%u,%u,0x%s,0x%02X,%u,%u},' %
(json.dumps(case['id']), json.dumps(case['title']), json.dumps(case['prompt']),
i, case['byte_count'], case['crc16_ccitt_false'], case['wait_mask'],
case['hold_ticks'], case['group']))
lines += ['};', '#define SOUND_VECTOR_COUNT %u' % len(manifest['vectors']),
'#define SOUND_VECTOR_VERSION "1.0"',
'#define SOUND_MANIFEST_SHA256 "%s"' % manifest['manifest_sha256'], '#endif', '']
(output / 'vectors.h').write_text('\n'.join(lines))
return manifest
if __name__ == '__main__':
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('--output', type=Path, required=True)
args = parser.parse_args()
result = emit(args.output)
print(f"{len(result['vectors'])} vectors; manifest {result['manifest_sha256']}")