# Kaspa Music

> 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
Block hash bytes determine pitch, timbre, velocity, panning, and visual color. The statistical distribution of notes over time auto-detects a musical key. DAG orphan events trigger percussion fills. Blue score milestones trigger scale transitions.

## Music modes
- Jazz: extended chords, Dorian/Phrygian scales, swing rhythm
- Ambient: slow attack, reverb-heavy, pentatonic, sparse
- Techno: driving 4/4, Aeolian, punchy kick on every block
- Classical: harpsichord + strings, major scale, arpeggios
- Chiptune: square/triangle waves, fast tempo, minor pentatonic

## 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