DEV Community: Bryan Hamilton

The Equalizer That Actually Listens: A Web Audio Analyser Deep-Dive

Bryan Hamilton — Sat, 17 Oct 2026 15:22:33 +0000

An equalizer that doesn't listen to the music is just a screensaver with good branding.

If the bars are animating on a timer and the music isn't driving them, your users can tell. They may never say it out loud, but they feel it - the same way they feel a fake progress bar. Sound-reactive visuals are one of the rare places on the web where honesty is literally measurable: the waveform either agrees with the audio or it doesn't.

This is the deep-dive on how I built a real one. Not CSS bars with a random keyframe animation - an actual AnalyserNode reading the frequency spectrum of a playing track and painting eight bars on a canvas, every frame, in sync with the sound. It runs on the hover-preview cards of The DJ Calendar, an electronic music event discovery platform I build and run. When you hover a DJ card, a 30-second preview starts playing and the equalizer on the card starts dancing to it. Zero dependencies. All vanilla JS.

Here's everything I learned building it, including the two failure modes nobody warns you about.

The pipeline in sixty seconds

Web Audio gives you the whole chain for free, built into every browser:

You take an audio element - in my case playing a preview stream from the iTunes Search API - and you wrap it in a MediaElementAudioSourceNode.
You pipe that through an AnalyserNode, which keeps a running Fourier transform of whatever is playing.
You pipe the analyser to the destination so the sound keeps playing.
Every animation frame, you call getByteFrequencyData and get back an array describing how much energy is in each frequency band, from 0 to 255.

That last array is the entire magic trick. Everything else is drawing.

Two details in that chain will bite you if nobody tells you, so let me tell you now. First: createMediaElementSource can only ever be called once per audio element. Call it twice and you get an exception, so keep your wiring in one place. Second, and worse: if the audio source is cross-origin and the server doesn't send CORS headers, the analyser doesn't error. It returns all zeros. The music plays fine, the animation runs, and the bars just... sit there, dead flat, forever. I lost real time to this in the demo build before adding a diagnostic that detects the taint. An analyser that fails silently is the cruelest kind of bug, because every part of your pipeline looks like it works.

Why fftSize 64 is the right amount of wrong

The default fftSize is 2048, which gives you 1024 frequency bins. That sounds impressive and is mostly useless for a visualizer: you would be drawing bars for frequency detail the human eye cannot parse at animation speed, at a per-frame cost you pay for nothing.

I use fftSize 64. That is 32 bins. And it turns out that for a music visualizer, 32 is not a compromise - it is close to the correct answer, because most of the perceptual energy in a dance track lives in the bottom of the spectrum. Kick drums, basslines, the sub region: that is what makes an electronic track feel alive, and it all sits in the low bins.

With 32 bins I need 8 bars, and I could just average the bins into 8 groups. Instead I sample with a stride of 2 - bin 0, bin 2, bin 4 and so on. The reason is character. Averaging smooths away the differences between neighboring bands, and those differences are exactly what makes a visualizer look like music instead of a metronome. Stride sampling keeps each bar pointing at a specific, stable frequency region, so when the kick hits, the left bars spike and the recovery ripples rightward. The image reads as a wave moving through the spectrum, because it is one.

Smoothing is the difference between data and a strobe light

Raw FFT frames flicker. Music has sharp transients - a hi-hat is a spike that exists for a few milliseconds - and if you paint raw frames your equalizer turns into a strobe that triggers anyone with photosensitivity issues and looks broken for everyone else.

The AnalyserNode has a smoothingTimeConstant property, and I set it to 0.8. That is a heavily damped value: each frame, the analyser blends the new spectrum with the old one at 80/20, so the bars rise fast enough to feel percussive and fall slowly enough to feel like they have mass. Go lower and the bars twitch; go higher and they miss the beat entirely. 0.8 sits in the pocket for dance music specifically, where transients are big and regular.

If you only steal one number from this article, steal that one. It is doing more visible work than anything else in the system.

Drawing eight bars that belong to the card

The visual style has one hard rule: the equalizer is part of the card, not an overlay floating on it. On the production cards it is a full-width strip anchored flush to the bottom edge - eight bars at 31.5 pixels with 4-pixel gaps, which comes out to exactly 280 pixels on a 280-pixel card, 80 pixels tall, with a cyan gradient fading to transparent toward the bottom of each bar.

That flush-to-the-edge geometry is a small thing that reads as a big thing. A floating EQ looks like a widget was pasted on top of a photo. An EQ that runs edge to edge and dies exactly at the card border looks manufactured - like the card was designed around it. Same code, different margins, completely different perceived quality.

