# KaspaBeat

> Live generative music from the Kaspa blockchain DAG. Kaspa confirms 10-15 blocks per second; the app streams them live and turns them into musical notes at a tempo the listener chooses, one a second by default.

## What is it?
A free, browser-only audio-visual experience that converts real-time Kaspa blockchain data into generative music and rich canvas visuals. No login, no downloads, no ads.

## Core idea
Blocks steer a song rather than each becoming an isolated note. A musical clock owns the timing; the chain chooses between musical options — which chord progression, which motif, how dense the drums are, when the fill lands, when the drop happens — and each block also fires one accent snapped to the grid, so you can still point at the block you are hearing. Transaction volume and DAG width become energy; orphan blocks queue drum fills; a mega block pulls the chorus forward; blue score milestones change key. The result is finished songs of three or four minutes, each announced with the range of blocks it was composed from.

## Genres
Thirty-four, grouped: Hip Hop, Trap, Drill, Rap, R&B; House, Deep House, Tech House, Techno, Trance, Synthwave; UK Garage, Drum & Bass, Dubstep, Breakbeat; Reggae, Dub, Dancehall, Reggaeton, Salsa, Cumbia, Bossa Nova, Afrobeats, Amapiano; Soul, Funk, Disco, Jazz, Blues, Gospel; Pop, Rock, Country, Metal.

Each has its own tempo, drum kit, groove, chord family, bass idiom and mix. Switching genre keeps the song — same key, same progression, same motif, same place in the form — and changes only the arrangement.

## Scales available
Pentatonic, Dorian, Minor, Major, Blues, Lydian, Whole Tone, Maqam Rast (Arabic), Hirajoshi (Japanese), Klezmer, Aeolian, Chromatic — user-selectable or auto per mode.

## Visualizations
- DAG Graph: live node-link graph of blocks and their parents
- Waterfall: scrolling spectrogram-style block rain
- Mandala: radial symmetry, each block adds a petal
- Piano Roll: notes scroll left, color-coded by instrument

## Technical stack
- Vanilla JavaScript, Web Audio API, Canvas 2D API
- No frameworks, no libraries, no bundler runtime in prod
- PWA — installable; offline shell after install; music continues via cached-block loop if API drops after a live session
- Service Worker with versioned cache-busting
- i18n: English + Hebrew (RTL), lazy-loaded
- Data: REST polling from api.kaspa.org — tip discovery once a second (cache-busted), then only the blocks that will actually be played, released in blue-score order at the chosen tempo

## User features
Session archive (up to 10), achievement badges, keyboard jam mode (keys 1–8), daily challenges, custom instrument samples (drag-drop WAV/MP3, IndexedDB-persisted; cleared with Privacy → Clear Stored Data), favorite block moments, shareable note-replay links (v2 includes absolute semitones; plays during demo without waiting for live blocks), canvas video recording (WebM), theme palettes (5), scale explorer, BPS sparkline, community wall (local mock only — not a global feed), Kaspa radio widget.

## Session lifecycle
Browser Back from a live session returns to the splash (history always pushes when entering `#live`). Teardown stops polling, demo, note-replay timers, recordings, address watch refresh, and waveform; samples restore again on the next START.

## Ambient mode
Append ?ambient=1 to the URL for full-screen no-UI mode — ideal for background display on a second screen or stream overlay.

## Embeddable widget
/widget.html — 220×80px iframe, polls api.kaspa.org, shows live BPS pulse, tip note, blue score, and offline badge.

## Data sources
- api.kaspa.org (public REST, no auth required)
- All processing is client-side; no personal data is collected or stored

## License
MIT