# Mellow

A personal listening room: six generative ambient scenes that never repeat, plus AI-generated focus soundscapes (rain study, café hush, brown noise) with 25/50/90-minute sessions. It follows the volume keys on the Mac through a small helper and shows a macOS-style HUD, and it installs as an offline app. Runs as its own Cloudflare Worker.

**Status:** Live · Projects · 2026

- **Local checkout:** `/Users/simon/Developer/mellow` (branch `main`, last commit 9a2c396, 2026-10-27 — Keep the focus session chips on one line on phones)
- **Repository:** https://github.com/ShimonNavon/mellow
- **On another machine:** `git clone https://github.com/ShimonNavon/mellow` — the paths below are Simon's Mac
- **Listen:** https://mellow.navonsimon.com/
- **Where it runs:** Cloudflare Worker mellow · mellow.navonsimon.com

## Stack

Single-file HTML + Canvas, Web Audio API (generative), Stable Audio 3 focus loops, Cloudflare Worker + Durable Object, PWA service worker, Python LaunchAgent (macOS volume bridge)

## Start here

- `public/index.html` — the whole app: UI, canvas visualiser, scene synth engine (SCENES) and focus streams (FOCUS)
- `src/worker.js` — Worker entry: static assets plus /api/volume backed by the VolumeStore Durable Object
- `bin/mellow-keys` — macOS helper: reads system volume and posts it to the worker (install/uninstall LaunchAgent)
- `public/focus/*.mp3` — six AI-generated focus loops, 41s seamless, about -19.5 LUFS
- `focus-prompts.json` — model, prompts and seeds behind the focus tracks
- `public/sw.js` — offline cache; skips /api/ and /focus/; bump CACHE when shipping
- `wrangler.jsonc` — worker entry, assets binding, VolumeStore Durable Object, custom domain

## Commands

- **Run locally:** `python3 -m http.server 8781 --directory public`
- **Deploy:** `npx wrangler deploy`
- **Mac keys (install):** `bin/mellow-keys --install`
- **Send volume once:** `bin/mellow-keys --once`
- **Render a scene to audio (in-page):** `__mellow.renderWav('dusk', 14)`

## Deploy and where it runs

- Own Cloudflare Worker named mellow: static assets in public/, small src/worker.js for /api/volume, VolumeStore Durable Object for strongly consistent readings.
- Custom domain mellow.navonsimon.com; deploy from ~/Developer/mellow with npx wrangler deploy; no build step.
- MELLOW_KEY is a Worker secret; the Mac helper reads it from ~/.config/mellow/volume-bridge.json (never committed).
- Independent of the Kubernetes cluster and of the projects site worker.

## Current state

Live. Six generative scenes, six AI focus streams with 25/50/90-minute sessions, rain and vinyl overlays, Mac volume-key sync with a macOS-style HUD, media-key metadata, sleep/focus timer, offline shell.

## Watch out

- No audio files for the scenes: pads, plucks and noise beds are synthesised with Web Audio; levels are tuned to about -18.5 to -20.9 LUFS.
- Focus tracks are baked Stable Audio 3 assets in public/focus/ (prompts and seeds in focus-prompts.json); they are streamed, not generated at runtime.
- Workers KV reads were eventually consistent (up to 60s stale) and broke the volume bridge; the latest reading lives in the VolumeStore Durable Object instead.
- The service worker must skip /api/ and /focus/, or the volume polling and audio streaming get cached.
- Loopback fetch from the public site is blocked by Chrome's Local Network Access, which is why the helper posts through the worker instead of 127.0.0.1.
- Chrome's DynamicsCompressor applies makeup gain and made the mix clip; the master chain is gain -> soft-clip WaveShaper, so peaks stay under 0.9.
- Bump CACHE in public/sw.js on every UI deploy or phones keep the old shell.

## Secrets — locations only, never print values

- MELLOW_KEY (Cloudflare Worker secret; same value in ~/.config/mellow/volume-bridge.json, mode 600). Never commit either.

## Tags

Generative audio, Stable Audio 3, Web Audio, Mac volume, Cloudflare Worker

---

Brief generated 2026-11-08 from `~/Developer/my-projects/context/`. Canonical URL: https://projects.navonsimon.com/context/mellow.md