The canvas is cleared and redrawn every frame with the bar heights scaled from the byte data. Eight fillRect calls per frame is nothing; the entire render loop would run comfortably on hardware from a decade ago. Performance was never the hard part of this feature. Correctness was.

The race condition nobody warns you about

Here is the bug that ate my afternoon. The cards are hover-activated. A user dragging a cursor across a row of ten DJ cards fires ten hover events in about a second. Each one wants to: start a preview, wire a new analyser, and start a requestAnimationFrame loop.

The problem: those operations do not complete in order. Audio loading is async. So hover event for card B can arrive while card A's animation loop is still running, and now you have two loops, two audio sources, and one canvas being painted by both. The visual result is bars flickering between two different songs' spectra, and it looks exactly like the broken-random-bars antipattern this whole feature exists to avoid.

The fix is a generation counter. Every time a new preview starts, I increment a global generation id and capture it in the closure of the new animation loop. Every frame, the loop checks whether its generation is still current; if it is not, the loop exits without drawing and without rescheduling. One line of state, and stale loops kill themselves politely. No cancellations to manage, no listeners to track, no way to leak.

If you build any hover-activated media feature, build the generation counter on day one. Do it after the bug and you will spend an afternoon watching two ghosts fight over one canvas.

The autoplay gate, and why I stopped fighting it

Browsers will not start an AudioContext without a user gesture. That is not a bug, it is policy, and it is non-negotiable. My first instinct - and the first instinct of everyone who builds this - was to treat it as an obstacle and try to route around it.

The better move is to design for it. On The DJ Calendar, the first hover on a card arms the system: it preloads the audio and warms up the context, and the card shows its "you are about to hear this" state. The first click anywhere on the page unlocks audio for the whole session, permanently. From the user's point of view nothing was ever blocked - hover previews just start working after the first interaction, which is the exact moment they have expressed interest anyway.

I learned this one the hard way in May, rebuilding this exact feature, before I internalized that the browser is not asking permission. It is telling you the user has not asked yet.

Touch and reduced motion get real states, not broken ones

Two accessibility rules that shape the whole interaction model:

On touch devices there is no hover. hover: none media queries detect this, and the interaction becomes click-to-toggle: tap the card, preview plays, EQ dances; tap again, it stops. Same system, different trigger, and nobody on a phone ever sees a dead hover state.

For prefers-reduced-motion, the equalizer does not animate at all - it renders a static, honest state instead of dancing. A user who has told their OS they get motion sick has not asked for an animated frequency display, and the respectful fallback costs about ten lines.

And because the previews are real playing media, the card registers mediaSession metadata, so the track name shows up correctly in OS-level audio UI, and the page title swaps to the playing track. Small details. They are also the details that make a feature feel shipped rather than demoed.

Why zero dependencies matters here

None of this needed a library. The Web Audio API, canvas 2D context, and requestAnimationFrame are all in the platform, and the whole visualizer is a few hundred lines of readable JavaScript. For code that runs on every keystroke-equivalent event - here, every audio frame - being able to read the entire pipeline in one sitting is not sentimentality. It is how you catch the silent CORS failure, the double-wired source node, the stale animation loop. Dependencies do not just add bytes; they add distance between you and the failure.

The Search Engine With Zero Server Calls

Bryan Hamilton — Fri, 16 Oct 2026 15:19:28 +0000

Every search box you've ever shipped came with the same tax: a search endpoint, a spinner, a payload, and - if you took the SaaS route - a service that bills monthly to index what is usually a few hundred names the page could have shipped with in the first place.

I run The DJ Calendar, a site of roughly 1,000 pages covering DJs, venues and shows. Its site search has never had a server. No endpoint, no spinner waiting on a round-trip, no monthly bill. It's a JSON index rendered into the page at deploy time and a small scoring function that runs in the browser on every keystroke.

I've now extracted that whole pattern into a standalone, MIT-licensed repo: instant-search-index. Zero dependencies. One JS file. This post is how it works and, because that's where the real lessons live, what broke along the way.

The opinion underneath it

Most search boxes are infrastructure cosplay. A request to a search endpoint, a spinner, a payload - for a catalog of a few hundred records.

My stance: if the catalog fits in the page, the search belongs in the page. Ship the index as JSON, score it in the browser on every keystroke, and the search feels instant because it is instant. There is no network left to wait on.

There's a second property I care about even more than speed: the index is generated, not queried. It's built at deploy time by the same PHP that renders the artist pages, so the search index and the page content come from the same data. A search index that drifts from the pages it links to is worse than no search at all - this one can't drift, because it's rendered from the source, not synced to it.

The index contract

One JSON array per page. Three searchable fields, two display-only ones:

{
  "title": "Carl Cox",
  "subtitle": "Techno / House",
  "keywords": "techno house icon ibiza space",
  "badge": "Artist",
  "url": "/artists/carl-cox"
}

