OSCILLA

A zero-install, scientifically honest acoustic laboratory in your browser: generate, measure and reproduce sound experiments, and know how far each result can be trusted.

What you can do with it today, from one static file and with no account:

• measure the response of your speaker, room and microphone chain with a log sweep, and see the quality reasons that say how far that response can be trusted;
• compare two experiments, for example two setups or two microphone positions, with every difference between their records named;
• save an experiment and repeat it later from its recipe;
• generate tones, sweeps and sequences and see them as waveform, spectrum and spectrogram;
• patch a signal graph in the Studio and run it.

Live demo: https://korczis.github.io/oscilla/

What it does

OSCILLA generates signals with the native Web Audio API and measures them while they play. It shows them as a waveform, a live spectrum and a spectrogram, and it compares them with what your microphone picks up. You can arrange signals into block sequences, shape them with filters, an ADSR envelope and additive harmonics, explore phase and stereo, and export the result. In the Measure workspace it records a sweep through your speaker and microphone. From that recording it computes the response of the whole playback and capture chain, rates the quality of the measurement and keeps it as a reproducible experiment. The app is a single HTML file. It needs no server, no account and no network once loaded, and it works when opened straight from disk.

The words OSCILLA uses for its objects (project, Studio, runtime, measurement, run, experiment, definition, calibration, trace) are defined in the glossary.

Navigation

The header has these entries: Playground, Measure, Experiments, Analyze, Synthesis, Learn, Studio and About, in that order. Analyze and Synthesis are groups. Analyze opens Analyzer, Filter Lab and Compare; Synthesis opens Synthesis, Sequencer and Presets. A group is a button that shows its list of workspaces: Enter or Space opens it and Tab walks the list, or ArrowDown opens it on the current workspace and the arrow keys move. Escape closes it. Every V2 workspace is still there under the same name, and only the way to it has changed.

