Aurora · Technical stack

Version 0.1.0 · Release handoff · 14 October 2026

Aurora is a native, free, open-source audio analysis and reactive visual plug-in. It combines sample-derived meters with six GPU scenes, 24 complete appearance presets and detailed display controls. This document describes the code and binaries in this release, the tools used to produce them, and the limits of the measurements and validation.

What is delivered

The macOS download contains both plug-in bundles and release documentation. The corresponding-source download contains Aurora source, tests, build scripts, technical records, the small editable Pearl Cloud design project and the exact vendored JUCE source with its notices. The development preview and QA applications are tools for synthetic signals; they are not standalone system-audio monitoring products.

Platform scope

This release does not include Windows, Linux, AAX, VST2 or a standalone audio capture application. A universal binary includes Intel machine code, but Intel runtime compatibility has not yet been tested. Actual Ableton playback of this revision and other GPU configurations remain unverified; the completed checks are listed later in this document.

The CMake source contains an intended deployment default of macOS 11.0. The verified release was built with an empty deployment-target cache entry and macOS 13.3 SDK, so its actual minimum is 13.3. This handoff states the binary requirement rather than advertising the unverified intended default.

Native runtime & host integration

The plug-in is compiled software hosted by a DAW.

JUCE modules and system linkage

The CMake target links juce_audio_utils and juce_opengl plus JUCE recommended configuration flags. JUCE resolves their supporting modules, including audio processors, audio basics, audio formats/devices, GUI, graphics, events, data structures and core utilities.

The verified link command includes AudioUnit, AudioToolbox, CoreAudio, CoreAudioKit, CoreMIDI, Cocoa, Foundation, IOKit, Security, Accelerate, QuartzCore, OpenGL, WebKit and DiscRecording, with weak Metal and MetalKit linkage. Some arrive transitively from JUCE. This list does not imply Aurora captures MIDI, uses a browser UI, burns discs or renders its scenes with Metal.

Build-time feature switches

JUCE_WEB_BROWSER=0
JUCE_USE_CURL=0
JUCE_VST3_CAN_REPLACE_VST2=0
FORMATS AU VST3
IS_SYNTH FALSE
NEEDS_MIDI_INPUT FALSE
NEEDS_MIDI_OUTPUT FALSE

The UI uses local system typography and native widgets. There is no Electron, React web front end, embedded website, CDN, telemetry service, cloud database, machine-learning model or external shader service at plug-in runtime. A hosted download page is separate from the plug-in and requires no Aurora backend.

Audio & analysis architecture

Real-time audio, worker analysis and graphics have separate responsibilities.

Audio callback contract

The callback performs no buffer allocation, FFT, rendering, mutex locking or operating-system event notification. It does not alter, normalize or delay the DAW’s samples. The processor reports zero latency and accepts only matching mono or stereo buses. A null right input in the standalone analyzer duplicates left visually; mono loudness counts one channel rather than two.

Discontinuities and bounded memory

FIFO overflow is counted and marks a discontinuity. The worker discards its pending backlog and resets analysis windows so missing samples are not joined into false continuous measurements. Reset or format changes also invalidate old history. The audio path remains untouched. Incoming PCM is not retained indefinitely or written to a file; fixed rings and histograms keep working storage bounded with session duration.

Timing limits

Analysis is asynchronous. Offline exports can advance faster than the worker and drop analysis data, while the exported audio remains unchanged. The 80 ms waveform display buffer affects the visual timeline only. Freeze holds the display, while audio and analysis continue. Actual frame delivery depends on the host, system load, GPU and display scale; repaint targets are not guaranteed frame rates.

Meter definitions & accuracy

Measured data and creative visual controls are kept separate.

What “estimate” means

Integrated gate decisions use each occupied histogram bucket’s mean energy. Blocks near the relative threshold may be included or excluded together, although the final average uses actual energies rather than rounded bucket centres. There is no fixed session-duration expiry. This implementation is not a certified BS.1770 / EBU R 128 meter and has not passed a full standards compliance suite.

