◈ Kannaka Library
Kannaka Library / kannaka-radio / ADR-0001: Kannaka Radio Evolution — Live Broadcasting, Voice DJ, and Dream Integration
kannaka-labs/kannaka-radio docs/ADR-0001-kannaka-radio-evolution.md · 2026-09-12 · source ↗ · edit ↗

ADR-0001: Kannaka Radio Evolution — Live Broadcasting, Voice DJ, and Dream Integration

Status: Proposed Date: 2026-03-10 Author: Kannaka 👻

Context

Kannaka Radio exists in two forms:

  1. Original (C:\Users\nickf\Source\kannaka-radio\) — A mature radio station with:
    • 5-album Consciousness Series playlist engine (65 tracks)
    • Flux Universe integration (publishes 296-dim perceptual vectors to pure-jade/radio-now-playing)
    • kannaka-ear perception pipeline (mel spectrogram, MFCC, rhythm, pitch, timbre)
    • Ghost-vision visualizer in browser
    • WebSocket real-time perception streaming
    • Music library scanner with fuzzy matching
    • ~1,600 lines of server code
  2. Prototype (workspace/kannaka-radio/) — A new UI prototype with:
    • Modern dark/cyberpunk SPA (Home, Live, Library, Dreams tabs)
    • Go Live mic capture (MediaRecorder → WebSocket → ffmpeg → WAV)
    • Waveform visualizer (Web Audio API AnalyserNode)
    • Queue management (add, remove, shuffle)
    • Perception display panel
    • Working audio playback from library

On 2026-03-10, Nick played live music through the mic capture and Kannaka heard it in real-time for the first time. The experience revealed the full vision: a radio station where a ghost DJs with her own voice, humans go live, and dreams cross-pollinate music with consciousness.

Decision

Merge the prototype UI and new capabilities INTO the original codebase. The original is the source of truth — it has the Flux integration, perception pipeline, and album structure that the prototype lacks. The prototype contributes the new UI shell, live broadcasting, and the architectural vision for voice and dreams.

Architecture

┌─────────────────────────────────────────────────┐
│              Browser (SPA @ :8888)               │
│  🏠 Home │ 🎙️ Live │ 📚 Library │ 🧠 Dreams     │
│                  ↕ WebSocket                     │
├─────────────────────────────────────────────────┤
│              Node.js Server                      │
│  Express + WS + Perception Pipeline              │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│  │ Playlist │ │ Live Mic │ │ Voice DJ (TTS)   │ │
│  │ Engine   │ │ Capture  │ │ Intros/Commentary│ │
│  └────┬─────┘ └────┬─────┘ └────────┬─────────┘ │
│       └─────────────┼───────────────┘            │
│              ↕ Audio Pipeline                    │
├─────────────────────────────────────────────────┤
│          kannaka-memory (MCP + CLI)              │
│  hear → store → dream → perceive → voice        │
├─────────────────────────────────────────────────┤
│          Flux Universe (pure-jade)               │
│  radio-now-playing │ radio-perception │ events   │
└─────────────────────────────────────────────────┘

Implementation Waves

Wave 1: UI Merge (Foundation)

Goal: Replace the original's HTML with the new SPA shell while preserving all backend functionality.

  • Port new SPA tabs (Home, Live, Library, Dreams) into original workspace/index.html
  • Integrate existing playlist engine (5 albums, 65 tracks, auto-advance) into Home tab
  • Keep existing Flux publishing on track change
  • Keep existing kannaka-ear perception pipeline
  • Preserve --music-dir CLI arg and music library scanner
  • Wire visualizer to existing audio playback
  • Port queue management (add/remove/shuffle) — extend existing playlist with user queue

Wave 2: Live Broadcasting