• The address names the workspace. Each switch writes m=<workspace> into the page address (#m=measure, #m=analyzer, …) and adds one browser history entry, also from file://. Back and Forward move between workspaces, keep what each workspace holds and move focus to the workspace heading; a reload reopens the workspace. A link is read by one dispatcher: the Studio keys win over m, and m wins over a recipe link's mr, so #m=studio&mr=… opens Studio and still loads the recipe into Measure (ADR 0045). Copy config URL keeps the recipe and Studio keys that are in the address. Each nav item links to its workspace's address, so opening it in a new tab opens that workspace. A link that is refused does not stay in the address or in history.
• The address names a stored record. In Experiments, the experiment the detail shows is named in the address (#m=experiments&exp=<id>, no new history entry) on every path: when it opens, when the detail closes, and on return to Experiments. A definition is def=<id> and a finding finding=<id>; such an address stays until an experiment is opened. Following a connected record is a new entry, so Back returns to the record you came from and moves focus to its heading. A link names a record stored in this browser; for one that is not stored the page says so and the address names what is shown again (ADR 0048).
• Unsaved work. While something would be lost, a reload, a closed tab or leaving the page makes the browser ask first: unsaved Studio changes, a completed measurement that is not saved, a saved experiment's name or notes not yet stored with "Update name and notes", a rename being typed, a finding being written, or a level calibration (it is kept in page memory only). Where the browser allows no IndexedDB, saved experiments, findings and Studio projects live in page memory too and count as well. Studio shows "unsaved changes" and Measure "unsaved result" or "unsaved name or notes". With nothing to lose the page asks nothing. Sequencer patterns are not guarded yet.

The V2 laboratory

• Generator: sine, triangle, sawtooth and square sources, set by frequency or by note, with continuous and finite tone, pulse, burst, sweep up/down, ping-pong, chirp, siren, wobble, AM, FM, random, alternating, octave-stepping and user-defined step sequences, plus a dual oscillator.
• Analyzer: a live spectrum on log or linear frequency axes, with the requested frequency marked.
• Spectrogram: a scrolling time-frequency view, with level shown as colour.
• Microphone analyzer and compare: your microphone's spectrum and spectrogram, the detected frequency with its uncertainty, and a generator-versus-microphone comparison with freeze, averaging and peak hold.
• Sequencer: a timeline of tone, silence, sweep, pulse, chirp, burst, siren, AM, FM and random blocks, with drag-and-drop editing, keyboard control, looping and tempo-locked durations.
• Filter Lab: biquad filters with a response chart drawn from the browser's own filter response. Cutoff and Q can be dragged on the chart.
• ADSR: an attack/decay/sustain/release envelope with a draggable graph.
• Additive synthesis: a harmonic editor. The bars you see are the same coefficients that build the waveform you hear.
• Phase, Lissajous and stereo: A/B phase views, a Lissajous figure, a correlation meter and stereo routing (split, panned or mono).
• Bioacoustics: approximate hearing ranges and call examples for humans and several animal species, every value cited.
• Export: WAV of the current tone, pattern or sequence, rendered offline through the same signal chain as live playback; a PNG of the graphs; the configuration as JSON (export and import); a shareable configuration URL.
• About: the last workspace tells how OSCILLA was built and with what discipline, and shows the running build's version, commit, channel and source digest.

The V3 measurement workbench

V3 adds two workspaces after Playground: Measure takes a measurement, Experiments keeps and compares them. A measurement plays a known digital signal, records what comes back and analyses the recording offline. Its result is the observed response of the whole playback and capture chain, not of any one part of it. How to make a useful measurement is in the measurement guide. How the layers fit together is in the architecture. How each result is computed, and which tests pin it, is in the algorithm notes.

Measurement Workbench

• Guided flow. Seven steps: input, calibration, noise check, stimulus, measure, review, save. One primary action moves the flow on, and an explicit state machine owns every stage (IDLE, PREFLIGHT, NOISE_CHECK, READY, ARMED, MEASURING, ANALYZING, then COMPLETE, INVALID, ABORTED or ERROR). The preset CHARACTERIZE PLAYBACK CHAIN runs a noise check and then a 20 Hz-20 kHz log sweep, three times, at the LOW digital level. Expert settings add the sweep range and duration, the number of runs (1-10), mean or median aggregation, timing and phase.
• Setup check. Before anything plays, OSCILLA checks the microphone permission, the input device, the sample rate, the input level and the background noise. It requests echo cancellation, noise suppression and automatic gain control off, and reads back what the browser actually applied. A blocker stops the flow and a warning never does.
• Input device. The default input stays the default. Once the browser has granted the microphone, the Live input panel lists the inputs and you can choose one; the experiment records it as a hashed identifier. An input that disappears stays selected and is reported as not available; OSCILLA never switches microphones for you.
• Recipe link. "Copy recipe link" puts the measurement recipe (sweep, level, runs, timing) in the page address. Opening the link fills the setup and opens Measure without starting anything; it never carries results, calibration or a device, and an altered link is refused as a whole.
• During the run. A quality bar reports INPUT, NOISE, CLIPPING, SIGNAL and CAPTURE, and a screen reader hears one announcement per stage. While a measurement owns the output, the instrument cannot play. Escape, STOP, hiding the page or leaving the workspace aborts the measurement, and no audio node, capture or input track is left running.
• Capture. Mono PCM is recorded by an AudioWorklet loaded from a data: URL, so it also works from file://. When AudioWorklet is unavailable, a ScriptProcessor fallback records instead. The stimulus passes through the same master safety chain as every other sound, and that chain is part of what is measured.
• TEST CONTEXT. The last choice of the Input device list, "TEST CONTEXT · digital loopback (no microphone)", replaces the microphone with a known synthetic digital system; ?measure=loopback opens the page with it chosen, and the address follows the choice. The page then says TEST CONTEXT on the result and in every saved experiment. The automated tests use this mode, and it is never presented as a measurement of a physical system. Choosing an input leaves it. Entering or leaving clears the result shown, valid or invalid (a saved experiment of it stays, labelled), and the input check. A level calibration is kept on either side: one stored in TEST CONTEXT does not apply to a real input, one stored with a real input does not apply inside TEST CONTEXT, and each applies again on its own side once its input is checked.

Calibration

• Frequency-response profile. Import a microphone correction file (CSV, TXT or JSON). Errors are reported with their line numbers. A profile is identified by the SHA-256 of its points and interpolated linearly in dB over log frequency. It applies only between its first and last frequency: outside that range the curve stays uncorrected and is marked uncalibrated. The raw curve is always kept beside the CALIBRATED one. The loaded profile exports as CSV or JSON; both files are deterministic and import back to the same profile.
• Absolute level calibration. You enter an external reference (for example 94 dB SPL at 1 kHz from a calibrator) and the relative level OSCILLA observed. This is the only way to get dB SPL. It is valid only for the microphone, gain, browser settings and position it was taken with. There is no default calibration. OSCILLA stores one only once it knows the input (the setup check or the reference capture), binds it to that input and stops applying it when the input changes; a reading typed before any setup check is refused with the reason. The measurement itself checks the input it captures from and never applies a calibration bound to another one (the record then says why it is uncalibrated); until an input is checked the indicator reads PENDING INPUT CHECK. A browser that exposes no device id binds the sample rate and processing settings only, "as far as the browser reports it". A record from an earlier version whose calibration has no input says "not bound to an input".

Transfer Function

The Frequency response tab shows the magnitude recovered from the captured sweep. The capture is divided by the spectrum of the rendered sweep, with band-limited regularisation. The tab offers:

• the raw curve, a calibrated curve where a profile covers it, smoothing (1/24 to 1/3 octave) and normalisation (0 dB at 1 kHz, or the mean over 500 Hz-2 kHz). Every derived view is labelled, and the raw curve stays visible behind it.
• a valid range, which ends where the sweep has no energy or where the signal is less than 10 dB above the background noise. Stretches outside it are drawn dashed and faded.
• a cursor that prints frequencies no finer than the analysis resolution allows.

Phase is shown only when requested and when the alignment is robust. Otherwise it is absent, not guessed. The magnitude is a ratio and never dB SPL.

Impulse Response

The Impulse response tab derives the impulse response from the same sweep and the same spectral division. Time is shown in ms from the direct peak, and the absolute offset in the recording is kept. You can zoom to the direct sound, the early part or the whole response, show the analysis window, and switch to a dB view normalised to the peak. Windows and normalised views are derived objects, so the stored response never changes. The peak time includes unknown device and browser delays: it is not a time of flight and not a latency.

RTA

The analysis layer computes octave and one-third-octave band power on the standard base-10 band edges. Bands above 95 % of Nyquist are left out. An averager offers instant, fast and slow time constants, peak hold and freeze. The RTA tab of the Measure workspace draws one-third-octave band levels as bars over each band's edges, with peak hold, freeze and reset. Levels are in dB relative (dBFS-like) unless a valid level calibration applies. No IEC 61260-1 filter class is claimed. An experiment saved from Measure does not store band levels yet: its results.rta is empty, although the format, validation and CSV export already support them.

Experiments

• What is recorded. Every saved measurement becomes an experiment. It records the recipe (stimulus, runs, analysis settings), the output level, the input device and the requested and applied constraints, the calibration (profile name and identity, level calibration), the sample rate and runs, the quality assessment and the algorithm ID of every result. It also records the product version and build (including the build's source digest and, for the deployed page, the artifact SHA-256), with a configuration hash and a result hash. The result hash (version 4) covers the results, the verdict, the calibration, the input, the output, the runs (each with a stable id, run-1, run-2, ...), the build, the recipe and the definition the experiment was executed from. Files with a version 1, 2 or 3 hash still verify in their own version.

• Definitions. A definition says what to measure and how: the recipe as asked for, the conditions declared for every experiment and, optionally, the lowest quality verdict that meets it. Its hash covers only those fields, so a rename never changes it. Editing them creates a new version; earlier experiments keep the version they used. "Run this definition" runs its latest version, and Repeat loads a saved experiment's version again. An experiment records the version only when its measurement ran exactly that recipe. One without a definition, or whose setup was changed, records a definition derived from the recipe it played and marked as derived, never as authored. An experiment is shown under a stored definition's name only when that definition has its version with its hash (ADR 0043, proposed).

• Recorded as measured. The calibration saved is the one the measurement applied, and the notes are those at its start. A profile loaded, a correction switched or a level calibration made after the measurement never becomes part of its record, and the Experiment panel says so; notes edited later are saved as an annotation. An experiment from an earlier version whose named calibration its own results contradict still opens and imports, and is marked as such: it is shown and compared as uncalibrated, never in dB SPL.

• Only a log sweep is repeated. The measurement engine measures log sweeps only. A file whose stimulus is anything else (white or pink noise, a sine, a chirp) still imports and is kept as it is, with a warning that this version cannot measure it; Repeat and "Run this definition" refuse it rather than run a log sweep in its place.

• Evidence. A saved experiment's detail answers two questions from what its record stores. "What produced this value?" traces the stored response value at a frequency you enter (1 kHz by default) through the analysis algorithms, the capture (input, sample rate, processing flags), the calibration as applied, the runs, the definition version, the build and, for an experiment run from Studio, the Studio graph the recipe was derived from with the measured path it names (the nodes, connections and measurement clips the measurement used). "Can I repeat this?" is a checklist: each item is recorded, partial or not recorded, with its reason, and there is no score. The result hash is recomputed and its reason says what it covers; the algorithm ids, environment notes and lineage are covered by no result hash. The raw capture is never retained: OSCILLA stores the derived result (see ). Anything the record does not store reads "not recorded" (, proposed).

Measurement quality

Every measurement is rated GOOD, USABLE, POOR or INVALID by a versioned rule set (oscilla.confidence.v4 for new measurements; v1-v3 are kept so stored ratings reproduce). The rules use named metrics: signal-to-noise, clipping, dropouts, discontinuities, frequency coverage and resolution, repeatability, and calibration. Each rating comes with its reasons, and each reason carries its value and unit. A check that was not made reads NOT MEASURED. Severe clipping, an empty capture, or a dropout or discontinuity inside the sweep makes a run INVALID; milder clipping lowers the rating. Statuses are shown with text, a glyph and a shape, never colour alone. The rationale is in the proposed ADR 0025.

Scientific limitations

• A measurement is of the whole chain. That chain is the browser's output, the operating system, the DAC and amplifier, the loudspeaker, the room, the microphone position, the microphone, its ADC and the browser's input path. A room measurement is not "the speaker's response".
• Browsers may process the input anyway. OSCILLA requests input processing off but cannot enforce it. When the applied settings cannot be confirmed, the result says so.
• SPL needs a level calibration. Without a valid absolute level calibration, nothing is labelled dB SPL. A frequency profile alone never gives SPL (ADR 0017, ADR 0020, both proposed).
• Results come from captured PCM. Every result is computed from captured PCM by deterministic offline DSP. The live analyser is feedback only (ADR 0018, proposed). Each stored result names its algorithm by a versioned ID (ADR 0024, proposed).
• The analysis runs in a Worker. It is one serializable task, run in a Worker started from a data: URL of the page's own analysis script so that no step blocks the page; without Worker support the same code runs inline and yields between steps, with identical results (gap G21 in the algorithm notes, resolved).
• What the tests prove. The automated tests check the digital pipeline, the mathematics on synthetic systems with known answers, the browser APIs and the interface. They cannot prove how your hardware, room or browser behaves.
• No medical or certification claims. OSCILLA is not audiometry and not an IEC 61672 sound level meter.

The V3.1 Studio

Studio is the last workspace before About. It is a patching and composition workspace over the same audio engine: no second engine, and the engine's master chain and limits apply. How to use it, with the keyboard shortcuts, is the Studio user guide. What it consists of (schemas, node and port types, tests, size, ADRs, records) and how its release and deployment are evidenced is the final report.

• The model is the source of truth. A Studio document is a plain, versioned StudioModel: a graph of typed nodes and ports, a timeline of tracks and clips, automation lanes, and transport settings. Every edit is an action with undo and redo. The audio graph is compiled from the model and patched in place with crossfades, so editing during playback does not click. Details are in the model, the compiler, the timeline and patches and provenance.
• Graph editor. Nodes look like the Signal Path boxes, joined by cables drawn in one SVG layer. Port glyphs show the signal type, and only compatible ports connect. A rejected connection, including a feedback loop without a delay, says why in words. The editor offers:
  • pan, zoom, and frame all or the selection
  • a node library
  • dropping a cable on empty canvas to pick a compatible node
  • rectangle selection, copy, paste, duplicate and delete
  • an inspector generated from each node's parameter schema, with units; with nothing selected it edits the transport and document settings (tempo, time signature, loop, notes)
  • search: / finds a node by name, type or category and frames it
• Timeline, transport and automation. Tracks hold clips that you create, move, resize, split and delete with snapping. The timeline also has a loop region, markers, a playhead that follows the audio clock, and automation lanes in each parameter's own scale. STOP and Escape release every node and source.
• What runs, and what each edit did. With nothing selected, the Inspector's Runtime section says whether the graph on screen is the one that plays: running, not applied, a previous configuration still running, refused or failed, with the diagnostic codes (ADR 0039, proposed). Its Trace section follows each recent edit, undo, Play and Stop under one operation id. It shows the action, the compiled plan with its hash, whether the running graph applied it, and each parameter value and connection gain the audio nodes report they were given, at its audio time. A setting that changes nothing audible at once is shown as stored. A refused edit shows its code, an edit made while stopped says it was not applied, and a parameter an automation lane drives is shown as owned. A selected node's Inspector lists only the operations that touched it. The trace is kept in memory for the session and is never saved or hashed (, proposed).

Studio output and Playground output are exclusive: starting one stops the other, and a measurement stops the Studio.

Not yet built:

• a minimap
• node groups
• dragging several clips at once
• pinch zoom on the timeline

Safety and measurement limits

• Start quietly, especially on headphones. Loudness is a poor guide to acoustic output, above all at very low and very high frequencies. Open-ended patterns stop at a hard time limit unless you allow continuous playback for the session, and a limiter caps the output.
• Levels are relative, not SPL. Every level is relative to digital full scale (dBFS-like) and labelled as uncalibrated. A browser knows sample values, not sound pressure. The only exception is the Measure workspace with a valid absolute level calibration that you supply from an external reference.
• The microphone is not calibrated. Its response, the input processing and the room are unknown, so readings are only comparisons. In Measure, a frequency-response profile corrects the microphone only inside the profile's range. Detected frequencies are never shown with more precision than the analysis resolution allows.
• Measurement sweeps start at a low digital level. Do not wear headphones during a loudspeaker sweep. Small speakers can be overloaded below about 50 Hz before you hear anything. The measurement guide has the details.
• Speaker output is unknown. Generating a frequency digitally does not mean your hardware reproduces it accurately, or at all.
• Hearing ranges are approximate. They depend on the threshold criterion and on the individual. Each entry cites its source (for example Heffner & Heffner 2007) and lists differing published values.

The reasoning is in the proposed ADR 0017 and the rule project.no-fake-science.

Architecture

src/  (ES modules, plain CSS, the src/index.html shell)
  -> scripts/build.mjs              esbuild (pinned): one IIFE app bundle + one stylesheet
     scripts/build-analysis-worker.mjs   the analysis library (one IIFE), imported by the app
  -> scripts/pack-single-file.mjs   pure string assembly; drops developer comments and
                                    markup indentation (pre, textarea, script, style verbatim)
  -> dist/index.html                the whole app: CSS, p5 block, analysis library, app
                                    bundle, licence notices, one build-metadata region

• Deterministic build. There are no timestamps or absolute paths, so the same inputs give the same bytes. npm run build:check rebuilds in memory and fails if the committed file differs. npm run verify-dist checks the artifact statically: nothing fetched or imported at runtime, no module scripts, licence notices present, size budget met.
• Vendored p5.js. p5.js is embedded byte-for-byte from its npm package as its own <script data-vendor="p5@…" data-sha256="…"> block. It is never bundled into the app code, and verify-dist checks it against the pinned package file (ADR 0013). Alpine.js and uPlot are bundled; Lucide icons are inlined at build time (ADR 0012).
• One copy of the analysis. The offline analysis (the closure of src/js/measurement/analysis-worker.js) is bundled once, into its own classic <script data-analysis> before the app. The app imports it through that script's global and carries no copy; the analysis Worker is started from a data: URL of that same script text, so the Worker and the inline fallback run the same code and no file is loaded. The build fails if an analysis module is bundled into the app as well (ADR 0026, resolution note).
• dist/ is committed. A clone runs without npm, every pull request shows how the artifact changed, and GitHub Pages serves the bytes CI checked (only the metadata region below is stamped) instead of running its own build.
• Deploy-time provenance stamp. A committed file cannot contain the hash of the commit that contains it. So the build writes one inline JSON region that records the version and a digest of the build inputs, with commit: null. The Pages workflow (.github/workflows/pages.yml) rewrites only that region with the deployed commit, the production channel, the commit date, the SHA-256 of the committed file (ADR 0028) and the release state: whether the commit is its version's tag, and if it comes after the tag, how many commits after. Pages deploys every push to , so between releases the page names itself (N commits after ); only a release page reads ().

Why one file?

You can double-click a single file and it works, even offline. GitHub Pages serves that same file. The modular source exists so that the code can be tested and so that parallel work does not collide; users never see it. See ADR 0011 and the rule project.single-file-deliverable.

Run locally

Double-click dist/index.html. No build, server or network is needed. Some browsers refuse microphone access from file://. In that case the microphone panel and the Measure setup check say so, and everything else keeps working. Where IndexedDB is unavailable from file://, Experiments keeps saved experiments in memory for that page view and says so; export them to keep them. To use the microphone locally, serve the repository on localhost and open dist/index.html there:

python3 -m http.server 8000     # then open http://127.0.0.1:8000/dist/index.html

Or use the public URL: https://korczis.github.io/oscilla/

Development

Requires Node.js 22 or later. The fast check also runs majordomus doctor, so it needs the majordomus CLI.

npm ci
npm run verify          # fast: unit tests, version check, build check, artifact rules
npm run build           # src/ -> dist/index.html; commit dist/ together with the source change
npm run release-gate    # full gate, including the Playwright browser suites
npm run visual          # compare a screenshot with the visual reference at 1536x1024

dist/index.html embeds a digest of every build input (src/, package.json, the lockfile, the build scripts), so any change to them, including a merge from main into a long-lived branch, makes it stale by design: run npm run build and commit the result, or build:check and CI fail.

The browser suites need Playwright's browsers (npx playwright install chromium firefox webkit). Work lands through small pull requests. CI runs the gate on every pull request, branch protection requires the gate check, and a merge to main redeploys Pages.

Two of the gate's jobs check the pull request rather than the product. fail-first: when the title starts with feat or fix, a unit test the pull request adds or changes must fail on the merge base and pass on the head, or the body carries fail-first: n/a <reason> (node scripts/fail-first.mjs --title "<title>"). review-verdict: a change under src/js/audio, src/js/analysis, src/js/experiments, src/js/studio, src/js/measurement, src/js/calibration, src/js/core/storage*, src/js/core/safety*, the MEASURE, Experiments and Findings adapters, scripts/release-*, the build, stamp and deploy-verification scripts, the release rules' tests or .github/, or to the programs and tests of these rules, needs a reviewer's verdict in .ai/repo/reviews/<pr>.yaml for the guarded content the pull request changes (node scripts/review-verdict.mjs --pr <number>; --content prints the digest to record, which a merge of main that leaves those files alone does not change). CI judges a pull request with the base branch's copy of both programs, and ci.yml runs on pull requests only. A pull request is bound from the first run of a head that contains these jobs. The rules are project.fail-first, project.review-verdict and project.ci-bounded under .ai/repo/rules/project/.

Browser support

The release gate runs the built dist/index.html in Chromium, Firefox and WebKit (the engine behind Safari) through Playwright. Each browser loads the file from file:// and from a GitHub-Pages-like /oscilla/ sub-path, and the run must produce zero console errors.

Only these three engines are checked. No real device is: Safari on iOS, Chrome on Android and Edge have not been tried for sound starting only after a tap, resuming after the page returns from the background, or hold-to-play by touch. The owner declined real-device checks for now on 2026-10-29 (plan issue S071).

Testing

Layer	Where	What it covers
Unit	tests/unit/	Pure modules (DSP, analysis, sequencer, charts), the packer, the artifact rules and the release tooling, all under node --test
V1 freeze	tests/freeze/	Golden vectors that pin V1 behaviour (ADR 0014)
Browser	npm run test:browser, test:engine, test:dsp, test:labs, test:sequencer	Playwright suites on the built page: the app gate (tests/browser/app.cjs), layout (tests/browser/layout.cjs), the V2 final-QA regressions (tests/browser/qa-regressions.cjs), navigation history and unsaved work (tests/browser/navigation.cjs), the MIDI support state (tests/browser/midi.cjs), the V1 engine port (tests/browser/engine-v1port.cjs), DSP (tests/browser/dsp.cjs), labs (tests/browser/labs.cjs) and the sequencer (tests/browser/sequencer.cjs)
Visual	scripts/visual-gate.mjs, tests/visual/	The 1536x1024 reference and named regions, compared region by region with thresholds measured from run-to-run variance (ADR 0029)
V3 unit	tests/unit/v3-*.test.mjs	Measurement core, transfer and impulse response on synthetic systems with known answers, RTA and aggregation, calibration, quality, experiments (schema, round trip, corrupt imports, store), goldens per algorithm ID, the engine on a fake io and the view models, all in npm test
V3 browser	npm run test:measure	tests/browser/v3-measure.cjs: the measurement engine on real Web Audio, a recovered digital loopback response, limiter transparency, 0 nodes after finish and abort. tests/browser/analysis-worker.cjs: the offline analysis in its Worker against the inline run, identical results, no inline fallback, abort. tests/browser/v3-ui.cjs: Measure and Experiments of the built page, guided flow, abort at every stage, calibration, experiment import, compare and export, and no "SPL" without a level calibration. All run in Chromium, Firefox and WebKit, from and

Every V3 browser check runs on a TEST CONTEXT digital loopback or a fake microphone. No automated test proves how a physical speaker, room or microphone behaves.

npm run release-gate is the authority on what the gate runs and in what order; the table names every suite and visual script its test:release runs (tests/unit/docs-derived.test.mjs holds it to package.json). tests/README.md describes each file and how to run it alone.

Versioning and releases

• One source. The version field in package.json is the only product version (ADR 0027). The status bar, the About workspace, the exported configuration's oscillaVersion and window.OSCILLA.version all derive from it at build time. npm run version:check fails when any of these disagree, or when the current version is hard-coded anywhere else. That is why this README never names it. File-format schema versions are separate integers (ADR 0023).
• SemVer. MAJOR means an incompatible change to the configuration format or to a user or public contract (type!: or a BREAKING CHANGE: footer). MINOR means a new compatible capability (feat:). PATCH covers fixes, performance and any non-conventional commit. Commits that are only docs, chore, ci, test, refactor, style or build need no release. A new product generation (a new primary workspace family, such as V3's measurement workbench) may also take a MAJOR version without an incompatible change: the owner sets the untagged version in package.json, and release:prepare confirms it because it covers the level the commits require.
• Release flow.
  1. npm run release:analyze reads the conventional commits since the last v* tag and proposes the level, with a reason for each commit.
  2. npm run release:prepare starts from a clean tree. It bumps package.json once (or confirms an untagged version), rebuilds, and runs version:check, the release gate and majordomus doctor. If anything fails, it restores the files. It never tags. Land the result on main through a pull request. It refuses to start while the newest release has no record (step 4), and it refuses the first stable release of a new major (X.0.0, and equally X.0.1 or X.1.0 typed into package.json) that no published X.0.0-rc.N preceded (npm run release:prepare -- --prerelease cuts the candidate; ADR 0047). The gate receipt it writes binds every tracked file except the release records, so any other pull request merged before the publish means running it again (rule ).

Majordomus

The repository is supervised by Majordomus. .ai/ holds the project rules (.ai/repo/rules/project/), the plan (milestones and issues in .ai/repo/project/), the architecture decisions (.ai/repo/adrs/), features, use cases, workflows and knowledge notes. majordomus plan status shows milestone progress. AI workers start at AGENTS.md (Claude Code: CLAUDE.md).

What is checked, and where:

• On a commit and a push (the git hooks a checkout wires, declared in .ai/repo/policy.yaml; majordomus doctor checks that the hook names each one): before a commit, majordomus worktree guard refuses a branch committed outside its canonical worktree (docs/WORKTREES.md), git diff --cached --check refuses a staged conflict marker, and majordomus doctor validates the layer; majordomus finish --check refuses a push outside the active task's scope. npm run verify first checks that the local majordomus is the version CI pins (scripts/majordomus-pin-check.mjs), then runs majordomus doctor too.
• In CI, on every pull request (.github/workflows/ci.yml, all required through gate): the test suites; tests/unit/knowledge-integrity.test.mjs, which fails when a claim, rule, bootstrap or this README names a file that does not exist, and when a claim's test or a rule's x-majordomus test is not run by CI (other paths are checked only to exist), when a rule's enforcement section names nothing CI runs, when a document names a project rule that is not in force, and when a script header says a workflow runs a file it does not run; tests/unit/repo-hygiene.test.mjs, which fails on a conflict marker in a tracked file; tests/unit/storage-inventory.test.mjs, which holds the privacy table below to the code; tests/unit/no-fake-science.test.mjs; and majordomus doctor at a pinned version.
• Not checked by a machine: whether the test a project rule names actually decides the rule (project.rules-name-their-enforcement checks that it exists and runs); the advisory session guidance in project.shared-machine-discipline; use-case coverage of the claims is advisory; the worktree guard passes a detached HEAD and sees only commits. An ADR's status proposed means recorded, not accepted (see .ai/repo/adrs/README.md).

V3 Measure is specified in docs/specs/oscilla-v3-measure.md (milestones M012-M020). Its features, use cases and claims are under .ai/repo/features/, .ai/repo/use-cases/ and docs/CLAIMS.yaml. Each claim names the file that implements it and the test that proves it.

V3.1 Studio (docs/specs/oscilla-v3.1-studio.md, milestones M021-M033) has shipped (the V3.1 release tag); its features, use cases and claims are in the same places, and majordomus plan status shows which Studio issues remain open.

Privacy

There are no analytics, no server and no account. The page fetches nothing at runtime. The microphone starts only when you press "Use microphone". Its signal goes to a local analyser and is never played back, recorded or uploaded. Exports are downloaded to your machine. A configuration URL contains only your settings, and it leaves your machine only if you share it.

In Measure, the microphone opens only for the setup check, a measurement, a level-calibration reference capture or the live RTA, and every track is stopped when they end or are aborted. The live RTA keeps only its latest analysis window, overwritten frame by frame. The setup check reads the input level from a 0.3 s window, and the reference capture (3 s) keeps only its level reading and the facts of the input; both recordings are dropped as soon as the level is read. A measurement's recording (the background-noise check and every run) is analysed in the page and lives only as long as that analysis: when the measurement completes, is found invalid, is aborted or fails, nothing in the page references it any more. It is never stored, exported or uploaded, and OSCILLA offers no option to keep it. A saved experiment keeps derived results: the frequency response (with the aggregate of repeated runs), the impulse response, the quality assessment and the facts of the run. The impulse response is computed from the recording of one run and is not anonymised: other sound the microphone picked up after the sweep had passed a frequency, in particular in the post-roll after the sweep (1.5 s by default), can be recovered from it. A saved experiment also contains the input device's label and a one-way hash of the browser's device ID, when the browser reports them, along with your notes. All of it goes into an exported file, so check it before you share it. Calibration profiles and level calibrations are kept in page memory only. The policy, its reasons and the tests that hold the code to it are ADR 0049 (proposed).

Browser storage holds only these keys and one database, oscilla-experiments (version 4):

Storage	Key	Contents
localStorage	oscilla.presets	Your saved presets
localStorage	oscilla.v2.theme	Light or dark theme
localStorage	oscilla.v2.analysisTab	The last analysis tab
sessionStorage	oscilla.history	Recently played configurations (this tab only)
sessionStorage	oscilla.safetyNoticeCollapsed	Whether the safety notice was collapsed
IndexedDB	oscilla-experiments, object store experiments	Your saved experiments, in the exported file form
IndexedDB	oscilla-experiments, object store summaries	One small row per experiment for the list (name, date, schema and product version, quality status, result hash, size, its definition version, and the repeat, duplicate and Studio hashes it stores)
IndexedDB	oscilla-experiments, object store studio	Your saved Studio projects and patches (name, save time, studioHash and the document)
IndexedDB	oscilla-experiments, object store studioSummaries	One small row per Studio project or patch for the library list
IndexedDB	oscilla-experiments, object store definitions	Your experiment definitions, each with its versions (recipe, declared conditions, acceptance criterion, name and notes)
IndexedDB	oscilla-experiments, object store findings	Your findings (statement, status, notes, the evidence each cites and the id and result hash of each cited experiment)

Experiments and findings are deleted only when you delete them. Permission to play continuously is never stored.

Licences

An HTML comment at the top of dist/index.html carries the name, version, licence and full licence text of every bundled third-party package:

• Alpine.js (including its @vue/reactivity and @vue/shared) and uPlot: MIT.
• lucide-static (icons): ISC.
• p5.js: LGPL-2.1. It is shipped unmodified as a separately identifiable script block, and any compatible p5.js build can replace it.

OSCILLA's own code is released under the MIT License (see LICENSE). The same notice comment carries it first, so the single published file contains its own licence text.