title - the primary match surface, weighted heaviest
subtitle - displayed right-aligned, lightly searchable
keywords - the synonym field: genre names, city names, whatever users type that isn't literally in the title
badge and url - display only; url is where Enter navigates

The keywords field is the quiet hero. Users type "edm", the record says "Tiësto". The keyword field is where you encode everything a human might type that the title will never contain - and it's also where accent folding happens, because folding happens once at index-build time, in PHP, and the client stays ASCII-simple forever. That's why "tiesto" finds Tiësto and "kolsch" finds Kölsch without a single line of Unicode normalization in the browser.

Scoring: AND semantics, weighted by where the match lands

Every keystroke scores every record. A record must match every query token somewhere, or it drops out - AND semantics, not OR. Type "house mafia" and you get Swedish House Mafia and nothing else.

Where a match lands decides the rank:

Signal	Weight	Example
Title token, exact	60	"cox" hits Carl Cox
Title token, prefix	40	"ame" hits Amelie Lens
Keyword, exact	30	"techno" hits the genre field
Keyword, prefix	18	"tech" hits "techno"
Subtitle, exact / prefix	12 / 8	useful, not the point
Loose substring	4	the safety net
Full-phrase hit	+25	"black coffee" beats token soup

The core of the scorer:

var W = { titleExact: 60, titlePrefix: 40, keywordExact: 30,
          keywordPrefix: 18, subtitleExact: 12, subtitlePrefix: 8,
          substring: 4, phraseBonus: 25 };

function scoreEntry(entry, queryTokens, rawQuery) {
  var total = 0;
  for (var i = 0; i < queryTokens.length; i++) {
    var best = bestFieldScore(entry, queryTokens[i]);
    if (!best) { return 0; }        /* one miss kills the record */
    total += best;
  }
  if (entry.haystack.indexOf(rawQuery) !== -1) { total += W.phraseBonus; }
  /* Shorter titles win ties */
  return total * 1000 - entry.record.title.length;
}

That last line is my favorite trick in the file. Two sort priorities - score, then shorter title - get packed into a single integer: multiply the score by 1000, subtract the title length. No comparator object, no tie-break loop, no second pass. It's arithmetic doing the work of a sort policy.

Ties after that fall to index order, which keeps results stable while you type - the list doesn't reshuffle under your fingers mid-word, and mid-word stability matters more than people think. Type "ame" and watch the list: if entries jump around per keystroke, users stop trusting it.

Tokens are precomputed once at load - per-record token arrays for title, subtitle and keywords - so a keystroke scores prepared arrays and never re-splits a string. On the demo's 99 records that's microseconds per keystroke. You'd need six figures of records before this design complains.

The combobox: keyboard is first-class, not an afterthought

The input is a real ARIA combobox, wired properly:

input.setAttribute("role", "combobox");
input.setAttribute("aria-expanded", "false");
input.setAttribute("aria-controls", listId);
input.setAttribute("aria-autocomplete", "list");

Results live in a role="listbox"; arrow keys move an aria-activedescendant pointer; Enter goes to the active option - and here's the detail I'm proudest of: if a query produces exactly one result, Enter goes straight there. No need to arrow down to the only item on screen. The keyboard path is as short as the mouse path.

Two more details that took iteration:

Escape everything before rendering. Matched text gets wrapped in a mark tag, but the title is escaped first - index entries are data, not markup. If an artist were ever named like a script tag, the search box would display it, not run it.

The debounce is 80ms, not the tutorial's 300. Debounce in most search boxes exists to protect a server you're about to annoy. There's no server here. The 80ms is only there to batch keystrokes into one render; the scoring itself is cheap enough to run on every input event.

What broke

The dropdown that vanished. The search widget was perfect in isolation and invisible in production: the results list rendered inside hero containers with overflow: hidden, which quietly amputated everything below the fold of the header. The fix was overflow: visible on every hero and header parent - and a rule I've repeated since: the search box is rarely where the bug is. The page around the search box is the bug farm.

The AND decision I almost reversed. The instinct is to fall back to OR matching when AND finds nothing: "you searched for X, maybe you meant these loosely related things." I left it out. AND plus an honest "No matches." beats OR plus a wall of tangential results, because the top of the list is the product - a confident zero communicates more than a desperate eight.

The payload, stated honestly. The index ships inside the page, which means the page carries it. Hundreds of records is trivially fine - this is a few kilobytes of JSON. But this pattern has a boundary, and the boundary is not where you'd panic: it's when your catalog stops being "names a human can scan" and starts being "a dataset". At tens of thousands of records, close the laptop and use a real engine. Most sites - including most sites that paid for one - are nowhere near that line.

Extracting it

