DJConnect. Muziekbediening met karakter.

DJConnect brengt spraak, muziekbediening en een persoonlijke DJ-reactie samen. De kern blijft hetzelfde op elk device: vraag muziek, kies waar het speelt en krijg directe feedback terug.

Wat ga je doen?

  1. Integreer DJConnect in Home Assistant
  2. Kies Spotify Direct of Music Assistant
  3. Koppel lokaal, gebruik apps daarna ook remote
Geniet van je eigen muziek, met je persoonlijke DJ

Vereisten

Deze checklist voorkomt de meeste installatieproblemen.

  • Home Assistant installatie
  • HACS geïnstalleerd in Home Assistant
  • Een muziekbackend: Spotify Direct of Music Assistant
  • Home Assistant Assist pipeline met werkende STT en TTS
  • Optioneel: geschikte Home Assistant media_player speaker voor spoken DJ announcements
  • DJConnect device, DJConnect app of Assist Conversation Agent route
  • Home Assistant en DJConnect client op hetzelfde lokale netwerk tijdens pairing; remote pairing wordt niet ondersteund
  • Voor ESP hardware: 2.4 GHz WiFi tijdens provisioning en lokaal gebruik
  • Alleen voor Spotify Direct: Spotify Premium en je eigen Spotify Developer app met Client ID
  • Voor Ontdek: Music DNA consent in Home Assistant
  • Alleen voor Music Assistant: Music Assistant geinstalleerd, providers geconfigureerd en een player geselecteerd
  • Optioneel voor remote iOS/macOS/Windows: een externe HTTPS Home Assistant URL, bij voorkeur Nabu Casa

Music backend kiezen

DJConnect 3.2 werkt met Spotify Direct of Music Assistant. Home Assistant meldt aan clients welke backend actief is en welke acties beschikbaar zijn.

Credentials blijven in Home Assistant

DJConnect devices en apps krijgen geen Spotify refresh token of playback credentials.

Remote na lokale pairing

iOS, macOS en Windows kunnen na lokale pairing via je externe Home Assistant URL werken. ESP32 en Raspberry Pi blijven local-only.

Optioneel: Track Insight providers

Track Insight werkt standaard met beschikbare playbackcontext of meegegeven trackmetadata. Optionele metadata- of contextproviders blijven server-side in Home Assistant; clients tonen de analyse en berekenen geen conclusies lokaal.

Music DNA en Ontdek

Ontdek bouwt aanbevelingen server-side via Home Assistant en werkt pas na expliciete Music DNA consent. Clients bewaren geen profiel; ze tonen alleen aanbevelingen, artwork, redenen en Play Now-acties uit het backendcontract.

3. Kies je music backend

Kies voor setup of DJConnect direct met Spotify werkt, of dat Music Assistant de centrale muzieklaag in Home Assistant is.

RequirementSpotify DirectMusic Assistant
Home AssistantRequiredRequired
HACS DJConnect integrationRequiredRequired
Spotify PremiumRequiredOnly if your Music Assistant Spotify provider needs it
Spotify Developer app / Client ID in DJConnectRequiredNot required
DJConnect Spotify OAuth/PKCERequiredNot used
Music Assistant installed in HANot requiredRequired
Music Assistant providers configuredNot requiredRequired in Music Assistant
Music Assistant player selectedNot requiredRequired
HA Assist STT/TTS for voiceRequired for voice/PTTRequired for voice/PTT
Nabu Casa/external HTTPS URLOptional, for remote iOS/macOS/WindowsOptional, for remote iOS/macOS/Windows
Local pairingRequiredRequired
FeatureSpotify DirectMusic Assistant
Play/pause/next/previousSupportedSupported if selected MA player supports it
Volume controlSupported if Spotify Connect output supports volumeSupported if MA player supports volume
Output/player selectionSpotify Connect devicesMusic Assistant players
Queue viewSupported via Spotify queueSupported if MA exposes queue/player queue
PlaylistsSpotify playlistsMA library/provider playlists if available
Search by artist/track/albumSpotify catalogMA library/providers if available
Ask DJ Play Now actionsSpotify URI actionsMA item/player actions
Current track / now playingSupportedSupported
Album art/imagesSupportedSupported if MA/provider exposes images
Favorites / liked songsSpotify Liked SongsCapability-dependent
Recently playedSpotify recently playedCapability-dependent
Top artists/tracks profileSpotify Web APIUsually not available unless MA/backend exposes equivalent
Personal music profile analysisRich Spotify profile dataLimited to MA/Music DNA data available
Personal recommendationsSpotify-backed where availableCapability-dependent
Local music filesNot supportedSupported if configured in Music Assistant
Tidal/Plex/Jellyfin/other providersNot supportedSupported if configured in Music Assistant
Multi-room/groupingSpotify Connect limitedMusic Assistant/player dependent
Backend switching laterSupported via HA options-flowSupported via HA options-flow