The analysis accepts 8–384 kHz sample rates, recalculating filter coefficients per rate. Time windows round to whole samples. Invalid formats are ignored and nonfinite analysis samples become zero; host audio is still not rewritten. Level fields use a finite −120 dB floor, also used before enough loudness samples exist.

Excluded measurements

Aurora does not currently measure true peak, loudness range or calibrated analog VU/PPM. The low/mid/high controls used for animation, visual sensitivity, waveform colours, automatic stereo display gain and scene transients are creative encodings. They do not change calibrated meter values and are not beat or tempo detectors.

Waveform & instrument rendering

The visual detail is derived from stored sample statistics.

Continuous waveform history

The worker accumulates every sanitized sample into buckets of round(sample rate / 1,000) samples. Each channel retains signed minima/maxima, the exact first sample positions of those extrema, double-precision squared-sample energy, filtered-band energy and 65 signed amplitude-occupancy counters. The ring retains at least 24.25 seconds. An unfinished bucket is published as a replaceable tail, so stopping between bucket boundaries does not erase final samples.

At the actual display pixel density, the editor groups only contiguous buckets on sample-time boundaries. Energies and histogram counts are summed before deriving RMS and colours. Missing intervals stay blank. This preserves measured extrema and avoids averaging already-normalized colours. The histogram is quantized, does not preserve sample order and cannot reconstruct individual PCM samples.

Other meter surfaces

The spectrogram stores a 480 × 256 cache of UI-sampled FFT history, up to 24 seconds, and recolours retained dB data through a lookup table. It is approximate wall-time history, not a lossless spectrogram recording. The stereo display accumulates mid/side sample density into a 256-square cache, with configurable persistence and display gain. Spectrum traces and trails project measured data onto a logarithmic axis and clip at Nyquist.

Creative scenes & GPU pipeline

Procedural shaders react to copied audio features.

The six scenes are Folded Light, Liquid Aperture, Pearl Cloud, Night Transit, Diffraction Veil and Orbit Loom. Scene selection, camera orbit, zoom, three-stop palette, theme, exposure, bloom, saturation, speed and sensitivity are editable. VisualReactivity separates artistic response from numeric metering with adaptive normalization, 18 ms attack, 160 ms release and a 180 ms transient envelope; missing snapshots release after 250 ms.

Pearl Cloud: persistent fluid and layered material

PearlFlow uses floating-point ping-pong textures for velocity, pressure and pigment. Its bounded fixed steps perform velocity advection, curl/confinement and audio forcing, divergence, 12 pressure iterations, pressure projection and pigment transport. Limited MacCormack correction preserves fine dye structure without introducing new extrema. The production pigment canvas has a fixed 848:512 aspect; the solver’s long side is 256 cells and the dye long side is 768 texels.

PearlFlowMaterial integrates three curved optical strata over 128 samples per view ray. Density, relief, transmission and highlights create the pearlescent volume; a support mask contains it. Colour channels stay palette-independent so colour edits can update the appearance immediately. Silence and Freeze stop simulation advance. A zero flow-speed control also holds motion. The fallback shader is the earlier deterministic design study.

Shared rendering and performance choices

Only Pearl Cloud initializes and advances the fluid solver. The other five scenes use their own procedural geometry/material shaders. All scenes receive a floating-point finishing pass with quarter-resolution bloom; finishing is not fed back into the simulation. Camera framing considers rotated bounds, while intentional zoom can crop the image.

Uniform locations are cached after linking. Unchanged frozen scenes avoid redraws. Covered or absent scene panels skip updates, and Customise parks the existing OpenGL surface outside the visible area to preserve its context and resources. Closing the editor releases its GPU context. Palette, spectrum and stereo caching reduce repeated CPU work without reducing measured waveform resolution or Pearl Cloud’s material sampling.

Optional Diffusion Studio authoring

Diffusion Studio v0.211.0 was used to edit and render the earlier Pearl Cloud shader study. Its project is TypeScript/TSX plus GLSL, with solid-js and @diffusionstudio/jsx supplied by the editor. There is no local npm dependency installation for that project. Studio is optional and is not linked, bundled or required by Aurora. Despite its name, no diffusion model or runtime AI is part of the plug-in.

