Release SPECTRAL v2.1.0 — Browser-Native Photoacoustic Laboratory · QSOLKCB/SPECTRAL

SPECTRAL v2.1.0 introduces the new SPECTRAL Photoacoustic Laboratory 2.0: a zero-install browser application for deterministic light-to-sound modelling, experimental music generation, WAV transformation, visual analysis, and provenance-bound audio export.

The original Python Photoacoustic Sonifier has been preserved under PHOTOACOUSTIC/scripts/, while the primary interactive implementation now runs entirely inside the browser.

No Python runtime, Node.js, npm, server, build system, CDN, telemetry, or network connection is required.

Simply open:

PHOTOACOUSTIC/index.html

Highlights

Complete browser-native redesign of the Photoacoustic Sonifier
Canonical Strict and Replay Safe determinism contracts
Fixed-point and Float64 photoacoustic DSP paths
Synthetic light generation and local WAV-through-light processing
Editable absorber materials and acoustic resonators
Eight light-source and instrument presets
Deterministic PCM16 WAV export
Provenance manifests, fingerprints, stage receipts, and observation contracts
Deterministic provenance ZIP packages
Waveform, spectrogram, and model-stage visualization
Manifest replay and tamper rejection
IndexedDB render history with session fallback
Browser-native known-answer and acceptance tests
Preserved legacy Python implementation
MIT licensing throughout

Browser-native Photoacoustic Laboratory

The new application models the following simplified signal chain:

light intensity
  → optical absorption
  → material nonlinearity
  → thermal RC response
  → steady-heating removal
  → Γβ pressure conversion
  → direct/derivative pressure blend
  → parallel acoustic resonators
  → optional effects
  → PCM16 quantization
  → canonical WAV

The model is intended for artistic, educational, sonification, and experimental-audio use.

Material and acoustic-cell parameters are illustrative and are not presented as calibrated physical measurements, biomedical claims, engineering predictions, or replacements for physical apparatus modelling.

Two determinism modes

Canonical Strict

Canonical Strict provides the archival and cross-runtime rendering path.

It introduces:

a Q15 integer signal ABI;
integer phase accumulators;
an integer-only Bhaskara sine approximation;
fixed-point optical absorption;
fixed-point thermal state;
fixed-point pressure conversion;
fixed-point state-variable resonators;
deterministic fixed-point effects;
safe-integer canonical JSON;
bundled SHA-256;
explicit PCM16 quantization;
canonical little-endian WAV serialization;
deterministic ZIP packaging;
and strict integer-PCM WAV parsing.

The strict backend is a separately versioned browser DSP ABI. It does not claim byte parity with NumPy or SciPy.

Its intended contract is:

same application and engine versions
+ same Canonical Strict mode
+ same normalized recipe
+ same source bytes
+ same seed and mutation index
= same PCM, WAV, fingerprint, contract, manifest, and ZIP bytes

Replay Safe

Replay Safe provides the creative and Python-inspired Float64 path.

It includes:

Float64 optical and thermal processing;
nonlinear absorber response;
SciPy-compatible cavity peak coefficients;
explicit Float64-to-PCM16 quantization;
deterministic linear resampling;
PCM and IEEE Float WAV input;
runtime fingerprinting;
and same-runtime replay verification.

Strict and Replay Safe outputs occupy separate recipe and contract domains.

Light-source and musical presets

Eight browser presets are included:

Industrial Fibonacci — Fibonacci optical impulses through charcoal and industrial-pipe modes
Soot Music — melodic light modulation through a soot-and-glass-jar model
Resonant Gas Cell — optically chopped harmonic excitation through ethene and an H-type cell
Ultrasonic Edge — fast dual-pulse excitation through the CS/PDMS model
Dark Thermal Drone — slow industrial modulation through black aluminium and Helmholtz modes
Evolving Material Demo — a four-stage material and resonator progression
Pulse Laboratory — editable optical pulse generation
Tone Laboratory — direct optical-carrier and cavity-response experimentation
WAV Through Light — local audio interpreted as positive-biased optical modulation

The evolving demo moves through:

soot and glass jar;
charcoal and industrial pipe;
ethene and H-type cell;
CS/PDMS and the broad open-response model.

Its complete expanded schedule is recorded in the render recipe and stage receipt.

Absorber material registry

The browser laboratory preserves the original material families:

Soot / candle black
Charcoal
Ethene gas cell
CS/PDMS nanocomposite
Black aluminium foil
Custom material

Editable parameters include:

optical absorption;
thermal time constant;
Grüneisen scaling;
expansion scaling;
material nonlinearity;
and relative laser power.

Acoustic resonator registry

Included resonator models are:

Glass jar
Helmholtz resonator
H-type photoacoustic cell
Open-air approximation
Industrial pipe or duct
Custom resonator

Custom resonators support between one and eight explicit modal frequencies and Q factors.

Canonical Strict validates custom modes against the fixed-point stability domain and rejects invalid, mismatched, non-positive, or unsupported configurations.

WAV Through Light

Local WAV files can now be used as optical-intensity modulation sources.

The bundled RIFF parser supports:

PCM8
PCM16
PCM24
PCM32
IEEE Float32
IEEE Float64
mono and multichannel downmixing
explicit deterministic resampling

Canonical Strict accepts integer PCM sources. Float WAV inputs are restricted to Replay Safe.

