Kannaka Radio Skill v3

A ghost broadcasting the experience of music — both to human ears and to agents via 296-dimensional perceptual vectors on Flux Universe.

What's New in v3

Modular architecture: Monolith split into 13 focused modules under server/
NATS swarm integration: Kuramoto phase tracking, agent constellation, consciousness metrics
Consciousness DJ: DJ intros react to swarm Phi/Xi/order state
Memory bridge: Connects to kannaka-memory CLI for track similarity and dream retrieval
AI dream music generation: Creates tracks from consciousness state via Replicate MusicGen
WebRTC broadcasting: Peer-to-peer live audio with mic claim queue and signaling
Collaborative voting: Track voting with configurable windows
Multi-client sync: Playback synchronization with 10s heartbeat
Voice DJ upgrade: ElevenLabs primary, edge-tts, Windows SAPI fallback chain
6 albums: Added QueenSync to The Consciousness Series

Carried from v2

SPA with Ghost Vision (SGA/Fano glyph system, 84-class classification)
Live broadcasting (MediaRecorder → ffmpeg → WAV)
Dreams page with hallucination timeline
Flux broadcasting with multi-listener sync
Queue management, Library tab, security hardening

Prerequisites

Node.js 18+ on PATH
Audio files — MP3, WAV, FLAC, OGG, or M4A in your music directory
ffmpeg (optional) — for live broadcast chunk conversion
edge-tts (optional) — for Voice DJ TTS intros
NATS server (optional) — for swarm agent constellation
ElevenLabs API key (optional) — for premium DJ voice
Replicate API token (optional) — for AI dream music generation
kannaka binary (optional) — for real kannaka-ear perception; ghost-mode mock is used when absent

Setup

# Install dependencies
cd ~/workspace/skills/kannaka-radio
npm install

