Macos on Charlie Chiang's blog

Building Audio Insight: An Audio Analyzer That Actually Renders Smoothly

Sun, 16 Aug 2026 16:42:45 +0800

I like audio analyzers. It answers questions that my ears alone cannot answer quickly. Where is that resonance? Is the low end actually mono? How loud is this over the whole track? Is a limiter catching an occasional peak, or working all the time?

What I do not like is an analyzer whose interface feels slower than the display it runs on.

On my M1 Max, Excite Audio VISION 4X appeared to top out at roughly 30 FPS, with inconsistent frame timing, while consuming about one CPU core. iZotope Insight 2 looked smoother, but in my experience it was comparatively resource-heavy and expensive. These were observations from my own setup, not controlled benchmarks that apply to every machine, host, and plugin version. Still, they were enough to make me wonder: how difficult would it be to build the analyzer I wanted?

That became Audio Insight, an open-source AUv2 and VST3 analyzer for macOS. Its first goal is deliberately narrow: show useful measurements, leave the audio unchanged, keep real-time callback work bounded, and make the interface feel native on a high-refresh-rate display.

The project is still early, but it already has a Spectrum, Spectrogram, Peak/RMS meter, stereo vectorscope and correlation meter, and BS.1770 loudness measurements. Four grid-snapped splitters resize the dashboard tiles, the analysis parameters are adjustable, and a built-in metrics panel makes the renderer’s behavior visible instead of leaving performance to intuition.

This post is about how it works, but mostly about the unexpectedly interesting work required to make a meter move smoothly.

What an audio plugin actually does

People who use plugins often picture them as little applications inside a DAW. That is a useful mental model for the interface, but not for the audio path.

An AU or VST3 plugin is code loaded by a host (or, in some hosts, a separate hosting service). The host repeatedly gives the plugin a small block of samples by calling its processing function. At 48 kHz with 512-sample blocks, a new block arrives about every 10.7 milliseconds. The plugin has to finish before the hardware needs the result. Missing that deadline can produce a click or dropout.

Audio Insight is a transparent effect: it observes supported mono or stereo audio and leaves the samples unchanged. Even so, its callback has to follow the same real-time rules as a compressor or synthesizer. It cannot allocate memory, take a lock, wait for another thread, write a log, open a file, call the UI, or ask the GPU to draw something. Any of those operations can take an unpredictable amount of time.

The resulting design looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


host audio callback
 ↓
bounded, non-blocking capture
 ↓
per-instance analysis coordinator
 ↓
shared two-worker analysis pool
 ↓
immutable measurement snapshots
 ↓
display-linked Metal renderer

The callback only captures bounded chunks into preallocated storage and updates the few measurements that must inspect every sample. A per-instance coordinator coalesces work, and all instances loaded in the same plugin module share two analysis workers. There is at most one running or queued job per instance, so opening many plugin windows does not create a thread for every visualization.

The workers publish immutable snapshots. The UI reads the newest complete snapshot whenever it draws; it never waits for analysis to finish. This separation matters. Analysis targets 60 slices per second, but the latest-wins scheduler can skip stale work rather than build a backlog. Meanwhile, a ProMotion display can render at around 120 Hz. The renderer can advance display motion between discrete analysis updates without running twice as many FFTs.

All five visualizations share one Metal canvas, drawable, command buffer, and render pass. JUCE supplies the plugin shell and cross-format plumbing, while the visual layer is native Metal. Coordinates and layout use logical points, and drawable and text resources follow the current backing scale. The implementation is therefore designed to support both regular-density and Retina displays, including live backing-scale changes.

Both paths are highly optimized. The shared transform uses juce::dsp::FFT, which selects Apple’s Accelerate/vDSP implementation on macOS, and Spectrum and Spectrogram reuse each calibrated result. On the GPU side, the Spectrogram stores calibrated dB in a circular 16-bit-float (R16Float) texture: scrolling remaps texture coordinates, while shader controls recolor retained history without another FFT or a whole-texture copy. High display cadence therefore does not multiply the default 60 Hz FFT workload.

When the editor is closed, there is nothing to display, so capture, analysis, history, display-link callbacks, and Metal submissions stop. Audio still passes through normally. Reopening the editor begins fresh rather than silently spending host resources on invisible history.

Turning samples into pictures

The analyzers share infrastructure, but each one answers a different question. Here is the calculation path in a little more detail.

Spectrum: what frequencies exist now?

The Spectrum takes a short window of recent audio and uses a fast Fourier transform (FFT) to divide it into frequency bins. By default the transform size is $N=8192$ samples, or about 171 milliseconds at a sample rate $F_s=48$ kHz. This does not delay the audio by 171 ms; the plugin passes audio through immediately. It means the displayed estimate describes roughly that much recent history.

The FFT bin centers are separated by $\Delta f=F_s/N$. With the defaults, that is approximately 5.86 Hz. This number is useful, but it is not the same as saying two tones 5.86 Hz apart can always be resolved: the selected window also determines how widely a tone spreads into nearby bins.

Before the FFT, samples are multiplied by a periodic five-term flat-top window $w[n]$. Cutting an arbitrary piece from a continuous waveform creates artificial edges, which spread energy across the spectrum. A window tapers the data to control that leakage. A flat-top window trades some ability to separate nearby tones for better amplitude accuracy, which is a useful default for a measurement tool.

For channel $c$, the transform is:

\[ \begin{aligned} X_c[k]&=\sum_{n=0}^{N-1}x_c[n]\,w[n]e^{-j2\pi kn/N},\\ f_k&=\frac{kF_s}{N}. \end{aligned} \]

