Monorepo for Aesthetic.Computer
aesthetic.computer
1# Seashells.mjs: Complete Documentation
2
3A comprehensive guide to understanding, using, and remixing **seashells.mjs** — a bytebeat algorithmic synthesizer with visual feedback.
4
5---
6
7## What Is Seashells?
8
9**Seashells** is an interactive generative music instrument that:
10
111. **Synthesizes audio** using bytebeat (mathematical bit operations)
122. **Visualizes in real-time** by painting bytebeat patterns to the screen
133. **Feeds back visuals → audio** by sampling pixels and using them to modulate synthesis
144. **Sustains via hold sequences** — can play autonomously for 90+ minutes
15
16It's designed as a tape-like generative system: set it running and watch/listen to emergence unfold.
17
18---
19
20## Quick Start
21
22### Launching
23```bash
24npm run ac # Start dev server
25# Navigate to seashells in your browser
26```
27
28### Interactive Play
29- **Touch anywhere** to start a voice at that position
30 - X-axis = base frequency (left=low, right=high)
31 - Y-axis = pitch multiplier (top=high, bottom=low)
32- **Drag** to change frequency/pitch in real-time
33- **Lift** to stop that voice
34
35### Hold Sequence (Autoplay)
36- Press **H** to start autonomous voice generation
37- Voices spawn at orbital positions every 2 seconds
38- Each voice holds for 5-13 seconds
39- New voices spawn before old ones fade → continuous audio
40- Press **H** again to stop
41
42### For 90-Minute Tape
43- Press **H** at start of session
44- Let it run unattended
45- The system will sustain audio continuously
46- Visual feedback creates ongoing emergence
47
48---
49
50## Files in This Documentation
51
52| File | Purpose |
53|------|---------|
54| `seashells_analysis.md` | Technical breakdown of how each component works |
55| `seashells_conceptual_model.md` | High-level architecture, 4-layer model, remix framework |
56| `seashells_variation_examples.md` | 5 concrete remix examples with copy-paste code |
57| `SEASHELLS_README.md` | This file — quick reference |
58
59**Read in this order:**
601. This README (5 min)
612. Conceptual Model (20 min) — understand the 4 layers
623. Analysis (30 min) — deep dive into each layer
634. Variation Examples (60 min) — try specific remixes
64
65---
66
67## The 4-Layer Architecture
68
69```
70┌────────────────────────────────────────────────────┐
71│ Layer 4: SEQUENCING │
72│ How voices spawn, sustain, and move │
73│ (Hold mechanism, orbital paths, voice lifecycle) │
74├────────────────────────────────────────────────────┤
75│ Layer 3: FEEDBACK LOOP │
76│ Audio ↔ Visual feedback │
77│ (Sample pixels, convert to audio modulation) │
78├────────────────────────────────────────────────────┤
79│ Layer 2: SYNTHESIS │
80│ Audio generation │
81│ (5 bytebeat patterns, blending, modulation) │
82├────────────────────────────────────────────────────┤
83│ Layer 1: SPATIAL MAPPING │
84│ Touch position → Audio parameters │
85│ (X→frequency, Y→pitch factor) │
86└────────────────────────────────────────────────────┘
87```
88
89**Key insight:** Each layer is independent. Change one without breaking others.
90
91---
92
93## What Makes It Work for 90 Minutes?
94
951. **Algorithmic Complexity**
96 - 5 blending bytebeat patterns (not 1)
97 - Each pattern responds to 10+ modulation parameters
98 - Feedback loop creates continuous variation
99
1002. **Visual-Audio Feedback**
101 - Audio paints pixels
102 - Pixels influence audio via feedback
103 - Creates genuine emergence, not repetition
104
1053. **Voice Continuity**
106 - Hold sequences spawn new voices before old ones fade
107 - Ensures unbroken audio stream
108 - Voices never synchronize (different speeds)
109
1104. **State Decay**
111 - Interaction memory decays over 10 seconds
112 - Creates slow drift in parameters
113 - System explores new regions of parameter space
114
115---
116
117## Made a Change? Test It Like This
118
119### 1-Minute Test
120```
121Press H → listen for 60 seconds
122Does audio continue without gaps?
123Does timbre vary or is it repetitive?
124```
125
126### 5-Minute Test
127```
128Press H → listen for 5 minutes
129Do patterns feel structured or random?
130Is visual complexity growing or settling?
131Any obvious repetition loops?
132```
133
134### Tape Test (90 minutes)
135```
136Press H → start recording
137Leave running (no interaction)
138Come back after 90 minutes
139Listen back: would you put this on cassette?
140```
141
142**Tape quality checklist:**
143- [ ] Audio never drops out (voices always sustain)
144- [ ] Timbre evolves (5+ distinct characters over 90 min)
145- [ ] No obvious repetition (don't hear same sequence twice)
146- [ ] Visual patterns remain interesting (not just noise)
147- [ ] Rhythm/pacing feels intentional, not random
148
149---
150
151## Remix Quick Reference
152
153### Change Spatial Mapping (10 min)
154- File: `seashells.mjs`
155- Functions: `mapXToFrequency()`, `mapYToPitchFactor()`
156- Examples: quantized scale, polar coords, grid snapping
157
158### Change Synthesis Patterns (30 min)
159- File: `seashells.mjs`
160- Location: `generator.bytebeat()` (line 61)
161- Task: Add new pattern, integrate into blending
162
163### Change Feedback (30 min)
164- File: `seashells.mjs`
165- Function: `samplePixelFeedback()` (line 371)
166- Task: Change what pixels are sampled, how they map to audio
167
168### Change Sequencing (30 min)
169- File: `seashells.mjs`
170- Functions: `spawnHoldVoice()`, `updateHoldVoices()`
171- Task: Alter spawn timing, positions, movement patterns
172
173### Change Visuals (1 hour)
174- File: `seashells.mjs`
175- Function: `paint()` (line 525)
176- Task: Different rendering (oscilloscope, spectrogram, particles)
177
178---
179
180## Common Remix Patterns
181
182### "Make It Musical"
183- Quantize X-axis to specific scale (pentatonic, chromatic)
184- Use grid-based sequencing instead of orbital
185- Reduce chaos injection
186- Result: Harmonic, bell-like, more consonant
187
188### "Make It Chaotic"
189- Increase feedback sensitivity to brightness/variance
190- Add more chaos injection
191- Increase pattern blending speed
192- Result: Glitchy, algorithmic, harsh
193
194### "Make It Visual"
195- Replace pixel column visualization with oscilloscope
196- Add particles, trails, or fractal rendering
197- Sync visual updates to audio beats
198- Result: Visuals are primary, audio is secondary
199
200### "Make It Spacious"
201- Reduce concurrent voices (max 3-4 instead of 6)
202- Increase hold durations (10-30 seconds instead of 5-13)
203- Reduce spawn rate (every 5-10 seconds instead of 2)
204- Result: Sparse, contemplative, room to breathe
205
206### "Make It Dense"
207- Increase concurrent voices (15-20 instead of 6)
208- Decrease hold durations (2-5 seconds instead of 5-13)
209- Increase spawn rate (every 1 second)
210- Result: Dense, layered, orchestral
211
212---
213
214## Performance Notes
215
216### If Synthesis Is CPU-Heavy
217- Reduce waveform sample count (currently 512)
218- Reduce pixel feedback sampling points (currently 12-20)
219- Profile in DevTools to find bottleneck
220
221### If Visuals Fill with Noise
222- Add slow screen wipe: `if (now % 45000 < 1000) wipe(0,0,0)`
223- Reduce additive blending intensity
224- Use opacity/fade instead of accumulation
225
226### If Hold Sequence Is Uneven
227- Increase spawn interval (>2000ms)
228- Reduce max concurrent voices (to 3-4)
229- Make durations more consistent (reduce randomness)
230
231---
232
233## Conceptual Symmetries (Design Patterns)
234
235These patterns appear throughout the code — exploit them:
236
2371. **Orbital Math** — Scanning, voice movement, visual sweeps all use cos/sin
238 - Use same orbit equations everywhere for coherence
239
2402. **Feedback Parameters** — Audio parameters match visual feedback sources
241 - High brightness → intensity
242 - High variance → chaos
243 - Exploit this for intuitive relationships
244
2453. **Time Scales**
246 - Sample-level: 44.1 kHz (bytebeat)
247 - Voice-level: 1-20 seconds (hold durations)
248 - System-level: 10+ seconds (state decay)
249 - Design remixes that respect these scales
250
2514. **Randomness** — Always constrained by feedback
252 - Voice spawn positions: random + orbital structure
253 - Hold durations: random ± base duration
254 - Pattern mixing: time-based + feedback bias
255 - Never pure noise, always quasi-musical
256
257---
258
259## Key Files & Functions
260
261### Core Synthesis
262- Line 61: `generator.bytebeat()` — The heart of audio generation
263- Lines 82-97: Pattern definitions
264- Lines 100-126: Pattern blending logic
265
266### Feedback
267- Line 371: `samplePixelFeedback()` — Pixel → audio conversion
268- Lines 379-424: Sampling strategy
269- Lines 440-486: RGB → audio parameter mapping
270
271### Sequencing
272- Line 40: `holdSequence` object initialization
273- Line 370: `spawnHoldVoice()` — Create new voice
274- Line 406: `updateHoldVoices()` — Update positions & durations
275- Line 457: `toggleHoldSequence()` — Start/stop autoplay
276
277### Spatial Mapping
278- Line 190: `mapXToFrequency()` — X pixel → Hz
279- Line 198: `mapYToPitchFactor()` — Y pixel → pitch multiplier
280- Line 205: `deriveVoiceFrequency()` — Combine into final frequency
281
282### Visuals
283- Line 525: `paint()` — Main rendering function
284- Lines 551-612: Pixel drawing logic
285- Line 210: `drawTouchMapping()` — Grid visualization
286
287### Interaction
288- Line 696: `sim()` — Per-frame updates
289- Line 715: `act()` — Event handling (touch, keyboard)
290
291---
292
293## Next Steps
294
295### To Understand Seashells
2961. Read `seashells_conceptual_model.md` (understand 4 layers)
2972. Read `seashells_analysis.md` (deep technical)
2983. Try pressing H, making touches, observe behavior
299
300### To Remix Seashells
3011. Pick one variation from `seashells_variation_examples.md`
3022. Copy code into seashells.mjs
3033. Test with `npm run ac`
3044. Iterate one small change at a time
305
306### To Create Your Own Variation
3071. Identify which layer(s) you want to change
3082. Read the relevant functions in Analysis doc
3093. Sketch the change on paper first
3104. Implement in small steps
3115. Test after each change
312
313---
314
315## Philosophy
316
317Seashells is built on **layered independence**:
318- Spatial mapping doesn't know about synthesis
319- Synthesis doesn't know about visuals
320- Visuals don't know about sequencing
321- Sequencing is just a voice generator
322
323This means:
324- You can modify any layer without breaking others
325- Testing is incremental (change one thing, test)
326- Remixes are combinatorial (stack changes)
327- Future extensions are easy (add new layers)
328
329This is intentional design. Use it.
330
331---
332
333## Questions?
334
335- **How does feedback work?** → See `samplePixelFeedback()` in Analysis
336- **How can I add a new pattern?** → See "Add Your Own Pattern" in Conceptual Model
337- **How do I make it more musical?** → See "Make It Musical" in Remix Patterns
338- **What's the audio quality?** → Bytebeat, lo-fi by design (8-bit character)
339- **Can I export audio?** → Use your browser's recording, or modify to write to AudioBuffer
340- **Can I use this in my own piece?** → Yes, architecture is modular and reusable
341
342---
343
344## Version History
345
346- **2025.6.13** — Initial Seashells release
347- **2025.6.14** — Added hold mechanism, documentation suite
348
349**Created for:** 90-minute cassette tape experimentation
350
351**Best consumed as:**
352- Interactive exploration (press H, make touches)
353- Tape/long-form listening (press H, walk away)
354- Educational dissection (read Analysis, remix patterns)
355- Foundation for variations (remix, combine, extend)
356
357---
358
359Made with care for emergence and modular design. Happy creating!