Kies Spotify Direct als...

je vooral Spotify gebruikt, de simpelste DJConnect muzieksetup wilt, Spotify-profieldata zoals recent/top/liked songs belangrijk vindt en geen Music Assistant draait.

Kies Music Assistant als...

Music Assistant al je centrale muziekhub is, je meerdere providers of lokale muziek gebruikt, of geen Spotify Developer app voor DJConnect wilt maken.

Capabilities sturen de UI

DJConnect vraagt Home Assistant welke backend actief is. Clients tonen acties die de backend ondersteunt en geven een vriendelijke melding als iets niet beschikbaar is.

Later wisselen kan

Je kunt de backend later wijzigen in de Home Assistant options-flow. Pairing, Ask DJ history en Music DNA blijven intact; oude backend-specifieke Play Now acties kunnen verlopen.

About en diagnostics

DJConnect 3.2 clients tonen de actieve music backend, target player, connection mode en belangrijkste capabilities in About/Diagnostics.

Voorbeeld

Top artists is beschikbaar met Spotify Direct. Met Music Assistant hangt dit af van gelijkwaardige profieldata in jouw Music Assistant setup.

Optioneel: lokale websocket fast path

Na lokale app-pairing kunnen iOS, macOS en Windows lokaal Home Assistant /api/websocket gebruiken voor lage-latency commands wanneer djconnect/capabilities dit meldt. HTTP blijft de fallback voor remote gebruik, pairing, voice uploads, history sync en media URLs.

VibeCast contract

VibeCast is een premium-ready Apple client feature via GET /api/djconnect/v1/vibecast. Supported Apple client types zijn ios, macos en watchos; iOS en macOS moeten functioneel hetzelfde werken.

Success bevat enabled:true, revision, ttl_seconds, poll_after_seconds, context, items[] en optioneel cache. Context bevat track, artist, album, music_backend, music_backend_name en music_backend_revision. Item kinds zijn track_fact, artist_fact, album_fact, genre_fact, trivia, listening_tip, mood_note, production_note, history_note en system.

Structured text

Items gebruiken structured text segmenttypes text, strong, emphasis, magnify, accent, emoji en line_break. Clients hoeven geen HTML of Markdown te parsen. Als een capability ontbreekt, bijvoorbeeld magnify, degradeert de client graceful zonder betekenisverlies.

Disabled responses

Disabled responses blijven JSON met enabled:false, reason, ttl_seconds, poll_after_seconds en items:[]. Clients tonen nooit raw provider/cache/decode/generation errors.

Disabled reasons

feature_disabled, premium_unavailable, no_active_playback, playback_inactive, unknown_track, unsupported_backend, provider_unavailable, generative_provider_unavailable, rate_limited, cache_failure, unauthorized, invalid_client_type, client_type_mismatch en privacy_disabled.

macOS/iOS parity

Gebruik hetzelfde endpoint, response contract, item kinds, structured text segmenttypes, disabled reasons en polling/cache semantics voor client_type:"macos" en client_type:"ios". De backend mag macOS en iOS niet verschillend behandelen qua contentkwaliteit, premium entitlement, fact generation, cache, TTL, revision of current-track resolution.

Backend-neutral

Home Assistant/backend playback is de source of truth. VibeCast maakt geen Spotify-only aannames: Spotify Direct, Music Assistant en toekomstige backends lopen via DJConnect backend abstraction. Clients pollen nu via ttl_seconds en poll_after_seconds; WebSocket of push kan later worden toegevoegd zonder contractbreuk.