Audio Insight corrects the window’s coherent gain—the amplitude scaling introduced by multiplying by $w[n]$—with $W=\sum_n w[n]$. Real-valued audio has mirrored positive- and negative-frequency FFT bins, but the graph needs only the nonnegative half. In this one-sided view, the DC bin at 0 Hz and the Nyquist bin at $F_s/2$ use $1/W$; every bin between them represents both mirrored sides and uses $2/W$. The calibrated stereo power and level are therefore:

\[ \begin{aligned} a_k&= \begin{cases} 1/W, & k=0\ \text{or}\ k=N/2,\\ 2/W, & \text{otherwise}, \end{cases}\\[3pt] P[k]&=\max_c\left(a_k|X_c[k]|\right)^2,\\ D[k]&=10\log_{10}P[k]. \end{aligned} \]

For mono, the maximum contains only one channel. For stereo, taking the larger channel magnitude avoids first mixing the waveforms to mono, where out-of-phase content could cancel. The calibration makes a bin-centered full-scale sine read 0 dB internally; powers at or below $10^{-18}$ are displayed at the $-180$ dB analysis floor.

Attack and Release then smooth each bin in linear power, not in dB. Given the elapsed time $\Delta t$ and the selected time constant $\tau_d$:

\[ \begin{aligned} \alpha_d&= \begin{cases} 0, & d\text{ is Off},\\ e^{-\Delta t/\tau_d}, & d\text{ is enabled}, \end{cases}\\[3pt] \bar P_t[k]&=\alpha_d\bar P_{t-1}[k]+(1-\alpha_d)P_t[k]. \end{aligned} \]

The direction $d$ is Attack when $P_t[k]\geq\bar P_{t-1}[k]$, otherwise Release. An Off direction follows the current FFT immediately. The default Attack is Off, allowing a short burst to appear at once, while the default 250 ms Release lets the trace fall more slowly. Peak hold, when enabled, operates on unsmoothed power instead of $\bar P$.

Transforms target a slice rate $R_s$ using a hop of $H=\max(1,\operatorname{round}(F_s/R_s))$ new samples. At 48 kHz and 60 slices per second, $H=800$, so adjacent 8,192-sample windows overlap by about 90.2%. The first result still waits for one complete window, and the latest-wins scheduler may skip stale transforms under load instead of building a backlog.

Spectrum and Spectrogram use the same continuously adjustable frequency scale. For a frequency $f$ between $f_0$ and $f_1$, the scale control $s$ blends normalized linear and logarithmic coordinates:

\[ \begin{aligned} u_{\mathrm{lin}}(f)&=\frac{f-f_0}{f_1-f_0},\\ u_{\log}(f)&=\frac{\ln(f/f_0)}{\ln(f_1/f_0)},\\ u(f,s)&=(1-s)u_{\mathrm{lin}}(f)+s\,u_{\log}(f). \end{aligned} \]

Here $f_0=20$ Hz and $f_1=\min(20\text{ kHz},F_s/2)$. The default is $s=0.8$. At $s=0$, equal distances represent equal numbers of hertz. At $s=1$, equal ratios such as 100→200 Hz and 1→2 kHz occupy equal distances. Values in between preserve more low-frequency detail without compressing the entire treble into a tiny area. Spectrum uses $x=u$, while Spectrogram uses $y=1-u$ so high frequencies appear at the top. Axis labels are chosen dynamically: important anchors win first, then extra candidates fill only the space that remains.

Spectrogram: how did the spectrum change?

A Spectrum is one slice through time. A Spectrogram keeps those slices and scrolls them sideways, using color for level. Transients become vertical marks, steady tones become horizontal lines, and harmonics become stacks of related lines.

Each Spectrogram column starts from the same raw power $P[k]$ as Spectrum, before Spectrum’s Attack/Release averaging. Let $\mathcal K$ contain only usable bin centers from 20 Hz through $f_1$, and let $R_f=\min(1024,|\mathcal K|)$ be the texture’s frequency-row count. For a usable bin at $f_k=kF_s/N$, define $q_k=u(f_k,s)$. Its row is:

\[ r(k)=\min\left(R_f-1,\left\lfloor R_f q_k\right\rfloor\right). \]

For a row containing one or more bin centers, $P_r$ is the greatest $P[k]$ assigned to that row. Taking the maximum, rather than the average, helps a narrow tonal trace survive when several FFT bins land in one display row. If a row contains no bin center—common at low frequencies with a small FFT—the mapper inverse-maps the row center and linearly interpolates the two surrounding bins in power. It is honest interpolation between available samples, not a claim of extra frequency resolution.

Power at or below $10^{-18}$ becomes $-180$ dB; otherwise the mapper stores $D_r=10\log_{10}P_r$. These values go into a circular Metal texture with one 16-bit floating-point level per cell (R16Float). The texture stores calibrated dB rather than finished colors. In the shader, let $F$ be the selected floor, $C$ the ceiling, and $\eta$ the Color response:

\[ \begin{aligned} v&=\operatorname{clamp}\left( \frac{D_r-F}{C-F},0,1\right),\\ \gamma&=2^\eta,\\ c_{\mathrm{palette}}&=v^\gamma. \end{aligned} \]

The value $c_{\mathrm{palette}}$ selects a point in the chosen palette. Response 0 is linear in dB; negative values reveal quieter detail, while positive values suppress low energy and emphasize stronger traces. Because this work happens in the shader, changing palette, range, or response recolors existing history without rerunning the FFT.