The repo ships the engine, the CSS, and a demo where you can search the real DJ Mag Top 100 the way the production site does - including a "Show how each result scored" toggle that exposes the actual math behind each ranking. No stand-ins; the demo runs the same engine, the same weights, the same defaults as production.

Usage is one line, either declarative (the index travels in the attribute, the widget builds itself):

<input type="text" data-instant-search='[
  {"title": "Carl Cox", "subtitle": "Techno", "keywords": "techno house icon", "url": "/artists/carl-cox"}
]'>

or programmatic, for records that arrive at runtime:

InstantSearch.attach(inputEl, records, { maxResults: 6 });

The numbers

0 dependencies, 0 server round-trips, 1 JS file
~60 lines of scoring core (320 with comments and the combobox)
Microsecond scoring on hundreds of records, per keystroke
ARIA combobox semantics, full keyboard navigation, escaped output
Running in production across ~1,000 pages since 2015

The pattern is instant-search-index on GitHub, with a live demo - type something, then put the mouse away and use the arrow keys.

I Built My Portfolio Like a Piece of Rack Gear - Zero Dependencies, All Vanilla JS

Bryan Hamilton — Thu, 15 Oct 2026 15:30:00 +0000

After 29 years of building software - most of it in PHP, all of it allergic to dependencies - I decided my portfolio should behave less like a resume and more like the gear I love: a production console. Rack units. LEDs that flicker on. A VU meter that actually moves.

The result is bryanhamilton.info, and its last PageSpeed run looked like this: 99 Performance, 100 Accessibility, 100 Best Practices, 100 SEO, 104 KB transferred, 8 requests, 558 ms to load - measured in the browser, not in a lab.

No framework. No build step. No npm. Here's how each piece works, and - because that's where the real lessons live - what broke along the way.

1. The rack: HTML that tells the truth

Each project is a "rack unit" card with three things most portfolios hide: a status LED, an honest status word, and zero marketing.

<article class="rack-card">
  <span class="rack-led"></span>
  <span class="rack-status">RUNS LIVE</span>
  <h3><a href="https://github.com/...">dj-card-preview</a></h3>
  ...
</article>

The LED color is contract law:

Green (RUNS LIVE): there is a URL you can click right now and it works.
Orange (DOCUMENTED): the code is real and CI-tested, but the live instance is retired.

When a tool's live deployment broke, I didn't take the card down or leave a green LED glowing next to a dead link. I flipped the LED to orange. A portfolio that lies to you once is a portfolio you stop trusting.

2. LEDs that power on like real gear

Real rack equipment doesn't fade in politely when it loads. It boots. So when the rack scrolls into view, the LEDs flicker alive left-to-right, one time, then settle into a slow pulse:

@keyframes rack-boot {
  0%   { opacity: .08; filter: brightness(.4); }
  38%  { opacity: 1;   filter: brightness(2.6); }
  55%  { opacity: .35; filter: brightness(.8); }
  100% { opacity: 1;   filter: brightness(1); }
}

@media (prefers-reduced-motion: no-preference) {
  .rack-boot .rack-card .rack-led {
    animation: rack-boot .9s calc(var(--i, 0) * 70ms) both,
               rack-pulse 2.2s calc(var(--i, 0) * 70ms + .9s) infinite;
  }
}

One IntersectionObserver adds a rack-boot class the first time the rack enters the viewport, sets a --i index on each card, and the stagger is just arithmetic in calc(). The handoff from boot animation to infinite pulse is scheduled by delay, not JS, so there's no race condition to manage.

The part I care about most is the @media (prefers-reduced-motion: no-preference) wrapper. Every animation on the site - this one, the terminal intro, the background drift - is gated the same way. Accessibility isn't a checklist item at the end; it's the container everything else lives inside.

3. A scroll progress bar disguised as a Venn diagram

The page background is a fixed Venn diagram: one circle for engineering, one for the people-facing work. The overlap used to just sit there. Now it fills.

.venn-core {
  position: absolute;
  width: calc(min(97vw, 1040px) * 0.30);
  background: radial-gradient(closest-side,
    rgba(0, 210, 255, .17),
    rgba(0, 210, 255, .05) 58%, transparent 72%);
  opacity: var(--vp, 0);
}

var max = document.documentElement.scrollHeight - window.innerHeight;
var p = Math.min(1, Math.max(0, window.scrollY / max));
venn.style.setProperty('--vp', p.toFixed(3));

Eleven lines of JS inside a requestAnimationFrame-throttled, passive scroll listener. As you descend the page, the intersection of the two circles glows brighter until, at the footer, the overlap is fully lit. The site's entire thesis - the engineer who can also talk to humans - is rendered as an opacity value.