Compatibility matrix

ComponentSupportConnectivityContract
Home Assistant/HACS integration3.2.xHome AssistantPatch versions may differ; major/minor must match. HTTP 426 version_mismatch means update the client or integration, not reset pairing.
ESP32 LilyGO T-Embed S3Protocol 3.2.xLocal-onlyLocal-device client with _djconnect._tcp, optional Client adres and /api/device/*.
ESP32-S3-BOX-3Not supportedNot supportedNot supported
Raspberry Pi/LinuxProtocol 3.2.xLocal-onlyLocal-device client with _djconnect._tcp, optional Client adres, /api/device/*, Pi restart/shutdown/display use cases and Ask DJ readonly_actions only.
iOSLocal pairingRemote-capable after local pairingInbound-only app client: djconnect-ios-XXXXXXXXXXXX, client_type ios, posts to /api/djconnect/v1/pair.
macOSLocal pairingRemote-capable after local pairingInbound-only app client: djconnect-macos-XXXXXXXXXXXX, client_type macos, posts to /api/djconnect/v1/pair.
WindowsLocal pairingRemote-capable after local pairingInbound-only app client: djconnect-windows-XXXXXXXXXXXX, client_type windows, posts to /api/djconnect/v1/pair.
watchOSVia iPhone proxyVia iPhone proxyNo separate Home Assistant pairing; the paired iPhone proxies Watch identity and sync.
HA Assist satellitesDJConnect conversation agentHome Assistant AssistNo device token, firmware controls or client pairing UI; STT/TTS stay in the HA Assist pipeline.

1. Configureer assist pipeline in Home Assistant

DJConnect gebruikt je Home Assistant voice pipeline voor stembesturing en gesproken DJ aankondigingen.

Hulp bij Home Assistant voice assist
  1. Maak of controleer je voice assist pipeline binnen Home Assistant
  2. Controleer spraakherkenning en gesproken output
  3. Gebruik deze pipeline straks in DJConnect
Automatisch

2. Voeg toe aan Home Assistant

Gebruik onderstaande Home Assistant Community Store knop om direct naar de DJConnect repository in HACS te gaan. Installeer de DJConnect integration v3.2.44 of nieuwer, herstart Home Assistant en voeg daarna DJConnect toe via Devices & services.

Open DJConnect in HACS
Handmatig

Voeg de repository zelf toe

  1. Open Home Assistant
  2. Open HACS
  3. Ga naar Integrations
  4. Voeg custom repository toe https://github.com/pcvantol/djconnect
  5. Kies category Integration
  6. Zoek en installeer DJConnect
  7. Herstart Home Assistant

4. Alleen Spotify Direct: maak een Spotify Developer app

Sla deze stap over als je Music Assistant gebruikt. Spotify Direct gebruikt je eigen Home Assistant installatie, Spotify Premium, een Spotify Developer app Client ID en OAuth/PKCE.

Gebruik bij voorkeur je Nabu Casa HTTPS external URL. De callback ishttps://<your-home-assistant-external-url>/api/djconnect/spotify/callback. DJConnect gebruikt PKCE; een Spotify Client Secret is bij voorkeur niet nodig.

  1. Open het Spotify Developer Dashboard.
  2. Maak een nieuwe app aan.
  3. Voeg je Home Assistant redirect URI toe:https://<your-home-assistant-external-url>/api/djconnect/spotify/callback.
  4. Kopieer de Spotify Client ID.
  5. Vul de Client ID in tijdens de DJConnect setup/config-flow.
  6. Autoriseer Spotify via Home Assistant.

5. Configureer DJConnect

Voeg DJConnect toe als Home Assistant integratie, kies je music backend en configureer alleen de velden die bij die backend horen.

  1. Open Home Assistant Settings -> Devices & services -> Add integration -> DJConnect
  2. Kies Spotify Direct of Music Assistant als music backend
  3. Bij Spotify Direct: vul je Client ID in en autoriseer Spotify via Home Assistant
  4. Bij Music Assistant: selecteer je Music Assistant player; Spotify OAuth in DJConnect is dan niet nodig
  5. Configureer voice via je Home Assistant Assist pipeline, niet via directe externe STT/TTS APIs
  6. Kies bij “Assist Conversation Agent” de DJConnect DJ agent voor Home Assistant Assist
  7. Kies in “Spraak en playback” optioneel een Home Assistant speaker voor DJ-aankondigingen

DJ-aankondigingen via Home Assistant speaker

Ask DJ blijft de intelligentie en persoonlijkheid. Een gekozen Home Assistant media_player is de fysieke stem in de ruimte.

App-clients

iPhone, iPad, macOS, Apple Watch en Windows ondersteunen Apparaat, Apparaat + Home Assistant speaker, Alleen Home Assistant speaker en Alleen tekst. Met een geconfigureerde HA speaker is Apparaat + Home Assistant speaker de default; zonder speaker zijn speaker-modi locked.

Pi en ESP32

Raspberry Pi heeft geen lokale audio-output en ondersteunt tekst-only of HA speaker. ESP32 blijft de bestaande device-speaker/DJ response flow gebruiken.

Spotify Direct verwachting

Bij Spotify Direct blijft Spotify playback gewoon doorspelen. DJConnect pauzeert Spotify niet, hervat niet en past volume niet automatisch aan; de DJ-stem speelt apart via de gekozen HA speaker.

6. Koppel app of device lokaal

Pairing/token bootstrap gebeurt lokaal. iOS, macOS en Windows zijn inbound-only app clients en kunnen daarna remote werken via Home Assistant; ESP32 en Raspberry Pi blijven local-device clients en local-only.

Lokaal pairen, daarna remote gebruiken

Tijdens pairing zitten Home Assistant en de DJConnect client bewust op hetzelfde lokale netwerk. Na succesvolle pairing kunnen iPhone, Apple Watch, macOS en Windows remote werken als Home Assistant een externe/Nabu Casa HTTPS URL heeft.

Waarom lokaal?

Lokale pairing voorkomt remote exposure van bootstrap en vereist LAN-aanwezigheid plus een tijdelijke code of QR. Zo blijft de tokenflow eenvoudiger en veiliger.

Waarom geen remote pairing?

Remote pairing zou extra expiry, replay protection, rate limiting, phishing/error states en afhankelijkheid van je external URL vragen. DJConnect houdt pairing daarom lokaal en gebruikt remote pas na succesvolle koppeling.

iOS app

  1. Download iOS app
  2. Open de DJConnect app op hetzelfde lokale netwerk als Home Assistant
  3. Scan de QR/deep-link payload die Home Assistant genereert
  4. Geen Client adres kopiëren: de app belt Home Assistant zelf via /api/djconnect/v1/...
  5. Daarna kan de app lokaal of remote werken via je Home Assistant URL
  6. Voor Apple Watch genereert Home Assistant een aparte Watch QR/deep-link payload. Scan die met iPhone; iPhone geeft de pairinggegevens door aan de gekoppelde Watch.
  7. Ask DJ audio kan op apparaat, apparaat + Home Assistant speaker, alleen Home Assistant speaker of alleen tekst; speaker-modi zijn beschikbaar zodra Home Assistant een announcement speaker heeft.

macOS app

  1. Download macOS app
  2. Open de DJConnect app op hetzelfde lokale netwerk als Home Assistant
  3. Voer handmatig de lokale Home Assistant URL en de door Home Assistant gegenereerde koppelcode in
  4. Geen Client adres kopiëren: de app belt Home Assistant zelf via /api/djconnect/v1/...
  5. Daarna kan de app lokaal of remote werken via je Home Assistant URL
  6. Ask DJ audio kan op apparaat, apparaat + Home Assistant speaker, alleen Home Assistant speaker of alleen tekst; speaker-modi zijn beschikbaar zodra Home Assistant een announcement speaker heeft.

Windows app

  1. Download Windows app
  2. Installeer de DJConnect Windows desktop app zodra je build beschikbaar is
  3. Open de DJConnect app op hetzelfde lokale netwerk als Home Assistant
  4. Voer handmatig de lokale Home Assistant URL en de door Home Assistant gegenereerde koppelcode in
  5. Geen Client adres kopiëren: de app belt Home Assistant zelf via /api/djconnect/v1/...
  6. Daarna kan de app lokaal of remote werken via je Home Assistant URL
  7. Ask DJ audio kan op apparaat, apparaat + Home Assistant speaker, alleen Home Assistant speaker of alleen tekst; speaker-modi zijn beschikbaar zodra Home Assistant een announcement speaker heeft.

ESP device

  1. Download ESP firmware
  2. Zet het DJConnect device aan en verbind het device met WiFi via captive portal of Home Assistant BLE WiFi provisioning
  3. Open DJConnect integratie setup in Home Assistant
  4. Voer de koppelcode in van het device
  5. Het DJConnect ESP32 apparaat gebruikt _djconnect._tcp of Client adres, alleen de lokale /api/device/* device API en blijft local-only
  6. ESP32 blijft de bestaande device-speaker/DJ response flow gebruiken.

Voice Assistant

  1. Bekijk Voice Assistant uitleg
  2. Kies in de DJConnect setup voor Assist Conversation Agent
  3. Selecteer DJConnect als conversation agent in je Home Assistant Assist configuratie
  4. Gebruik je HA Assist satellite, Home Assistant Voice Preview Edition, M5 Atom Echo of ander ESPHome-powered voice project voor wake word, microfoon en speaker-output
  5. Dezelfde of een andere HA speaker kan optioneel als DJ-aankondiging speaker worden gekozen.
  6. Geen client pairing, device token of Client adres nodig

Raspberry Pi app

  1. Download Linux app
  2. Installeer de DJConnect Raspberry Pi app via GitHub
  3. Open DJConnect integratie setup in Home Assistant
  4. Kies client type Raspberry Pi app en koppel lokaal op hetzelfde netwerk
  5. Raspberry Pi gebruikt _djconnect._tcp of Client adres, lokale /api/device/* runtime/device-connectiviteit en blijft local-only
  6. Raspberry Pi heeft geen lokale audio-output: Ask DJ is tekst-only of speelt via de gekozen Home Assistant speaker.

Technisch: app-clients zijn inbound-only

iPhone, Apple Watch, macOS en Windows publiceren geen lokale app API voor Home Assistant. Home Assistant belt nooit terug naar de app; de client post zelf naar POST /api/djconnect/v1/pair en gebruikt daarna Home Assistant routes. Er is geen app-client mDNS/local-API discovery of fallback.

Technisch: local-device clients blijven lokaal

ESP32 en Raspberry Pi gebruiken lokale/two-way pairing, mogen via mDNS _djconnect._tcp gevonden worden en gebruiken lokale /api/device/*. Zij krijgen geen ha_remote_url en blijven bedoeld voor gebruik op je lokale netwerk.

Release- en downloadlinks

Gebruik de platformpagina's hieronder voor de nieuwste publieke builds. De downloadkaarten lezen de actuele GitHub Releases en routeren downloadkliks privacyvriendelijk via djconnect.dev.

HACS

Home Assistant integration uit pcvantol/djconnect, category Integration, versie 3.2.x.

HACS

iOS / macOS / Windows

App builds komen uit pcvantol/djconnect-app-releases met aparte platformfilters voor iOS, macOS, Windows en Mac Catalyst.

iOSmacOSWindows

ESP32

Firmware komt uit pcvantol/djconnect-firmware en blijft bedoeld voor ondersteunde local-device hardware.

ESP32

Raspberry Pi / Linux

Linux/Raspberry Pi builds en install command komen uit pcvantol/djconnect-pi-releases.

Linux

APNs / Privacy

Apple push is optioneel en alleen een wake/sync hint. De relay ontvangt geen Spotify tokens, HA tokens, raw prompts, raw audio, volledige Ask DJ history of Music DNA.

Privacy

Support

Gebruik support voor installatieproblemen, HACS updates, pairing, STT/TTS, backend capabilities of ontbrekende release assets.

Support

7. Klaar voor gebruik

Start muziek op je gekozen player of output en bedien daarna alles via DJConnect.

  1. Kies je player/output in Spotify Direct of Music Assistant
  2. Bedien je muziek via DJConnect
  3. Vraag de volgende artiest aan met je stem
  4. Bekijk in About/Diagnostics je connection mode, actieve backend, target player en capabilities