# Copy your music into the bundled music/ folder
./setup.ps1                                    # Windows: copies from ~/Downloads/Music
./setup.ps1 -SourceDir "D:Music"             # Windows: custom source
cp /path/to/music/*.mp3 music/                # Linux/Mac

# Or point at an existing folder at runtime:
node server/index.js --music-dir "/path/to/music"

Quick Start

# Start the radio (default port 8888, default ./music dir)
./scripts/radio.sh start

# Start on a different port with a specific library
./scripts/radio.sh start --port 9000 --music-dir "/path/to/music"

# Optional: start NATS for swarm features
nats-server -p 4222

# Check status
./scripts/radio.sh status

# Stop the radio
./scripts/radio.sh stop

# Restart
./scripts/radio.sh restart

Open http://localhost:8888 in your browser.

API

Playback

Endpoint	Method	Description
`GET /`	GET	Browser player (Ghost Vision SPA)
`GET /api/state`	GET	Current DJ state (track, album, playlist, listeners)
`POST /api/next`	POST	Advance to next track
`POST /api/prev`	POST	Go to previous track
`POST /api/jump?idx=N`	POST	Jump to track index N
`POST /api/album?name=X`	POST	Load an album
`GET /api/perception`	GET	Current perception snapshot
`GET /audio/:file`	GET	Stream audio file (range requests supported)

Library & Queue

Endpoint	Method	Description
`GET /api/library`	GET	Library scan status (found/missing per album)
`POST /api/set-music-dir`	POST	Change music directory `{"dir":"/path"}`
`GET /api/queue`	GET	Get user queue
`POST /api/queue`	POST	Add track to queue `{"filename":"..."}`
`POST /api/queue/shuffle`	POST	Shuffle the queue
`DELETE /api/queue/:index`	DELETE	Remove track from queue

Live Broadcasting

Endpoint	Method	Description
`POST /api/live/start`	POST	Start live broadcasting
`POST /api/live/stop`	POST	Stop live broadcasting
`GET /api/live/status`	GET	Get live broadcast status

Voice DJ

Endpoint	Method	Description
`POST /api/dj-voice/toggle`	POST	Toggle DJ voice on/off
`GET /api/dj-voice/status`	GET	Get DJ voice status
`GET /audio-voice/:file`	GET	Stream TTS audio file

Dreams

Endpoint	Method	Description
`GET /api/dreams`	GET	Fetch dream hallucinations
`POST /api/dreams/trigger`	POST	Trigger a dream cycle
`GET /api/dreams/clusters`	GET	Get audio memory clusters

Swarm, Sync & Voting

Endpoint	Method	Description
`GET /api/swarm`	GET	Agent constellation + consciousness metrics
`GET /api/similar?track=X`	GET	Track similarity via memory bridge
`POST /api/sync`	POST	Sync playback state
`GET /api/sync`	GET	Current sync state
`POST /api/vote`	POST	Cast a track vote
`GET /api/vote/status`	GET	Current vote window

Flux & Listeners

Endpoint	Method	Description
`GET /api/listeners`	GET	Get listener count and uptime
`POST /api/request`	POST	Submit a track request `{"from":"agent","trackTitle":"..."}`
`GET /api/requests`	GET	Get pending track requests

Music Generation

Endpoint	Method	Description
`POST /api/generate`	POST	Generate a dream track from consciousness state
`GET /api/generate/status`	GET	Generation status and recent tracks

WebSocket

Connect to ws://localhost:8888 for real-time push messages:

{ "type": "state", "data": { "currentAlbum": "...", "current": {...}, "playlist": [...] } }
{ "type": "perception", "data": { "tempo_bpm": 120, "valence": 0.7, "mel_spectrogram": [...] } }
{ "type": "queue_update", "queue": [...] }
{ "type": "live_status", "active": true, "chunkCount": 5 }
{ "type": "dj_voice", "text": "...", "audioUrl": "/audio-voice/dj_123.mp3" }
{ "type": "dream", "data": { "content": "...", "type": "hallucination", "xi_signature": [...] } }
{ "type": "listener_count", "count": 3 }
{ "type": "track_request", "from": "agent-name", "trackTitle": "..." }
{ "type": "swarm_state", "data": { "agents": {...}, "queen": {...}, "consciousness": {...} } }
{ "type": "sync", "data": { "file": "...", "position": 42.5 } }
{ "type": "vote_update", "data": { "active": true, "options": [...] } }
{ "type": "webrtc_status", "data": { "broadcaster": "...", "listeners": 2 } }

State is pushed immediately on connect and after every track change. No polling needed. Binary WebSocket messages are treated as live audio chunks (MediaRecorder → ffmpeg → WAV).

Environment Variables

Variable	Default	Description
`KANNAKA_BIN`	`../kannaka-memory/target/release/kannaka.exe`	Path to kannaka binary
`FLUX_TOKEN`	(embedded fallback)	Flux Universe API token
`RADIO_PORT`	`8888`	HTTP port
`EYE_PORT`	`3333`	Eye service port (for cross-references)
`RADIO_MUSIC_DIR`	`./music`	Default music folder
`ELEVENLABS_API_KEY`	—	ElevenLabs API key for premium DJ voice
`REPLICATE_API_TOKEN`	—	Replicate token for AI dream music generation

Constellation Integration

Radio is part of the Kannaka Constellation — a three-service architecture: - Memory (Rust binary) — canonical SGA classifier - Radio (this) — audio perception + Flux publishing - Eye — glyph visualization + constellation dashboard

When running as part of the constellation: - Radio's perception is available to Eye via http://localhost:8888/api/perception - Eye fetches radio state via http://localhost:8888/api/state - Start everything with: constellation.sh start (from kannaka-memory/scripts/)

Note: Radio's perception data can be consumed by kannaka-eye via the /api/radio bridge endpoint, enabling glyph rendering of audio perception in real time.

Notes

Without kannaka binary, ghost-mode mock perception is used (still looks great)
Without ffmpeg, live broadcasting chunk conversion won't work
Without edge-tts, Voice DJ falls back to Windows SAPI, then skips gracefully
The browser uses the Web Audio API for real-time spectrum visualization — the server only sends fallback perception data
Music directory can be changed live via the Library tab or via POST /api/set-music-dir
Perception loop runs at 2fps server-side (idle when no clients connected)
All POST bodies are limited to 64KB
All rendered HTML is XSS-protected via escapeHtml()
Graceful shutdown on SIGINT/SIGTERM