design/pearl-cloud/pearl-cloud.glsl generates shader.ts for Studio and Source/PearlCloudShader.h for the native fallback. scripts/sync-pearl-cloud.py checks those embeds. The current persistent solver and material live in PearlFlow.h and PearlFlowMaterial.h; the earlier Studio renders do not demonstrate that newer engine’s performance.

Appearance, presets & persistence

Presentation settings never rewrite audio measurements.

Aurora supplies 24 complete factory looks, 12 named palette choices plus Custom, four material themes and four layouts: Studio, Meter strip, Waveform and Custom. The appearance model adds 96 validated custom settings to the core selectors, colours, camera and intensity. A complete factory look sets all 112 appearance XML attributes explicitly.

Storage contracts

Host state is a JUCE ValueTree serialized to XML and copied to the host’s binary state block. Its root is AuroraMetersState, version 1; it includes appearance and Freeze. Imported appearance presets use a separate appearance-only contract. Finite values and limits are validated, RGB values are masked to 24 bits and module positions remain a permutation. Missing older properties receive defined defaults.

The local macOS library is ~/Library/Aurora/Presets/, one .aurora XML file per saved appearance. Presets contain no recorded audio, FFT history, loudness integration or measurement history. Loading/importing a preset or resetting appearance preserves current measurements and Freeze. The main Reset button separately clears measurement state.

UI behavior

Customise is a native dropdown within the editor, with scrollable content in short layouts. Toggle or Escape closes it. Header layout selection closes it and reveals the chosen meters. Controls synchronize only when their model changes, preventing timer refreshes from erasing an asynchronously delivered menu selection. Camera drag, wheel/pinch zoom and reset remain available for the 3D scene.

Build tools & reproducible source

Tools used to author and package Aurora are separate from runtime dependencies.

Standard macOS build

Install Apple Command Line Tools and Python 3, extract the source archive, then run from aurora-meters:

xcode-select --install
./scripts/build.sh

build.sh obtains JUCE 8.0.6 if needed, creates .tools, installs pinned CMake/Ninja, configures Release for arm64;x86_64, builds with four jobs, runs CTest and ad hoc signs macOS bundles. With the included JUCE tree it does not need a fresh JUCE clone; the first tooling install still requires internet. Nothing is automatically installed into a DAW.

For a release with an explicit deployment target, pass -DCMAKE_OSX_DEPLOYMENT_TARGET=13.3 when configuring. Do not infer a binary’s minimum OS from the default in CMakeLists.txt; inspect its Mach-O metadata. Changing the target is a new build that requires validation.

.tools/bin/cmake -S . -B build -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_OSX_ARCHITECTURES="arm64;x86_64" \
  -DCMAKE_OSX_DEPLOYMENT_TARGET=13.3
.tools/bin/cmake --build build --parallel 4
.tools/bin/ctest --test-dir build --output-on-failure

Validation & measured performance

Evidence is scoped to the fixtures and hardware actually tested.

The 14 October 2026 revision built universal AU, VST3 and QA applications. Apple’s Audio Unit validator passed. Signed installed executables matched the tested build hashes. The full machine-readable record is docs/inline-controls-validation.json; the readable sequence of revisions is docs/VALIDATION.md.

Isolated CPU comparison

Median stereo raster work fell from 14.561 ms to 0.462 ms. Full spectrogram recolouring fell from 58.895 ms to 10.740 ms. These compare retained test-only baseline routines with the production renderer on identical synthetic data. Output pixels match exactly. They are timings of those routines, not whole-editor, DAW or audio-thread timings.

Isolated GPU comparison

On Apple M2 Max at 1,440 × 900 physical pixels, 30 synchronized frames per scene showed 64–75% lower median rendering cost for the five non-Pearl scenes: 2.357–2.900 ms before and 0.712–0.881 ms after. The baseline deliberately reinserts the previous unused fluid workload into the current renderer; it is not an old-binary comparison. GL checks passed, inactive fluid pixels stayed unchanged and Pearl Cloud still evolved. No Pearl Cloud speedup is claimed.