That's the trick I'd hand to anyone building a personal site: if your brand has a central metaphor, make the mechanics of the page narrate it. Nobody consciously notices a scroll progress bar inside a Venn diagram. Everybody feels it.

4. The equalizer that actually listens

The signature piece is an 8-bar equalizer that reacts to real audio - not a CSS keyframe fake. When you hover a demo card, it plays a 30-second track preview through the Web Audio API and drives eight canvas bars from the analyser:

const ctx = new AudioContext();
const src = ctx.createMediaElementSource(audio);
const analyser = ctx.createAnalyser();
analyser.fftSize = 64;
analyser.smoothingTimeConstant = 0.8;
src.connect(analyser);
analyser.connect(ctx.destination);

// 8 bars, sampling every other bin of the low half
function draw() {
  analyser.getByteFrequencyData(dataArray);
  for (let i = 0; i < 8; i++) {
    const v = dataArray[i * 2] / 255;
    bars[i].style.height = Math.max(4, v * 80) + 'px';
  }
  requestAnimationFrame(draw);
}

Two lessons worth the tuition:

Autoplay policy is a feature, not a bug. Browsers won't let you play audio until the user interacts. The demo shows a one-time "click anywhere to activate" gate. Fighting this is a losing game; designing around it is a UX opportunity.
A CSS "fake" EQ is detectable in about half a second. If the bars don't move with the kick drum, people feel the lie immediately. fftSize: 64 with smoothingTimeConstant: 0.8 gives you chunky, musical bars instead of noise.

5. The search index I'm proudest of

The site has instant search with keyboard navigation and ARIA combobox semantics, built on a prebuilt JSON index and a tiny client-side scoring function. No server round-trips, no search service. At build time the content gets flattened into one JSON file; at runtime, ~60 lines of JS score and match against it.

I extracted the whole pattern into a standalone repo (instant-search-index) because it's the most reusable thing I've built in years: prebuilt index + scored matching + proper combobox ARIA roles, and it works in anything.

6. What broke (and what it taught me)

No tutorial-style post is honest without the blood.

The 16 KB wall. My host's FTP silently truncates uploads at exactly 16,384 bytes. My resume-builder PHP file is 24,084 bytes. The deploy "succeeded" and produced a corrupt PDF. Diagnosis took byte-counting and MD5 comparisons; the fix was a chunked-upload kit (split the file, base64 the parts, assemble server-side, verify MD5 before writing). The real lesson: when a deploy fails weirdly, compare bytes, not screenshots.

The cache header that ate my deploys. I shipped cache-control: max-age=2592000, immutable on my HTML. That header is meant for fingerprinted assets like app.abc123.js - not for a homepage I edit daily. Result: my browser happily served me a week-old page while I debugged code that was already live. I only proved the code worked by loading the site in headless Chrome, which had no cache. The fix is one .htaccess block:

<FilesMatch "\.html$">
  Header set Cache-Control "public, max-age=0, must-revalidate"
</FilesMatch>

If you take one operational lesson from this post: immutable is for hashed assets. HTML gets max-age=0, must-revalidate. Write that on a sticky note before it costs you an afternoon.

The half-leading PDF. My PDF generator advanced the Y cursor by 48% of the line height, stacking lines on top of each other. I didn't see it for weeks because a separate bug (a missing %PDF-1.4 header) made the file unopenable, masking the layout bug underneath. Fix one bug, meet its friends.

7. Why zero dependencies, seriously

I've been doing this since before frameworks were the default, so take this with the appropriate salt. But the math on this site:

104 KB total. The median framework starter ships more than that before it renders anything.
8 requests. No font carousel, no analytics tag parade.
99-100 across every Lighthouse category - including the one most portfolios fail on purpose: Accessibility, because animations respect reduced-motion and the search is a real ARIA combobox.

Zero-dependency isn't nostalgia. It's a debugging philosophy: when everything in the stack is code you wrote, nothing is someone else's mystery. When the PDF breaks, I can read every line that produced it.

Come kick the tires

The site is live at bryanhamilton.info - scroll slowly, let the rack boot, watch the overlap glow as you reach the bottom. The code is on GitHub, ten repos deep, each one CI-badged and extracted from production code rather than written for show.

And if you build something with any of these patterns - the LED boot, the analyser EQ, the instant search - tell me in the comments. I want to see the racks other people bolt together.

How I Took ~1,000 Pages From Hundreds of Rich Results Warnings to Zero

Bryan Hamilton — Tue, 13 Oct 2026 09:28:49 +0000

The DJ Calendar has about 1,000 pages of structured data: artist pages, tour dates, venues and FAQs. For a while, Google flagged hundreds of Rich Results warnings across them. Today the count is zero, and a single 178-line PHP file keeps it there.