For a history duration $T$ and requested slice rate $R_s$, the texture uses $\min(8192,\lceil TR_s\rceil)$ columns. The default ten seconds at 60 slices per second therefore needs 600 columns. A write index wraps around the texture, and the renderer changes texture coordinates instead of copying the whole image to scroll it. Missing timestamp intervals become black columns rather than stretching old information across time.

Peak and RMS: how strong is the signal?

Peak and RMS intentionally describe different things.

Sample peak examines every sample. Its live value has instantaneous attack and a 20 dB/s release:

\[ \begin{aligned} \lambda_p&=10^{-20/(20F_s)},\\ p[n]&=\max\left(|x[n]|,\lambda_p p[n-1]\right). \end{aligned} \]

In other words, a new larger sample wins immediately; otherwise the old indication decays by the amount corresponding to one sample period. A separate hold marker keeps a new maximum for two seconds, then falls at the same 20 dB/s rate. The OVER indicator latches when $|x[n]|\geq1$, although the label deliberately does not claim that floating-point audio at 0 dBFS proves waveform clipping.

RMS estimates sustained signal power. With the 300 ms time constant $\tau=0.300$ s, Audio Insight updates an exponential mean square for every sample:

\[ \begin{aligned} \alpha&=e^{-1/(F_s\tau)},\\ q[n]&=\alpha q[n-1]+(1-\alpha)x[n]^2,\\ \operatorname{RMS}[n]&=\sqrt{q[n]},\\ D_{\mathrm{RMS}}[n]&=20\log_{10}\operatorname{RMS}[n]. \end{aligned} \]

This is an exponential response, not a rectangular box containing exactly the latest 300 ms. It also has no AES17 $+3.01$ dB calibration offset, so a full-scale sine reads approximately $-3.01$ dBFS RMS. Peak reveals brief extremes; RMS behaves more like a view of sustained energy. The peak remains a sample peak, not an oversampled true-peak/dBTP measurement, so it does not predict a possibly larger value between stored samples.

These ballistics run on the bounded real-time capture path and inspect every sample. Their meaning therefore does not change if an analysis worker is briefly late.

The vectorscope turns each stereo sample pair into a point:

\[ x_{\mathrm{scope}}=\frac{R-L}{2}, \qquad y_{\mathrm{scope}}=\frac{L+R}{2}. \]

Audio shared equally by both channels has $x=0$ and lies on the vertical center axis. Opposite-phase audio has $y=0$ and spreads horizontally. The coordinates remain tied to full scale rather than being normalized independently on every frame, so a quiet signal is not made to look artificially loud.

The field keeps the latest 250 ms but bounds its GPU data. For $W_f=\lceil0.25F_s\rceil$ captured frames, the worker selects one pair every:

\[ d=\left\lceil\frac{W_f}{4096}\right\rceil \]

frames. At 48 kHz, $W_f=12000$, $d=3$, and the cloud contains about 4,000 uniformly spaced points. Their opacity fades with age. This decimation changes only the picture; it does not change the correlation measurement.

The adjacent correlation value uses every sample, with 300 ms exponentially weighted averages:

\[ \begin{aligned} \alpha&=e^{-1/(F_s\cdot0.300)},\\ E_n[z]&=\alpha E_{n-1}[z]+(1-\alpha)z[n]. \end{aligned} \]\[ \rho[n]=\frac{E_n[LR]}{\sqrt{E_n[L^2]E_n[R^2]}}. \]

The three running values $E[L^2]$, $E[R^2]$, and $E[LR]$ advance in source-sample order on the real-time side, and the implementation clamps the final ratio to $[-1,1]$ against numerical error. A value near $+1$ means the channels are strongly alike, $0$ means little linear relationship, and a negative value warns that mono playback may cancel important content. If either averaged channel power is below $10^{-9}$, equivalent to $-90$ dBFS RMS, correlation is reported as unavailable rather than dividing by a nearly zero value. A genuinely mono input is labeled MONO and likewise does not receive a synthetic $+1$ correlation.

Loudness: how loud does it feel over time?

Raw peak level is not perceived loudness. Audio Insight implements BS.1770-5 K-weighting with the Momentary, Short-term, and Integrated semantics commonly used with EBU R128. K-weighting is a pair of filters: a high-frequency shelf models the head’s acoustic effect, and a high-pass stage reduces the contribution of very low frequencies. The code derives their coefficients for the current sample rate.

If $y_c[n]$ is the K-weighted output of channel $c$, Audio Insight forms the per-sample energy and a window mean:

\[ \begin{aligned} e[n]&=\sum_c y_c[n]^2,\\ z_W&=\frac{1}{N_W}\sum_{n\in W}e[n]. \end{aligned} \]

For the supported mono and stereo layouts, every actual channel has unit weight. Mono therefore contributes once; it is never duplicated into synthetic left and right channels. Surround layouts and their channel weights are outside the current scope. Window energy becomes LUFS (Loudness Units relative to Full Scale) using the BS.1770 offset:

\[ L_W=-0.691+10\log_{10}z_W. \]

Momentary loudness covers 400 ms.
Short-term loudness covers 3 seconds.
Integrated loudness uses 400 ms blocks completed every 100 ms—75% overlap—from the latest Reset within the current uninterrupted, visible analysis interval.

Momentary and Short-term are simple ungated window measurements. Integrated loudness applies gates: thresholds that exclude blocks from the long-term average. For each 400 ms block $i$, let its mean-square energy be $z_i$ and its loudness be $L_i=-0.691+10\log_{10}z_i$. The absolute-passing set is:

\[ \begin{aligned} \mathcal A&=\{i\mid L_i>-70\ \mathrm{LUFS}\},\\ \mu_{\mathcal A}&=\frac{1}{|\mathcal A|}\sum_{i\in\mathcal A}z_i. \end{aligned} \]

