Skip to content
← All articles

Published on 7 min read

8D audio in the browser: a Web Audio graph and streamed tracks

How Calmind builds 8D audio with the Web Audio API: an HRTF panner, moving source, streaming for long tracks, and short-lived signed R2 URLs for ambient sounds.

Related project: Calmind

Calmind is a PWA for calm, focus and sleep, built around soundscapes that can run for hours. Audio poses two opposite problems. An ambient loop has to repeat without gaps, so it is best kept ready in memory. A three-hour track does not fit in memory and has to be read piece by piece. The code uses different paths for the two cases, and the 8D effect runs through both.

The graph: one context, one panner

Howler creates an AudioContext and exposes it. Rather than creating a second one, the 8D graph is built on top of Howler's: a node cannot be connected to a different context, so Howler's master gain and the panner have to share one. The chain looks like this:

masterBus (GainNode) → PannerNode (HRTF) → StereoPannerNode → destination

The panner sets panningModel = "HRTF", falling back to equalpower if the browser rejects the model, with distanceModel = "inverse" and refDistance = 1. When 8D is on, Howler's master gain is routed through the masterBus; when it is off, it goes straight to the destination. The code gates 8D to the zen_master plan.

A source that orbits the listener

The movement is a circle drawn in requestAnimationFrame. Each frame accumulates the angle as the sum of dt times the speed, so changing speed mid-rotation does not make the phase jump:

const t = sharedCtx.currentTime;
sharedPanner.positionX.setValueAtTime(Math.cos(hAngle) * RADIUS, t);
sharedPanner.positionY.setValueAtTime(Math.sin(vAngle) * V_AMP, t);
sharedPanner.positionZ.setValueAtTime(-Math.sin(hAngle) * RADIUS, t);
// Same angle, hard stereo pan in series after the HRTF
sharedStereoPanner?.pan.setValueAtTime(Math.cos(hAngle), t);

The second panner answers a limit that a code comment describes: HRTF models realistic hearing, so it always leaks some crosstalk into the "off" ear. The stereo pan in series pushes the sides to full separation, while HRTF keeps the cues for depth and height. The slider runs from 0.02 to 0.8 rad/s, with a default of 0.1: at 0.1 rad/s a full orbit takes about 63 seconds. When the page goes to the background the animation frame stops, and on return the first frame has no delta, so the sound does not jump.

Two strategies for sounds

The ambient mixer downloads each file whole. fetchAudioBlob fetches the URL, turns the response into a blob and hands it to a Howl with preload: true, which decodes it into memory. The cache is keyed by assetId, not by URL, because signed URLs change every time the backend cache refreshes. Concurrent requests for the same asset share one promise. Each Howl is created once and reused, so starting a sound again reloads nothing.

The local sound files I measured run from under three seconds to about two and a half minutes. For those, decoding into memory is the right trade-off. The delay before a loop restarts depends on its length: 15 seconds for sounds up to 10 seconds, 10 seconds for sounds up to 30, and none for loops that must restart without a gap. After every play() the code reattaches the analyser, because Howler creates a new node on each playback.

A music track is a different story. The four tracks stored locally run from 122 to 184 minutes, and the largest file weighs 176 MB at 128 kbps. Decoded to stereo PCM at 44.1 kHz, the longest would occupy about 3.9 GB in memory, and about 4.2 GB at 48 kHz. Downloading and decoding that is not sustainable on a phone. That is why music is streamed.

Long tracks: streaming through a proxy

For music (useMusicRadio), the Howl uses html5: true: the sound plays through a regular <audio> element that reads the file in pieces. The source is the backend proxy, not an R2 URL:

const streamUrl = `${BASE_URL}/music/stream/${track.trackId}?st=${encodeURIComponent(streamToken)}`;
const newHowl = new Howl({
  src: [streamUrl],
  format: ["mp3"],
  loop: true,
  volume: 0,
  html5: true,
});

An <audio> element cannot send an Authorization header, so the token goes in the query string. The frontend calls /music/stream-token, receives a one-hour JWT with the music_stream scope, and renews it five minutes before it expires. The backend forwards the request to R2 with the Range header: the answer is a 206 with Content-Range, and when the client closes the connection the response body is destroyed.

Why a proxy and not a signed URL? A signed URL is a link valid for an hour that anyone can open. Behind the proxy, a copied link opened in a new tab carries no Origin or Referer from the site, and it is refused with a 403. That is not a barrier against someone scripting requests, since a script can send any header, but it blocks the simplest kind of reuse. The catalogue maps 40 tracks to 13 genres, including lo-fi, jazz, solo piano and synthwave.

Ambient sounds: direct signed URLs

Ambient sounds take a different path, and I want to be precise about it. The backend catalogue has 23 environments, five of them free. The response from /environments/:id/sounds contains, for each sound, a signed R2 URL valid for one hour, and the browser downloads it directly. The backend caches that response for ten minutes, well under the expiry. A copied URL like this works for an hour. The project's technical document says audio files can never be downloaded from a copied link. That holds for music, but not for ambient sounds.

The choice to return direct URLs has a history. The repository contains a commit that fixes a specific problem: a redirect from the backend to storage made the audio's CORS requests fail, so the response was changed to include the signed URL directly. The four sounds on the landing page are different: they are static files in the site's public folder. That page is public and goes through no authentication.

What runs in production, and what does not

I separate what the code does from what the documentation promises.

  • In production: the 8D graph on Web Audio, streamed tracks through a token-protected proxy, signed R2 URLs for ambient sounds, reuse of Howl and of the <audio> node, and a graph rebuild when Howler swaps its context.
  • Not handled: switching the audio output, such as Bluetooth headphones disconnecting or a speaker taking over from them. There is no listener for devicechange and no setSinkId. The technical document mentions device changes being handled: the code handles Howler swapping its context, not the system's output device changing. Neither repository has a branch with audio work in progress, and no project document plans it.
  • iOS and Safari: I found no audio-specific handling, in the code or in the documents. The code detects a missing AudioContext and turns 8D off with a warning. The Safari commits in the history concern sign-in, not audio.
  • Scalability: the 500-user analysis identifies the music proxy as a possible bottleneck under load, and sets a target of one hundred open streams at once. That is a target, not a measured result. The same document flags that on Vercel a long stream could exceed the serverless function duration limit: a risk still to be verified.

What I would do differently

The mixer downloads everything before playing. With a few sounds that is fine, but with many playing together memory grows. I would cap the number of decoded buffers, or stream the longer effects too. The second point is the copyable link on ambient sounds: I would tie them to the session, as the music already is, at the cost of one more endpoint. The third is audio output switching, the most concrete gap for anyone listening on headphones. Finally, I would test streaming with one hundred real connections, instead of trusting the target.

You can try Calmind at www.calmind.it.

  • Web Audio API
  • React
  • audio streaming
  • Cloudflare R2
  • Howler.js

Have a similar project? Let's talk

If you're facing a similar challenge, get in touch and I'll tell you how I would approach it.

Let's talk