What these tests do not establish

Fixtures use synthetic PCM and open no audio device. Results do not establish Ableton frame rate, real-time audio guarantees, Intel runtime compatibility, every host/version/GPU combination, notarization or full ITU/EBU certification. Prior waveform tests also cover exact extrema, energy grouping, partial tails, clipping, gaps, fixed axes, freeze/resume and cache correctness. The native GUI and GPU runners require a graphical desktop and are separate from headless CTest. This handoff document is generated with Python 3 and ReportLab; pypdf checks its extracted text and Poppler renders the pages for visual inspection. These document tools are optional and not plug-in dependencies.

Distribution, signing & installation

The release can be served as ordinary downloadable files.

Release artifacts

The public binary archive is Aurora-0.1.0-macOS-universal.zip and the corresponding-source archive is Aurora-0.1.0-source.zip. Keep the matching source and dependency notices alongside the binary when publishing the release. A website can link these files directly; GitHub Releases can host them as assets. Aurora needs no server code, package manager, runtime database or account service. This handoff does not create or publish a website.

Signature status

The bundles are locally ad hoc signed with codesign --sign - and pass strict signature verification. They are not Developer ID signed or notarized. Local validation does not establish acceptance of a browser-downloaded, quarantined copy on another Mac. This is a material release property, not a notarized installer.

DAW installation locations

~/Library/Audio/Plug-Ins/VST3/Aurora.vst3
~/Library/Audio/Plug-Ins/Components/Aurora.component

Copy the VST3 and/or Audio Unit bundle into the corresponding user Library folder, then enable that format’s system plug-in location and rescan in the host. Look for Aurora under Soft Club and place it on a track or master bus. Actual host labels and menus depend on the host version. The source repository also provides scripts/install-macos.sh, which installs a locally built release and backs up an existing Aurora bundle.

Source packaging and shader consistency

python3 scripts/sync-pearl-cloud.py --native --check
python3 scripts/package.py

scripts/package-release.py wraps the validated base archives, documentation and screenshots into Aurora-0.1.0-website-kit.zip. This standard-library Python packager creates the public 0.1.0 downloads, preserves executable modes and writes checksums, with the matching source and dependency notices. It does not publish to GitHub or a website.

The original package.py generates the base Aurora-0.1-macOS-universal.zip and Aurora-0.1-source.zip inputs. It first checks that the editable GLSL and generated Studio/native embeds match. It includes Aurora source, Tests, scripts, docs, CMakeLists.txt, README, LICENSE, THIRD_PARTY.md and the JUCE tree. The small Studio project is explicitly enumerated. Git metadata, build outputs, tool environments, node_modules, caches, backups and working captures are excluded from the source ZIP. The binary ZIP carries the AU/VST3 bundles and project notices.

Releasing a later revision

Build and test the new source, verify architecture and actual minimum OS, sign with the intended release identity, validate AU and representative hosts, and regenerate matching binary/source archives. Use fresh checksums for the final files. Developer ID signing and notarization would be additional release work; neither is implied by the current ad hoc signature.

Licenses & provenance

This inventory records project notices; the included license texts remain authoritative.

Research references

Ghost and MiniMeters were studied as functional and visual references. No vendor native source, binaries, graphics, presets or branding were copied into Aurora. Public open-source visualizer research also examined projectM, Butterchurn, Pulse, Prism and OpenMeters. Their renderers or preset collections are not incorporated. The solver adaptation listed above is the explicitly retained third-party implementation reference.

Research links, inspected revisions and distinctions between observed demos and source inspection are recorded in docs/REFERENCE-RESEARCH.md and docs/VISUAL-RESEARCH.md. The earlier Soft Club and later Flight Deck directions are original treatments; the release does not bundle Cowboy Bebop imagery, logos or media.

Source and notices stay together

The source archive includes the exact JUCE source used for the release, its dependency notices and Aurora’s build scripts. Read LICENSE, THIRD_PARTY.md and the relevant vendored files for their actual terms. This document is an implementation inventory and does not replace those texts.

Source map & further reading

Paths below are relative to the extracted aurora-meters source folder.