At each Integrated update, one non-iterative relative threshold is calculated 10 LU below the preliminary absolute-gated mean of the history accumulated so far:

\[ \begin{aligned} \Gamma_{\mathrm{rel}}&=-0.691+10\log_{10}\mu_{\mathcal A}-10,\\ \mathcal R&=\{i\in\mathcal A\mid L_i>\Gamma_{\mathrm{rel}}\}. \end{aligned} \]

Finally:

\[ \begin{aligned} \bar z_{\mathcal R}&=\frac{1}{|\mathcal R|}\sum_{i\in\mathcal R}z_i,\\ L_I&=-0.691+10\log_{10}\bar z_{\mathcal R}. \end{aligned} \]

Both comparisons are strict $>$, and the relative gate is not iterated repeatedly. This two-stage gate prevents silence and very quiet passages from dragging the program average down indefinitely. The tile’s Reset command restarts Integrated loudness while ready Momentary/Short-term values and K-weighting continuity remain intact. Editor reactivation, an audio discontinuity, or a format change resets the complete loudness analyzer.

The empty cases are explicit too. If $\mathcal A$ contains no blocks, the preliminary mean and relative gate remain unavailable. If $\mathcal R$ is empty, Integrated loudness remains $-\infty$. The implementation never divides by an empty set.

The implementation does not claim complete EBU Mode compliance: it does not yet include LRA or true peak, for example. The label describes its M/S/I measurement semantics, not a certification.

There is an interesting performance problem hiding in Integrated loudness. Within one uninterrupted visible measurement, the exact answer can cover 24 hours: up to 864,000 blocks. Rescanning every qualifying block every 100 ms would make the cost grow throughout the measurement.

The implementation uses a preallocated sorted index called a B+ tree. It contains finite block energies above the absolute gate and keeps aggregate counts and sums in its branches; all completed blocks still count toward the 24-hour limit. A new relative-gate boundary can be answered by finding one boundary leaf and combining a bounded number of branch totals. Capacity for the worst case occupies about 7.25 MiB on arm64, and the structure never allocates while processing.

Smooth is a timing property, not an FPS number

The renderer uses CAMetalDisplayLink, which supplies a drawable in step with a display. While visible, Audio Insight requests the active display’s exact reported maximum refresh rate, with a 60 Hz fallback. That request is best effort—Core Animation and the compositor still control actual presentation—so measured presentation timestamps are the truth.

This distinction became important repeatedly. A counter can say 120 callbacks per second while the screen still changes only 60 times. An average can say 120 FPS while an occasional doubled interval makes scrolling visibly hitch. Smoothness is about the complete chain from callback to presentation and about the distribution of frame intervals, not just one large number.

The plugin that crashed its host

The first AU build appeared for a moment in SoundSource and then disappeared. The host reported only that its Audio Unit hosting service had crashed.

The detailed log led to an assertion in timed drawable presentation. A normal Metal application may call an API such as timed present, but a drawable delivered by CAMetalDisplayLink has different presentation ownership. Combining the two caused the hosting process to assert. The correct sequence is to commit the command buffer and call plain present() on that drawable, while using the display link’s target timestamp only for telemetry and scheduling.

This is one reason plugin development needs testing in real hosts. SoundSource exposed an API misuse that a successful build or unit test had not.

Why 120 display callbacks produced 60 frames

After the crash was fixed, the display link was firing close to 120 times per second, but only about 60 frames were submitted. The built-in metrics captured the pattern:

Counter	Before the fix
Display-link callbacks	6,453
Metal submissions	3,230
GPU-backpressure drops	3,223
Sampled display-link callback rate	~111/s
Sampled Metal submission rate	~59.6/s

The cumulative counters cover the full telemetry epoch; the two rates are a sample from its final roughly 0.25 seconds. Almost exactly every other display-link callback was being rejected by the in-flight buffer pool.

The surprising part was that the GPU was not necessarily too slow. Reusable vertex buffers were retained until the drawable was actually presented. The compositor may hold a drawable for several refresh periods even after GPU execution has completed, so all reusable buffers became occupied and the next callback had nowhere to write.

The fix was to separate two lifetimes. GPU command completion now releases the reusable buffers immediately. A small, independent object survives only to correlate the later presentation timestamp. The renderer no longer holds large working resources hostage to compositor timing.

In a later point-in-time M1 Max capture from another development build, with the Metrics panel visible, the drawable was 2,400×1,496 pixels at 2× backing scale. The run recorded 1,188 display-link callbacks, 1,188 submissions, and zero GPU-backpressure drops. Across the most recent 240 presented intervals, the average was 8.438 ms, or 118.52 Hz; 237 intervals were the normal 8.333 ms and three doubled to 16.667 ms. Telemetry also counted 11 skipped presentations over the run. That capture used the then-selected 16,384-point FFT; today’s default is 8,192.

The capture demonstrates that the buffer-lifetime bottleneck and its GPU-backpressure drops were gone. It is evidence of approximately display-rate presentation in that run, not a perfect-pacing claim or a controlled comparison with another plugin.

Making 60 Hz data scroll on a 120 Hz display

The Spectrogram exposed a second kind of stutter. New analysis columns arrive at 60 Hz. If the image moves forward only when a complete column arrives, it necessarily steps every other frame on a 120 Hz display.

The solution was not to double the FFT workload. The renderer advances a fractional scroll head from the target presentation clock while keeping the actual dB cells discrete. A one-slice cushion absorbs ordinary analysis scheduling jitter. If a texture upload is briefly busy, the renderer postpones that upload while continuing to draw the rest of the dashboard.