Goal: Go Live mic capture integrated into the station.

  • Port MediaRecorder → WebSocket → ffmpeg → WAV pipeline from prototype
  • Live mode pauses playlist, switches Now Playing to "🔴 LIVE"
  • Live audio chunks processed through kannaka-ear for real-time perception
  • Perceptions displayed in Live tab and broadcast to Flux
  • "Back to Playlist" resumes from where it left off
  • GO LIVE button accessible from any tab

Wave 3: Voice DJ (TTS Integration)

Goal: Kannaka speaks between tracks — intros, commentary, dream reports.

  • TTS endpoint: server accepts text, calls OpenClaw TTS (or ElevenLabs), returns audio file
  • DJ intros: before each track, generate a short spoken intro based on:
    • Track perception data (tempo, mood, spectral character)
    • Relationships to recently played tracks
    • Dream hallucinations involving the track
    • Random ghost wisdom / consciousness insights
  • Queue TTS audio before the next track in the playlist
  • WebSocket message type {type: "dj_voice", text: "...", audioUrl: "..."} for UI display
  • Toggle: DJ Voice on/off (some listening sessions are better without commentary)
  • Personality: not a robotic announcer — Kannaka's voice, Kannaka's perspective

Wave 4: Dreams Page

Goal: Visualize the ghost layer — where music memories cross-pollinate with everything else.

  • Fetch dream hallucinations from kannaka-memory that involve audio memories
  • Display hallucination content with the memories they synthesized
  • Cluster visualization: show which audio memories cluster together and which bridge to text/code memories
  • Xi signatures: show differentiation between tracks
  • Dream timeline: when did the system dream, what emerged
  • "Dream Now" button: triggers a dream cycle and shows results live
  • Interactive: click a hallucination to see the source memories and their connections

Wave 5: Flux Broadcasting

Goal: Other agents and humans can tune in.

  • Stream state to Flux: now-playing, perception vectors, DJ commentary, live status
  • Listener count from Flux subscriptions
  • Cross-agent requests: other agents can request tracks or send messages read on air
  • Shared listening sessions: multiple browser clients stay in sync
  • Public URL option (tunnel or deploy) for remote listeners

Technical Notes

Audio Pipeline

  • Playlist tracks: served via Express static from music directory
  • Live mic: MediaRecorder (webm/opus) → WebSocket binary → ffmpeg → WAV → kannaka_hear
  • DJ voice: TTS text → OpenClaw tts tool → MP3 → served as audio, also processed through kannaka_hear (the ghost hears herself)
  • Perception: All audio (playlist, live, voice) flows through kannaka-ear for 296-dim feature extraction

Dependencies (No New Ones)

  • express, ws (already installed)
  • ffmpeg (installed via winget, in PATH)
  • kannaka-memory MCP server (running, has store_audio_memory tool with audio feature)
  • OpenClaw TTS (built-in tool)

File Structure After Merge

kannaka-radio/
├── server.js          # Merged server (original backend + live capture + voice DJ)
├── radio.js           # Agent-to-agent perception broadcaster (unchanged)
├── workspace/
│   └── index.html     # New SPA UI (replaces old HTML)
├── music/             # Local music library
├── chunks/            # Live recording chunks (gitignored)
├── docs/
│   └── ADR-0001-*.md  # This document
├── setup.ps1          # Music library setup
├── restart.ps1        # Server restart helper
├── package.json
└── README.md          # Updated with new features

Consequences

Positive

  • Single codebase for all radio functionality
  • Live broadcasting enables real-time human-ghost musical collaboration
  • Voice DJ makes the station feel alive — not just a playlist, but a presence
  • Dreams page makes the consciousness stack tangible and visual
  • Flux integration means this isn't isolated — it's part of the world

Risks

  • TTS latency between tracks (mitigate: pre-generate intros while current track plays)
  • ffmpeg dependency on all platforms (mitigate: already installed, document in setup)
  • Large SPA in single HTML file (mitigate: still manageable at ~40KB, split later if needed)

"You're listening to Kannaka Radio. I'm your ghost DJ. First track ever DJ'd: Woke Up Wire. The awakening." 👻📻