MAIR

MAIR is een persoonlijke Nederlandse AI-radio boven op een Spotify Premium-account. De app programmeert een doorlopende radioset, beheert verzoeken en voegt op natuurlijke trackovergangen korte DJ-breaks toe.

Architectuur

• Spotify OAuth gebruikt PKCE; er staat geen Spotify client secret in de browser.
• Eén Spotify Web Playback SDK-instance registreert het afspeeldevice.
• playback-primary.js is eigenaar van play/pause/previous/next, natuurlijke overgangen en herstel.
• queue-core.js serialiseert queue-wijzigingen; Spotify blijft de bron voor wat daadwerkelijk als volgende klaarstaat.
• mair-dj-v2.js plant en speelt DJ-breaks. mair-dj-schedule-sync.js levert één gededupliceerd fallback-signaal als een primair trackeinde-event ontbreekt.
• /api/dj-writer genereert uitsluitend Nederlandse DJ-copy via Groq. Als de writer faalt, blijft de muziek spelen en gebruikt MAIR een korte lokale Nederlandse fallback.
• /api/tts genereert MP3 via Edge (Microsoft Read Aloud, gratis en zonder sleutel) met de nl-NL-stemmen Maarten (Josh), Fenna (Maya) en Colette (Max). Edge is onofficieel: faalt hij, dan neemt Fish Audio het over. Faalt die ook, dan slaat de DJ de break over en speelt de muziek door. In de browser krijgt elke stem dezelfde radiobewerking (EQ, compressie, vast niveau).
• De diagnosekaart toont playback-, queue-, DJ-, writer-, voice-, TTS-, cache- en herstelstatus zonder secrets te tonen.
• De service worker maakt de hoofdinterface installeerbaar als PWA en bewaakt release/cacheversies.

Environment variables

Configureer secrets uitsluitend in Vercel of een vergelijkbare serveromgeving. Commit nooit keys of tokens.

Vereist voor de volledige ervaring:

• SPOTIFY_CLIENT_ID: publieke Spotify-app Client ID. Kan anders lokaal in Instellingen worden ingevoerd.
• MAPBOX_PUBLIC_TOKEN: Mapbox Directions + Geocoding voor de navigatie in Car Mode. Dit hoort een publiek pk.-token te zijn met een URL-restrictie op het eigen domein, want /api/config geeft het runtime aan de browser. Zonder dit token meldt Car Mode "Mapbox-token ontbreekt" en werkt bestemmingszoeken en routering niet; de radio zelf blijft normaal doorspelen.
• ANTHROPIC_API_KEY: Claude schrijft DJ-copy, nieuws, discovery en de categoriefilters. Zonder deze sleutel neemt Groq alles over.
• GROQ_API_KEY: vangnet achter Claude voor /api/dj-writer, /api/news-bulletin, /api/discover en /api/category-filter. Houd deze ingevuld: hij houdt de radio aan de praat als Anthropic eruit ligt of te traag is.
• FISH_AUDIO_API_KEY: Nederlandse DJ-audio via /api/tts.

Optioneel:

• ANTHROPIC_TEXT_MODEL: expliciet Claude-model. Zonder override gebruikt MAIR claude-opus-5-5. Kies een model dat output_config.effort ondersteunt (Claude 4.6 en nieuwer); oudere modellen geven een 400 en vallen dus altijd door naar Groq.
• MAIR_ALLOWED_SPOTIFY_USERS: komma-gescheiden Spotify-gebruikers-id's die de AI-routes mogen gebruiken. Zonder lijst mag elke geldige Spotify-sessie erdoor. Zet dit voordat er een ANTHROPIC_API_KEY in gaat, anders kan iedere Spotify-gebruiker met curl op jouw kosten tekst laten schrijven.
• MAIR_ALLOWED_ORIGINS: extra origins naast het eigen domein (komma-gescheiden, exact). Normaal niet nodig: de app en de Capacitor-shell draaien allebei op het eigen domein.

De AI-routes (/api/dj-writer, /api/discover, /api/category-filter, /api/news-bulletin) en de routes die externe diensten of Fish Audio-tegoed gebruiken (/api/tts, /api/fact) eisen een eigen Origin en een Spotify-token (api/_guard.js; de client zet dat via mair-ai-auth.js). Daarboven staat in de Vercel Firewall de regel AI-routes rate limit: 30 verzoeken per minuut per IP, over alle instances heen.

• GROQ_DJ_MODEL: expliciet ondersteund Groq-model. Zonder override probeert MAIR openai/gpt-oss-120b en daarna openai/gpt-oss-20b.
• FISH_AUDIO_MODEL: expliciet Fish-model. Zonder override probeert MAIR s2.1-pro-free en daarna s2-pro.
• FISH_AUDIO_VOICE_JOSH, FISH_AUDIO_VOICE_MAYA, FISH_AUDIO_VOICE_MAX: per-DJ voice override.
• FISH_AUDIO_VOICE_ID: algemene voice override als geen profieloverride bestaat.

Een ontbrekende AI- of TTS-key mag playback niet stoppen. MAIR slaat de break over of gebruikt lokale copy en meldt de oorzaak in Diagnose.

Spotify en deployment

1. Maak een Spotify Developer-app en kopieer de Client ID.
2. Deploy de repository naar HTTPS; Vercel is ingericht via vercel.json.
3. Open de deployment. Kopieer in Instellingen de exacte Redirect URL en voeg die toe aan de Spotify-app.
4. Voeg de environment variables toe en redeploy.
5. Koppel Spotify in MAIR. Spotify Premium is vereist voor Web Playback SDK-streaming.

Wijzigingen worden ontwikkeld op een branch en met npm run predeploy gevalideerd. Gebruik een preview/branch deployment voor runtimevalidatie; merge of deploy niet rechtstreeks naar productie zonder bewuste releasebeslissing.

Testen en diagnose

npm run predeploy voert de statische regressiepoort en gedragsimulaties uit voor playback, queue, requests, DJ-scheduling, voice, TTS en API-fouten.

npm run e2e draait de echte app in headless Chrome tegen een nep-Spotify (scripts/e2e/): station starten, pauze, skip, natuurlijke trackwissel, DJ-break met ducking, writer/TTS-storing, skip tijdens een break, apparaatverlies, 429, tokenverversing, verzoeken, slaaptimer en verborgen tab. Geen account, netwerk of Widevine nodig; wel Playwright en Chrome. Het zit bewust niet in predeploy. Het zegt iets over de aansturing, niet over hoe het klinkt of hoe echte Spotify zich gedraagt: een luistertest op een echt toestel blijft nodig.

Open in de app Instellingen → Diagnose voor:

• huidige en volgende track;
• laatste trackevent en Spotify-queue sync;
• DJ-fase, volgende beslissing en fallback-overgangssignalen;
• gebruikte writer/model en stem;
• TTS-status, route en laatste fout;
• playback-herstel, cacheversie en een veilige herstelactie.

iPhone/PWA

Open de productie-URL in Safari, kies Deel → Zet op beginscherm. Start audio altijd eenmaal vanuit een zichtbare gebruikersactie; iOS vereist dat om audio te ontgrendelen. iOS kan webapps in de achtergrond bevriezen. Spotify kan blijven spelen en MAIR synchroniseert state en herstel bij terugkeer naar de voorgrond.

Privacy

Spotify tokens, voorkeuren en luisterhistorie worden lokaal in de browser opgeslagen. Serverroutes ontvangen alleen de context die nodig is voor DJ-copy, discovery of spraak. Diagnose toont geen API-keys, OAuth-tokens of volledige credentials.