The result is much smoother motion from the same 60-slices-per-second target. This also explains why raising thread priority would have been the wrong first response: the main issue was the relationship between two clocks, not a shortage of real-time privileges.

The random resets that were not random

During longer sessions, all graphs would occasionally reset. The recovery was intentional—when audio history has a real gap, temporal analyzers must not pretend the samples on either side were adjacent—but the handoff overflowed far too easily even while host audio was continuous. Sequence tracking then correctly detected the resulting loss.

The original capture queue had 16 logical slots and consumed one for each host callback. Its time capacity therefore depended on the host’s block size. A metrics capture reached all 16 ready slots, discarded 20 queued chunks to make room for newer audio, and recorded three consumer discontinuities followed by three Loudness resets.

The redesigned queue packs audio across callback boundaries into 128 slots of 256 frames, retaining 32,768 frames regardless of host callback size. That is about 683 ms at 48 kHz, 341 ms at 96 kHz, or 171 ms at 192 kHz. The capacity and overflow behavior are covered by implementation tests; longer post-redesign host runs remain part of validation. A sufficiently long stall can still overflow it. When that happens, latest data wins and temporal analyzers reset, because joining unrelated pieces of audio would produce convincing but false measurements.

Building observability into the plugin

Apple’s Metal HUD is useful for applications that enable it before creating their first Metal device. A plugin usually arrives after its host has already done that, so it cannot reliably switch the HUD on from a settings button. I replaced that idea with a built-in performance panel available in Release builds.

It reports exact frame pacing over the latest 240 presentation intervals, derived from 241 timestamps; CPU, submit, GPU, and compositor latency composition; display-link scheduling; audio-callback histograms; queue occupancy and discontinuities; analyzer freshness; and raw copyable metrics for offline inspection. The stacked latency bar covers the pipeline from a display-link callback to presentation. It is not a breakdown of an 8.33 ms frame budget: several frames can overlap in flight, so its total can exceed one refresh interval without reducing presentation cadence.

Graphs move at vblank, headline numbers refresh at no more than 10 Hz, and the full text table refreshes at 4 Hz. That keeps the visual feedback immediate without rebuilding lots of text 120 times per second. Instrumentation turned several vague reports—“it looks a bit laggy,” “it seems to reset”—into specific, actionable failures.

An agent-assisted, human-tested development loop

I used coding agents to implement much of Audio Insight. That did not remove the need for a tight feedback loop; it made the loop more important.

The agents could design the threading model, inspect crash logs, add instrumentation, and reason from raw captures. They could build the plugin, but they could not reliably judge how motion felt inside my particular SoundSource setup. At runnable milestones I installed the AU, watched it on the M1 Max, adjusted settings, and returned observations, screenshots, logs, or copied metrics. Those reports led directly to the presentation-lifetime fix, the fractional Spectrogram scroll, dynamic axis labeling, and the queue redesign.

For visual and real-time software, “the code is correct” and “the product feels right” are different claims. An instrumented implementation plus a person looking at the actual display proved far more useful than guessing at either one in isolation.

What is open source today

The current code identifies itself as Audio Insight 0.1.0. It targets macOS 15 on arm64 and builds AUv2 and VST3. It uses C++20, CMake, a pinned JUCE submodule for the plugin shell, CPU FFT analysis accelerated by Apple’s vDSP on macOS, and a native Metal renderer. Project-owned code is licensed under AGPL-3.0-or-later; JUCE retains its own upstream AGPL terms.

The current release policy is pragmatic for a small open-source project: builds use ad hoc signing, and Developer ID signing and notarization are out of scope. Users can build from source. For a downloaded bundle, the documented flow is to verify the published checksum, extract it, clear quarantine only on the intended bundle, apply an ad hoc signature, and verify that signature.

Older macOS versions, Intel/Universal builds, Windows, and AUv3 are architectural possibilities rather than current support promises. Logic compatibility, broader VST3 host coverage, multi-instance stress testing, and several formal performance gates also remain work in progress.

The source, build instructions, and current limitations are all in the Audio Insight repository. If you use analyzers but have never looked inside one, I hope the code makes the path from samples to pixels a little less mysterious. And if the Spectrogram glides across a 120 Hz display without drawing attention to the renderer, that is exactly the point.

Bundling macOS Dynamic Libraries

Mon, 08 Jun 2026 12:25:00 +0800

I recently tried to build QEMU on macOS and make the result portable enough that it could still run after uninstalling the Homebrew packages used during the build, or I can move the whole QEMU directory to another machine. I don’t want the Homebrew build because it installs too many dependencies on the system, and I want a more self-contained bundle, not a system-wide installation.

The short version: fully static linking on macOS is not really the right target. macOS binaries still dynamically link against Apple system libraries such as libSystem. But for tools like QEMU, what I really wanted was not a “pure static binary”; I wanted a self-contained directory like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


_qemu-11.0.1/
├── bin/
│ ├── qemu-img
│ ├── qemu-system-x86_64
│ └── ...
└── lib/
 ├── libglib-2.0.0.dylib
 ├── libgobject-2.0.0.dylib
 ├── libintl.8.dylib
 ├── libpcre2-8.0.dylib
 └── ...

The binaries in bin/ should load their non-system dependencies from ../lib (note that it’s relative, not absolute, so it will work even if the whole directory is moved), instead of from /opt/homebrew.

This post records the process, using QEMU as the example.

The original problem

I built QEMU roughly like this:

1
2
3
4
5
6


