Files
VCCPlusOSS/docs/macos/AUDIO_CASSETTE.md
T

5.4 KiB
Raw Blame History

Native audio and cassette milestone

Technical evidence extract for the VCC Plus white paper. Only reviewed contracts, mechanisms, methods, results and limitations are retained. Original validation dates and configuration limits remain historical; this export is not a new test run.

Boundaries and compatibility

  • A 44.1 kHz scheduled event samples the PIA sound state, selected analog source, independent cartridge outputs and cassette input/output. Samples follow emulated time and stop when the machine pauses. Reset clears the PIA output latches and replaces the sampler event.

  • The packed PIA words are converted explicitly to signed stereo float samples. Native output uses AVAudioEngine/AVAudioSourceNode over the Mac audio system. The render callback only drains a fixed-capacity, single-producer/single-consumer buffer; it allocates no memory, acquires no locks, and never calls the emulator. Apple source-node guidance requires avoiding blocking operations in device render callbacks.

  • The machine queue refills roughly 100 ms ahead, with at most four frames per turn. Device consumption paces emulation without changing the CPU/GIME clock ratios. Output starts only after the reserve is filled. The queue has an 8,192-frame hard limit; the extra reserve adds about 50 ms of latency over the preceding implementation. Missing samples become silence; underrun, overrun, consumed/submitted/nonzero sample counts, occupancy and output-start counters are exposed in bridge snapshots. Zero volume still consumes samples. Volume/mute changes now preserve the running engine and queued audio. The producer uses interactive scheduling priority; a one-second loss of consumption falls back to silent pacing. See timing and reliability for sustained checks and limits.

  • The Windows sampler's +25 Hz host-buffer compensation is not carried over; output consumption supplies pacing. This is an intentional host-side difference that still needs sustained comparison with Windows.

  • CAS retains the upstream least-significant-bit-first 21/40-sample waveforms, amplitude reduction and rising-edge decoder. Fast CAS retains the $83 BASIC pulse-width convention. Motor gaps use emulated time. No ROM patch is bundled.

  • WAV parsing walks RIFF chunks, including unknown chunks and padding, and checks sizes before reading. Input accepts mono/stereo PCM 8/16/24/32-bit and float32 at 8–192 kHz. Stereo is averaged; sample positions are normalized to 44.1 kHz. Compressed WAV and WAVE_FORMAT_EXTENSIBLE are not accepted in this milestone.

  • Files and normalized/recorded WAV images are bounded to 64 MiB, including export-header space; CAS is bounded to 1 MiB. Recording stops at capacity. Recording resumes only through a new recording; this milestone does not overwrite sections of existing tapes or splice recordings.

  • The active deck lives in memory. File-backed cassette assignment is now remembered and reopens stopped at the beginning on relaunch; unexported recordings are protected by quit/replacement safeguards, not serialized as a saved execution state. See startup behavior and profiles. A separate audio-output picker, analog filtering and broader cassette-library qualification remain outside this baseline.

Validation and outstanding checks

Verified on the local Apple Silicon Mac with Xcode 27.2/macOS 27.2:

  • 51 XCTest tests: 39 shared core checks, seven bridge tests and five native tests.

  • Debug and Release universal app builds; the 39-check Release console suite and both-CPU BASIC integrations passed on arm64 and x86_64 under Rosetta. Rosetta does not validate physical Intel hardware.

  • Focused audio/cassette and both-CPU BASIC integrations passed AddressSanitizer and UndefinedBehaviorSanitizer. The full legacy suite stops under UBSan at the existing signed-left-shift issue in ssc/sp0256.cpp:125; at this early checkpoint that chip was not connected to the Mac machine. Speech/Sound was integrated later; this historical sanitizer result is not a claim about the current full suite. LeakSanitizer is unavailable on this platform.

  • Real native audio-device consumption at zero volume, pause stability, restart and shutdown.

  • Concurrent ring-buffer ordering/wraparound, explicit channel/sign conversion, mute, bounded overflow, underrun silence and sample timing from both CPU engines.

  • Tape motor gating, position/end behavior, reset retention, fast-load PIA reads, export/save state, invalid WAV input, all accepted sample representations, rate normalization, unknown chunks and truncated files.

  • File loading with uppercase extensions, spaces and Unicode; oversized inputs are rejected and source bytes remain unchanged.

  • The optional VCCCoreChecks --rom /path/to/coco3.rom check boots both CPUs, verifies BASIC SOUND produces samples, records the authored program using CSAVE to CAS and WAV, clears BASIC, reloads through CLOAD, and checks LIST/RUN and 42. It separately repeats fast CAS loading. No ROM or generated tape is committed.

Analog routing correction — November 11, 2026

The native sampler now honors sound enable and the DAC/cassette/cartridge/ground selector. This fixes the reproduced Quadrapassel splash-screen buzz with both Speech/Sound and Orchestra-90 connected, while retaining normal effects and independent external stereo. The game and installed app were not changed. See cause, reproduction and qualification.