This post covers the bug behind almost all of those warnings, why it's so easy to ship without noticing, and the small auditor I built to catch it, including a CI job that proves the auditor still works.

The bug that looks perfectly fine

JSON-LD lets one node point at another by @id instead of repeating it. An event can say "my venue is #venue" and "my performer is #group", and those nodes are defined once elsewhere in the @graph.

The failure is simple: the event points at a node that was never actually put on the page.

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "MusicEvent",
      "@id": "https://example.com/event/2#event",
      "name": "Nova Kade at The Fillmore",
      "startDate": "2026-11-21T21:00",
      "location": { "@id": "https://example.com/venue/ghost#venue" }
    }
  ]
}

The JSON is valid. The page renders normally. A person reading it sees a venue in the HTML. But in the graph Google reads, #venue points at nothing, so the event has no location, and it isn't eligible for event rich results.

On a site generated from templates, this happens quietly: a partial that renders the venue node gets skipped for one kind of page, or a refactor renames an @id on one side but not the other. Nothing errors. Traffic just doesn't show up.

Why the Rich Results Test wasn't enough

Google's Rich Results Test is the right tool for one page. It will tell you a property is missing or that a reference goes nowhere. But it had three problems at my scale:

It's one page at a time. I had about 1,000 pages built from a handful of templates. Pasting URLs in one by one doesn't tell you which template is the root cause.
It shows the symptom, not the source. A warning on an event page doesn't say which partial failed to emit the venue node.
Nothing stops it coming back. Fix it today, and next month's refactor can reintroduce it. I'd only find out when the warnings reappeared, weeks later.

I didn't need a better validator. I needed something I could point at a whole folder of rendered pages, that would fail loudly, and that could run on every push.

Three checks in one pass

jsonld-schema-audit is one PHP file with no dependencies. It pulls every <script type="application/ld+json"> block out of each HTML file and runs three checks.

1. Required properties. Each type has properties it can't do without. The list lives in one constant, so adding a type is a one-line change:

const KNOWN_TYPES = [
    'MusicEvent'     => ['name', 'startDate', 'location', 'performer'],
    'MusicGroup'     => ['name'],
    'Place'          => ['name'],
    'Organization'   => ['name', 'url'],
    'WebPage'        => ['name'],
    'FAQPage'        => ['mainEntity'],
    'BreadcrumbList' => ['itemListElement'],
    'Person'         => ['name'],
];

A property counts as missing if it's absent, an empty string or an empty array.

2. @id resolution. Every internal #fragment reference has to point at a node that is defined in the same graph. More on this below, because it's the interesting part.

3. Parse errors. A JSON-LD block with a trailing comma is invisible to Google, and most tools skip it silently. Here, a block that json_decode can't read becomes an error instead:

$decoded = json_decode(trim($raw), true);
if (!is_array($decoded)) {
    $blocks[] = [['__parse_error__' => 'unparsable JSON-LD block']];
    continue;
}

The exit code ties it together: 0 when clean, 1 when there are errors, 2 for bad usage. That single number is what lets it guard a pipeline.

Why the @id check needs two passes

A reference can appear before the node it points to. An event near the top of the graph can point at a venue defined at the bottom. Check references top to bottom in one pass, and every forward reference looks broken.

So the auditor walks the graph twice. Pass one only builds an index of what's defined:

// First pass: index every node carrying an @id (these are definitions).
foreach ($nodes as $node) {
    if (is_array($node) && isset($node['@id']) && is_string($node['@id'])) {
        $nodesById[$node['@id']] = true;
    }
}