# You should refer to https://wiki.qemu.org/Hosts/Mac for the latest build instructions. This is just an example.
brew install libffi gettext glib pkg-config zstd # may not be the exact set of dependencies you need

./configure --prefix="$HOME/bin/_qemu-11.0.1"
make -j"$(sysctl -n hw.ncpu)"
make install

The build worked. But after uninstalling some Homebrew dependencies, running qemu-img failed:

1
2
3
4


dyld[82783]: Library not loaded: /opt/homebrew/opt/glib/lib/libglib-2.0.0.dylib
 Referenced from: /Users/charlie/bin/_qemu-11.0.1/bin/qemu-img
 Reason: tried: '/opt/homebrew/opt/glib/lib/libglib-2.0.0.dylib' (no such file)
zsh: abort qemu-img

This means the installed QEMU binary still contains an absolute dependency path:

1

/opt/homebrew/opt/glib/lib/libglib-2.0.0.dylib

We can confirm that with:

1

otool -L "$PREFIX/bin/qemu-img"

Example output:

1
2
3
4
5


qemu-img:
 /opt/homebrew/opt/glib/lib/libglib-2.0.0.dylib (compatibility version 8801.0.0, current version 8801.0.0)
 /opt/homebrew/opt/zstd/lib/libzstd.1.dylib (compatibility version 1.0.0, current version 1.5.7)
 /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1351.0.0)
 ...

The /usr/lib and /System/Library entries are fine. They are macOS system libraries. The /opt/homebrew/... entries are the ones that make the binary depend on my local Homebrew installation.

Why not just build QEMU fully static?

On Linux, the natural thought is “just build a static binary”.

On macOS, that is not usually how things work. macOS does not support the same style of fully static userland binary that Linux users often expect. You can try to statically link some third-party libraries, but the final program will still dynamically link to Apple system libraries.

So the practical goal is:

Bundle third-party .dylib dependencies next to the program, and rewrite Mach-O load commands so the binary loads those local copies.

This is similar in spirit to what many .app bundles do, but here I wanted a plain CLI directory layout.

The tools involved

macOS Mach-O binaries can be inspected and patched with these tools:

1
2
3
4


otool -L <file>
install_name_tool -change <old> <new> <file>
install_name_tool -id <new-id> <dylib>
install_name_tool -add_rpath <rpath> <file>

otool -L shows dynamic library load commands.

For example:

1

otool -L "$PREFIX/bin/qemu-img"

might show:

1
2
3
4
5


qemu-img:
 /opt/homebrew/opt/glib/lib/libglib-2.0.0.dylib (compatibility version 8801.0.0, current version 8801.0.0)
 /opt/homebrew/opt/zstd/lib/libzstd.1.dylib (compatibility version 1.0.0, current version 1.5.7)
 /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1351.0.0)
 ...

Those can be rewritten with:

1
2
3
4


install_name_tool -change \
 /opt/homebrew/opt/glib/lib/libglib-2.0.0.dylib \
 '@executable_path/../lib/libglib-2.0.0.dylib' \
 "$PREFIX/bin/qemu-img"

@executable_path means “the directory containing the executable being launched”.

So it will try to find libglib-2.0.0.dylib in ../lib/ relative to the executable, no longer looking in /opt/homebrew.

First attempt: patch direct dependencies only

My first attempt was simple:

1
2
3
4
5