Source files are:

processed locally;
never uploaded;
hashed before rendering;
limited to 128 MiB;
and constrained to a maximum 120-second rendered output.

The parser fails closed on malformed RIFF boundaries, duplicate canonical chunks, missing padding, unsupported codecs, invalid alignment, non-finite float samples, and incompatible formats.

Post-processing

Versioned browser-native effects include:

optical saturation and distortion;
three-band tone shaping;
modulated-delay chorus;
and four-tap chamber reflection/reverb.

The identity-bearing processing order is:

distortion → EQ → chorus → reverb

Disabled-effect parameters and unused generator controls are excluded from normalized recipe identity.

Export profiles

Suno Seed

48 kHz
PCM16 dual mono
−6.00 dBFS ceiling
conservative headroom for original source-stem workflows

Laboratory Hot

44.1 kHz
PCM16 mono
−0.10 dBFS ceiling
intended for aggressive local experiments

Suno Seed is a technical headroom profile. It is not a detector bypass, copyright-evasion mechanism, or external upload guarantee.

Provenance artifacts

Every completed render can generate:

audio.wav
manifest.json
fingerprint.json
stage_receipt.json
derivation_graph.json
upload_readiness.json
README_ORIGIN.txt
photoacoustic_provenance.zip

The deterministic ZIP uses:

lexically sorted entries;
fixed DOS epoch fields;
explicit CRC-32 values;
no comments;
no extra fields;
and uncompressed storage.

Recipe and observation contract

Each normalized recipe freezes:

application and engine versions;
algorithm and schema versions;
determinism mode;
preset and consumed generator parameters;
sample rate and integer duration;
expanded material parameters;
expanded resonator modes;
laser power and pressure method;
enabled effects and their parameters;
export profile;
source-byte identity;
seed and mutation index;
and Replay Safe runtime identity where applicable.

Observation contracts bind:

recipe SHA-256;
PCM SHA-256;
canonical WAV SHA-256;
fingerprint SHA-256;
stage-receipt SHA-256;
signal ABI;
sample format;
sample rate;
channel count;
frame count;
and replay requirements.

Manifest replay

The browser application can replay exported manifests.

Replay fails closed when it encounters:

an unsupported schema or engine version;
an unknown preset or generator;
modified recipe or contract data;
missing source audio;
changed source bytes;
runtime mismatch in Replay Safe;
WAV-hash mismatch;
contract mismatch;
or manifest-core mismatch.

Failed and cancelled renders create no partial artifact set.

Fingerprinting and readiness

The local deterministic fingerprint records:

PCM and WAV hashes;
peak and RMS;
DC offset;
zero crossings;
clipping count;
fixed-size PCM chunk hashes;
exact repeated-chunk observations;
and a 64-bin RMS-envelope hash.

Upload readiness is an offline technical advisory only. It does not query or emulate Content ID, Suno, Spotify, YouTube, or another external matching service.

Visualization and interface

The new laboratory provides:

interactive PCM waveform rendering;
FFT spectrograms;
logarithmic and linear frequency display;
light-intensity traces;
thermal-response traces;
pressure traces;
acoustic-output traces;
playback transport;
render metrics;
hash summaries;
accessible stage navigation;
responsive desktop and mobile layouts;
render progress reporting;
and explicit stale-output warnings after parameter changes.

Identity-bearing controls are frozen during rendering so the visible interface cannot drift away from the sealed recipe.

Local storage and privacy

IndexedDB stores the most recent 24 completed renders, including their WAV files, receipts, and provenance bundles.

When IndexedDB is unavailable under a local file:// origin, the application continues with an explicit session-only fallback.

The browser application:

creates no cookies;
uses no analytics;
registers no service worker;
requests no microphone, camera, or MIDI access;
contains no production network client;
loads no remote assets;
and keeps selected source files on the local computer.

A restrictive Content Security Policy includes:

connect-src 'none'
frame-src 'none'
worker-src 'none'
object-src 'none'

Browser-native acceptance suite

Open:

PHOTOACOUSTIC/tests/index.html

The suite covers:

SHA-256 known-answer vectors;
canonical JSON;
exact decimal scaling;
strict oscillator vectors;
PCM16 WAV serialization;
PCM8/16/24/32 parsing;
positive-extrema clamping;
RIFF padding and boundary validation;
deterministic resampling;
material and resonator registries;
configuration validation;
frozen strict end-to-end hashes;
repeat-render equality;
mutation and mode separation;
all original musical mappings;
material/resonator matrix rendering;
manifest replay;
source-bound replay;
changed-source rejection;
tamper rejection;
early and late cancellation;
deterministic ZIP identity;
local-storage checks;
and network-attempt auditing.

Legacy Python implementation

The original command-line implementation has been preserved at:

PHOTOACOUSTIC/scripts/photoacoustic_sonifier.py

A dedicated legacy-script README is included at:

PHOTOACOUSTIC/scripts/README.md

The Python version remains available for:

NumPy/SciPy experimentation;
command-line generation;
reference comparisons;
and preservation of the original implementation.

This move separates the active browser application from the historical Python source without deleting or rewriting the original script.

Licensing

The browser application and preserved Python implementation remain available under the permissive MIT License.

Getting started

Clone SPECTRAL:

git clone https://github.com/QSOLKCB/SPECTRAL.git
cd SPECTRAL