Pass two looks at every value nested inside each node. Anything shaped like an internal reference (an optional URL, then # and a fragment) has to exist in that index:

$copy = $node;
unset($copy['@id']);   // a node's own @id is a definition, not a reference
array_walk_recursive($copy, function ($value, $key) use (&$errors, $nodesById, $typeLabel) {
    if (!is_string($value) || $key === '@context') { return; }
    if (preg_match('/^(?:https?:\/\/[^\s#]+)?#[A-Za-z0-9_-]+$/', $value)
        && !isset($nodesById[$value])) {
        $errors[] = '[' . $typeLabel . '] property "' . $key
            . '" references unresolved @id "' . $value . '"';
    }
});

Two details matter here:

The unset before the walk. Without it, every node's own @id would be checked as if it were a reference to itself. That's a definition, not a pointer.
"Defined", not "mentioned". A URL appearing somewhere in the graph doesn't count. The target has to be a node that actually carries that @id. That's exactly the distinction Google makes, and the one my templates kept getting wrong.

Run against the broken example from earlier, the output points straight at the cause:

$ php audit.php tests/fixtures/broken.html
=== SCHEMA AUDIT: 2 error(s) across 1 block(s) ===

tests/fixtures/broken.html  [JSON-LD block 1]
  [MusicEvent] missing required property "performer" on https://example.com/event/2#event
  [MusicEvent] property "@id" references unresolved @id "https://example.com/venue/ghost#venue"

(The reported property is @id because array_walk_recursive reports the innermost key, the @id inside location.)

A CI job that proves the tool still catches the bug

Most test suites only prove the happy path. For a checker, that's the wrong half. A checker that passes everything also passes your good fixture.

So the repo's GitHub Actions workflow tests both directions: the good fixture must pass, and the broken fixture must fail.

name: Schema Audit CI
on: [push, pull_request]
jobs:
  self-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2'
      - name: Good fixture must pass
        run: php audit.php tests/fixtures/good.html
      - name: Broken fixture must fail
        run: |
          if php audit.php tests/fixtures/broken.html; then
            echo "ERROR: broken fixture passed audit"; exit 1
          else
            echo "OK: broken fixture correctly rejected"
          fi

The second step inverts the exit code. If a future change makes the auditor too lenient, the broken fixture sneaks through, and CI goes red. The tool can't silently stop catching the exact bug it was written for.

Using it on your own site

It needs PHP 7.4 or newer and nothing else: no extensions, no Composer. Drop audit.php anywhere and point it at rendered HTML:

php audit.php path/to/html/            # audit a directory (*.html, *.php)
php audit.php page.html                # audit one file
php audit.php ./ --report=out.txt      # write errors to a file

Clean pages stay quiet:

$ php audit.php tests/fixtures/good.html
=== SCHEMA AUDIT: clean. 0 errors across 1 file(s). ===

To guard your own site, render your pages to a folder during the build and add one step to your pipeline: php audit.php build/. A non-zero exit fails the job.

If you want to see it work before installing anything, the project page has an in-browser version of the same three checks. Paste your own HTML or JSON-LD, or load the broken fixture and watch it fail.

What I took away from it

"Defined" beats "mentioned." The bug was never invalid JSON. It was a graph that pointed at nodes that weren't there. Check the relationships, not just the syntax.
Test the failure, not just the success. A checker's most important test is the one where it's supposed to say no.
Small tools get used. It covers eight types on purpose, and only checks nodes at the top level of each graph. One file with no dependencies means there's no excuse to leave it out of CI. I'd rather have a narrow check that runs on every push than a thorough one that runs when I remember.

The structured data on bryanhamilton.info is held to the same standard. Every reference between its Person, projects, FAQ and breadcrumbs resolves.

Links

Code (MIT): github.com/bryanhamiltondev/jsonld-schema-audit
Case study and live demo: bryanhamilton.info/projects/jsonld-schema-audit
The site it keeps clean: The DJ Calendar

If you've been bitten by a dangling @id, or you check structured data some other way in CI, I'd like to hear how in the comments.

Building a Real Audio Hover Preview with Zero Dependencies

Bryan Hamilton — Wed, 07 Oct 2026 17:15:41 +0000

I run The DJ Calendar, a real-time EDM tour date platform. The homepage has 99 artist cards. I wanted you to be able to hover any of them and hear their music instantly — without navigating away, without a page load, without a framework.

Here's how I built it.

The Stack

Zero. No React, no Vue, no jQuery, no audio player library. Just vanilla JavaScript and two browser APIs that ship with every modern browser:

iTunes Search API — free 30-second audio previews
Web Audio API — real frequency analysis for the equalizer

Step 1: Getting the Audio

Apple's iTunes Search API is a public endpoint that doesn't need authentication. A single request with entity=musicTrack&limit=12&media=music returns preview URLs for any artist.

fetch(`https://itunes.apple.com/search?term=${encodeURIComponent(name)}&entity=musicTrack&limit=12&media=music`)
  .then(r => r.json())
  .then(data => {
    const result = data.results.find(r => r.previewUrl);
    if (result) {
      card.dataset.previewUrl = result.previewUrl;
      card.dataset.previewTitle = result.trackName;
    } else {
      card.dataset.previewMiss = '';
    }
  });

The preview URL gets cached on the card's data- attribute. First hover does the lookup. Every hover after that is instant.

Step 2: The Analyser — Real Frequencies, Not a Fake

This is the part I'm proudest of. The 8-bar equalizer isn't animated CSS pretending to be sound. It reads actual frequency data from the audio.

const audio = new Audio();
audio.crossOrigin = 'anonymous';

const ctx = new AudioContext();
const src = ctx.createMediaElementSource(audio);
const analyser = ctx.createAnalyser();
analyser.fftSize = 64;
analyser.smoothingTimeConstant = 0.8;

src.connect(analyser);
analyser.connect(ctx.destination);

const bufferLength = analyser.frequencyBinCount;
const dataArray = new Uint8Array(bufferLength);

function draw() {
  analyser.getByteFrequencyData(dataArray);
  // Clear canvas, draw 8 bars from dataArray[i*2]
  requestAnimationFrame(draw);
}

The fftSize of 64 gives us 32 frequency bins. Reading every other one (dataArray[i*2]) gives us exactly 8 bars. Each bar represents a real slice of the audio spectrum.

Step 3: The Race Condition Guard

Sweep your cursor across a row of cards fast and three things race: the audio load, the canvas draw loop, and your mouse leaving. Here's the fix:

card._djcPreviewGen = (card._djcPreviewGen || 0) + 1;
const gen = card._djcPreviewGen;

// Inside every async callback:
if (gen !== card._djcPreviewGen) return; // stale, abort

New hover bumps the counter. Every previous hover's callbacks check before touching the DOM. The orphaned callbacks just die silently.

Step 4: Consent-First Design

Most hover previews break on the devices where hover doesn't exist. This one treats every "no" as a first-class answer.

Touch devices (hover: none, pointer: coarse): hover never fires. A tap on the photo toggles play/stop. The tap also satisfies the autoplay policy — no extra click needed.

Reduced motion (prefers-reduced-motion: reduce): no hover preview at all. Motion-reactive feedback is exactly what these visitors asked the OS to skip.

No preview found: the card gets data-preview-miss and is silently skipped forever. No repeated failing lookups on every hover.

@media (hover: none) and (pointer: coarse) {
  .dj-card .card-image-overlay { display: none; }
}
@media (prefers-reduced-motion: reduce) {
  .dj-card .card-image-overlay { display: none; }
}

Step 5: The Extras

A few things that came for free once the audio pipeline was in place:

Document title swap: while a preview plays, the tab reads "David Guetta - Titanium (feat. Sia)". Restores on stop.
Media Session API: the track shows up in OS media controls with artwork.
Cross-origin audio: audio.crossOrigin = 'anonymous' is what makes the analyser legal on Apple's CDN. Without it, the analyser returns all zeros.

The Result

A hover preview that works on every device, respects every accessibility setting, handles race conditions, and drives a real audio-reactive equalizer — all in vanilla JS, zero dependencies.
[Try it Live] https://bryanhamiltondev.github.io/dj-card-preview/ — click the page once, then hover the card.

The full source is on GitHub: bryanhamiltondev/dj-card-preview

This is part of a series extracting production patterns from The DJ Calendar. Also check out the eq-visualizer (pure-CSS decorative EQ) and next-show-radar (consent-first tour map).

Extracting a Production Hover Preview: Audio, Canvas EQ, and Consent-First Design

Bryan Hamilton — Wed, 07 Oct 2026 17:00:58 +0000

1. The Problem
99 artist cards on The DJ Calendar homepage
Users needed a way to preview music without clicking through to each artist page
Requirements: must work on hover AND touch, must be zero-dependency, must handle browser autoplay policy

2. The iTunes Search API — Free Audio
No audio hosting needed — Apple's 30-second previews are publicly accessible
entity=musicTrack&limit=12&media=music — grab the first result with a preview URL
Cache it on the card's data-preview-url so it's a one-time lookup per card

3. Web Audio API Analyser — Real EQ, Not a Fake
createMediaElementSource feeds real audio into an analyserNode
fftSize: 64, smoothing: 0.8 — 8 bars reading their own frequency bins
Canvas draws each frame from dataArray[i*2]
This is the key line: "This is not an animation pretending to be sound"

4. The Race Condition Guard
Sweep across cards fast and audio load, canvas draw, and mouseleave all race
Each card has a _djcPreviewGen counter
New hover bumps the counter, previous async callbacks check before touching DOM
Simple pattern, saves a ton of edge-case bugs

5. Consent-First Design — The "No" States
Touch devices (hover: none, pointer: coarse): tap toggles play/stop
Reduced motion (prefers-reduced-motion: reduce): no hover preview
Conflicting audio: card previews pause the favorites player, resume it
No preview found: data-preview-miss, silently skipped forever
Most hover widgets break on these — this one treats them as first-class

6. Extras That Come Free
document.title swaps to "Artist - Track" while playing
navigator.mediaSession for OS media controls
crossOrigin: anonymous makes the analyser legal on cross-origin audio

7. The Extraction — From Production to Repo
This code was running on thedjcalendar.com for months
Extracted verbatim into a standalone repo with a GitHub Pages demo
Same code, no build step, no framework — just a script tag and some HTML

8. Live Demo
bryanhamiltondev.github.io/dj-card-preview
David Guetta — Titanium — click once, hover the card, hear it play

9. Sibling Repos
eq-visualizer — the decorative pure-CSS EQ
next-show-radar — the consent-first tour map