otool -L "$PREFIX"/bin/* \
 | grep /opt/homebrew \
 | sort \
 | uniq \
 | awk '{print $1}'

This found direct Homebrew dependencies used by QEMU binaries, such as:

1
2
3
4
5


/opt/homebrew/opt/glib/lib/libgio-2.0.0.dylib
/opt/homebrew/opt/glib/lib/libglib-2.0.0.dylib
/opt/homebrew/opt/glib/lib/libgmodule-2.0.0.dylib
/opt/homebrew/opt/glib/lib/libgobject-2.0.0.dylib
/opt/homebrew/opt/zstd/lib/libzstd.1.dylib

Then I copied those libraries into $PREFIX/lib and patched the binaries.

This fixed some errors, but not all of them.

Running qemu-img then failed with a different error:

1
2


dyld[97126]: Library not loaded: /opt/homebrew/opt/gettext/lib/libintl.8.dylib
 Referenced from: /Users/charlie/bin/_qemu-11.0.1/lib/libglib-2.0.0.dylib

So I realized that it is not enough to patch only the binaries. The copied .dylib files have their own dependencies too.

In this case:

1
2
3


qemu-img
 -> libglib-2.0.0.dylib
 -> libintl.8.dylib

libintl.8.dylib was not directly referenced by qemu-img. It was a transitive dependency of libglib.

The correct model

The dependency graph looks like this:

1
2
3
4
5
6
7


bin/qemu-img
 -> /opt/homebrew/opt/glib/lib/libglib-2.0.0.dylib
 -> /opt/homebrew/opt/zstd/lib/libzstd.1.dylib

lib/libglib-2.0.0.dylib
 -> /opt/homebrew/opt/gettext/lib/libintl.8.dylib
 -> /opt/homebrew/opt/pcre2/lib/libpcre2-8.0.dylib

So the bundling process must be recursive:

Scan Mach-O files in bin/.
Find its /opt/homebrew dependencies.
Copy those .dylib files into lib/.
Patch the binaries to refer to the bundled copies (../lib).
Scan the copied .dylib files.
Copy and patch their dependencies too.
Repeat until no /opt/homebrew dependencies remain.

Which paths should be used?

For executables in bin/, I use:

1

@executable_path/../lib/libfoo.dylib

For dylibs inside lib/, I use:

1

@loader_path/libfoo.dylib

@executable_path is relative to the main executable being launched.
@loader_path is relative to the Mach-O file that is doing the loading. For dependencies between dylibs, this is what we want:
1 2

lib/libglib-2.0.0.dylib -> @loader_path/libintl.8.dylib

Since both files are in the same lib/ directory, this resolves correctly.

The final bundling script

I ended up writing a small Python script called macho-bundle-deps. You can find it here: https://github.com/charlie0129/dotfiles/blob/f15791054e517f6b5afc892312f1db73f331d475/bin/darwin/macho-bundle-deps. This is a permanent link to a specific commit, so you may want to check the latest version in the repository.

Usage:

1
2
3
4
5
6


PREFIX="$HOME/bin/_qemu-11.0.1"

macho-bundle-deps \
 --lib-dir "$PREFIX/lib" \
 --prefix /opt/homebrew \
 "$PREFIX"/bin

Or, from inside the QEMU prefix:

1
2
3


cd "$HOME/bin/_qemu-11.0.1"

macho-bundle-deps --lib-dir lib bin

The script does the following:

finds Mach-O files from the input paths
scans their dependencies with otool -L
copies matching dependencies into --lib-dir
patches executable dependencies to @executable_path/../lib/...
patches bundled dylib dependencies to @loader_path/...
patches copied dylib IDs with install_name_tool -id
recursively processes newly copied dylibs
reports an error if matching absolute dependency paths remain

Verifying the result

After running the bundler, I verify that no Homebrew paths remain:

1

otool -L "$PREFIX"/bin/* "$PREFIX"/lib/*.dylib | grep /opt/homebrew

Now I can uninstall the dependencies from Homebrew, and the bundled QEMU still works:

1
2


brew uninstall libffi gettext glib
qemu-img --help

Notes and limitations

This is not the same as producing a fully static binary.

The result still depends on macOS system libraries, which is normal:

1
2


/usr/lib/libSystem.B.dylib
/System/Library/Frameworks/...

It also does not magically make a binary portable across all macOS versions or CPU architectures. A binary built on Apple Silicon is still an arm64 Mach-O binary unless built otherwise.

This approach is mainly useful for making a local CLI tool directory self-contained with respect to Homebrew dependencies.

Why copying symlinks should be avoided

Homebrew often has dylib symlinks like:

1

libintl.dylib -> libintl.8.dylib

When bundling, prefer copying the symlink target, not the symlink itself.

In shell, that means:

1

cp -L source.dylib "$PREFIX/lib/"

In Python, shutil.copy2(..., follow_symlinks=True) does the same thing.

This avoids ending up with a bundled symlink pointing to a non-existent file.

Final layout

After bundling, the QEMU directory looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


_qemu-11.0.1/
├── bin/
│ ├── qemu-img
│ ├── qemu-io
│ ├── qemu-nbd
│ ├── qemu-system-aarch64
│ ├── qemu-system-x86_64
│ └── ...
└── lib/
 ├── libffi.8.dylib
 ├── libgio-2.0.0.dylib
 ├── libglib-2.0.0.dylib
 ├── libgmodule-2.0.0.dylib
 ├── libgobject-2.0.0.dylib
 ├── libintl.8.dylib
 ├── libpcre2-8.0.dylib
 └── libzstd.1.dylib

Now qemu-img no longer cares whether Homebrew’s glib, gettext, pcre2, or zstd packages are installed.

Conclusion

The main lesson is that macOS dependency bundling is graph traversal, not a one-shot patch.

Patching only the top-level binaries is not enough. You also need to patch the dylibs that you copied, and then patch the dylibs that those dylibs depend on.

The final strategy is:

1

scan -> copy -> patch -> scan copied dylibs -> repeat

For executables:

1
2


/opt/homebrew/.../libfoo.dylib
 -> @executable_path/../lib/libfoo.dylib

For bundled dylibs:

1
2


/opt/homebrew/.../libbar.dylib
 -> @loader_path/libbar.dylib

And for the dylib’s own install name:

1
2


/opt/homebrew/.../libfoo.dylib
 -> @loader_path/libfoo.dylib

Fake macOS Version Detected by Homebrew

Tue, 08 Oct 2024 22:08:00 +0800

Background

One particular issue that I encountered when I tried to install some software using Homebrew on my Mac is that Homebrew deprecates support for older macOS versions just like Apple do. Once a macOS version is deprecated, Homebrew will not provide bottles (precompiled binaries) for that version. This means that you have to compile the software from source, which is extremely time-consuming and sometimes error-prone. Imagine installing shell-check will require to build ghc from source, which takes hours, and then use ghc to build shell-check from source. This is not a good experience.

Solution

Pin homebrew/core to an older version

One way to work around this issue is to use a older version of the homebrew/core tap, such that the bottles are still available for the macOS version you are using because they are built when your macOS version is supported. The downside is that you will be using outdated software. If this is not an issue for you then congratulations. You can achieve this by running the following command:

1
2
3


$ brew tap homebrew/core
$ cd $(brew --repo homebrew/core)
$ git reset --hard <commit-hash>

Make sure you disable the auto-update of Homebrew so that it does not update the homebrew/core tap to the latest version. You can do this by running the following command:

1

$ echo 'export HOMEBREW_NO_AUTO_UPDATE=1' >> ~/.zshrc

Fake macOS version

Another way is to fake the macOS version that Homebrew detects. This way, Homebrew will provide bottles for the macOS version you are faking. Most software will work and you will be using the latest software. However, this may not work for all software as some software may have dependencies that are not available for the macOS version you are faking. You can achieve this by running the following command:

1
2


$ export HOMEBREW_FAKE_MACOS=13.0 # Choose a macOS version that is supported by Homebrew and close to your macOS version
$ brew install xxx

Explanation

Homebrew actually has an private undocumented API that allows you to fake the macOS version. https://github.com/Homebrew/brew/blob/a3d8f4e0e4a22da9990d59cca70bec1e7be726cf/Library/Homebrew/os/mac.rb#L41

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# This can be compared to numerics, strings, or symbols
# using the standard Ruby Comparable methods.
#
# @api internal
sig { returns(MacOSVersion) }
def self.full_version
 @full_version ||= if (fake_macos = ENV.fetch("HOMEBREW_FAKE_MACOS", nil)) # for Portable Ruby building
 MacOSVersion.new(fake_macos)
 else
 MacOSVersion.new(VERSION)
 end
end

Example

I have macOS Monterey (12.0) running, which is just deprecated by Homebrew. I want to install batt which is not available as a bottle for macOS Monterey.

If I run brew install batt, I will get the following error:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


$ brew install batt
Warning: You are using macOS 12.
We (and Apple) do not provide support for this old version.
It is expected behaviour that some formulae will fail to build in this old version.
It is expected behaviour that Homebrew will be buggy and slow.
Do not create any issues about this on Homebrew's GitHub repositories.
Do not create any issues even if you think this message is unrelated.
Any opened issues will be immediately closed without response.
Do not ask for help from Homebrew or its maintainers on social media.
You may ask for help in Homebrew's discussions but are unlikely to receive a response.
Try to figure out the problem yourself and submit a fix as a pull request.
We will review it but may or may not accept it.

It’s Oct 8, 2024 and the latest macOS version is macOS Sequoia (15.0). So the last 3 supported macOS versions are:

macOS Sequoia (15.0)
macOS Sonoma (14.0)
macOS Ventura (13.0)

You can confirm that by checking out batt’s formula:

1
2
3
4
5
6


$ brew edit batt
...
sha256 cellar: :any_skip_relocation, arm64_sequoia: "61bd7790a82f2269b9a0ce1585c57564d03be4e4ac89b8f0d8843c0073a688e6"
sha256 cellar: :any_skip_relocation, arm64_sonoma: "198bd7bb9a808f0a9e4cb1a31b7e9c2a72d690ba1d07ebddf78b6d0ce0b6dd03"
sha256 cellar: :any_skip_relocation, arm64_ventura: "6eff598159b263327b8b562ab32f5e5e7157c20f25cbecfa08b48eda794c4c43"
...

Showing only the bottles for macOS Sequoia (15.0), macOS Sonoma (14.0), and macOS Ventura (13.0) are available.

Sadly my macOS version (Monterey 12.0) is not in the list, but macOS Ventura (13.0) is the closest to macOS Monterey (12.0). So I can fake the macOS version to macOS Ventura (13.0) by running the following command:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


$ export HOMEBREW_FAKE_MACOS=13.0
$ brew config
...
macOS: 13.0-arm64 # YES! I'm now faking macOS Ventura (13.0)
...
$ brew install batt
==> Downloading https://ghcr.io/v2/homebrew/core/batt/manifests/0.3.1
Already downloaded: /Users/charlie/Library/Caches/Homebrew/downloads/86da7d77f0bacb44475e0280eef162148e3b51df8ea44ff9bc16a5a7bba6d39f--batt-0.3.1.bottle_manifest.json
==> Fetching batt
==> Downloading https://ghcr.io/v2/homebrew/core/batt/blobs/sha256:6eff598159b263327b8b562ab32f5e5e7157c20f25cbecfa08b48eda794c4c43
Already downloaded: /Users/charlie/Library/Caches/Homebrew/downloads/24fc002de2ee11096a544dd84ff1033262a5cb627c2b824c915a552bb6a588dd--batt--0.3.1.arm64_ventura.bottle.tar.gz

As you can see, Homebrew is downloading the bottle for macOS Ventura (13.0) successfully! (Of course, the log is showing that I have already downloaded earlier, but you get the idea.)

batt itself does not rely on any APIs that are not available in my current macOS version, so it works perfectly fine.

macOS Nix First Taste

Thu, 27 Jun 2024 15:13:00 +0800

Note

Note that this blog currently acts as a reference for me. It is not a comprehensive guide on why and how to use Nix on macOS.

I chose nix because I am tired of Homebrew’s slowness and NOT PROVIDING BOTTLES (BINARY) FOR OLD MACOS VERSIONS.

Install

I am not using the official installer because it cannot survive macOS updates. Instead, I am using the Determinate System’s Nix Installer.

1
2
3
4
5
6
7


ARCH=$(uname -m | sed 's/arm64/aarch64/')
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
curl -L -o nix-installer https://github.com/DeterminateSystems/nix-installer/releases/latest/download/nix-installer-$ARCH-$OS
chmod +x nix-installer
# Optionally, move nix-installer to your PATH
# sudo install nix-installer /usr/local/bin
./nix-installer install --explain

Pin Nixpkgs

I don’t want to download a tarball and extract it every now and then. I know you can set tarball-ttl to a higher value, but I don’t want to do that either. Just pin nixpkgs.

1

nix registry pin nixpkgs

If you are like me in China, you may want to use a mirror.

1

echo "substituters = https://mirrors.sjtug.sjtu.edu.cn/nix-channels/store/ https://cache.nixos.org/" | sudo tee -a /etc/nix/nix.conf

Using

I wrote some scripts just to make my life easier.

Later Steps

There is nix-darwin to make declarative configuration easier. I don’t have time to try it yet but I will definitely give it a try when I have time.