coolsoup/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

CoolSoup is a React + TypeScript + Vite application that generates visual patterns and converts them to audio through spectral synthesis. The app features multiple image generators (Tixy expressions, geometric tiles, external APIs) and an advanced audio synthesis engine that treats images as spectrograms.

Development Commands

• pnpm dev - Start development server with hot reload
• pnpm build - Build for production (TypeScript compilation + Vite build)
• pnpm lint - Run ESLint on the codebase
• pnpm preview - Preview production build locally

Architecture Overview

Core Application Structure

• State Management: Uses Nanostores for reactive state with persistent atoms
• UI Layout: Two-panel design - main content area (generator + image grid) and collapsible audio panel
• Generator Pattern: Pluggable generator system where each generator implements a common interface

Main Store (src/stores/index.ts)

Central state management with these key atoms:

• appSettings - Generator selection, grid size, colors
• generatedImages - Array of generated images with metadata
• selectedImage - Current image for audio synthesis
• synthesisParams - Audio synthesis configuration
• panelOpen - Audio panel visibility

Generator System

Four built-in generators located in src/generators/:

• Tixy (tixy.ts) - Mathematical expressions using t,i,x,y variables
• Waveform (waveform.ts) - Procedural random waveforms with various interpolation curves
• Picsum (picsum.ts) - External random images API
• Art Institute (art-institute.ts) - Art Institute of Chicago API

Each generator returns GeneratedImage[] with:

• id - Unique identifier
• canvas - HTMLCanvasElement
• imageData - ImageData for synthesis
• generator - Generator type
• params - Generation parameters

Spectral Synthesis Engine (src/spectral-synthesis/)

Advanced image-to-audio synthesis library:

• Core Logic (core/synthesizer.ts) - Main ImageToAudioSynthesizer class
• Types (core/types.ts) - SynthesisParams and related interfaces
• Audio Export (audio/export.ts) - WAV file generation and download
• Utilities (core/utils.ts) - Helper functions for frequency mapping and peak detection

Key features:

• Mel-scale frequency mapping for perceptual accuracy
• Spectral peak detection to reduce noise
• Temporal smoothing for coherent audio trajectories
• Auto-detection of image type (spectrogram vs diagram)
• Configurable synthesis parameters (duration, frequency range, resolution)

Audio Export System (src/audio-export/)

Batch audio processing capabilities:

• Single image export with custom parameters
• Batch export of all generated images
• ZIP file generation for batch downloads
• Progress tracking for long operations

Key Implementation Details

Image Generation Flow

1. User selects generator and parameters in GeneratorSelector
2. App.tsx calls appropriate generator function
3. Generator returns array of GeneratedImage objects
4. Images displayed in ImageGrid component
5. User can click image to select for audio synthesis

Audio Synthesis Flow

1. User selects image from grid (sets selectedImage)
2. AudioPanel provides synthesis parameter controls
3. Synthesis triggered via spectral-synthesis library
4. Audio can be played directly or exported as WAV
5. Batch export processes all generated images

Component Architecture

• App.tsx - Main layout and generation orchestration
• GeneratorSelector - Generator picker with settings
• ImageGrid - Grid display of generated images
• AudioPanel - Audio synthesis controls and export
• AudioControls - Playback controls for generated audio

Generator Module Structure

Both tixy-generator and waveform-generator modules are designed as standalone packages:

Tixy Generator:

• README.md - Documentation and usage examples
• core/types.ts - Type definitions
• index.ts - Main exports
• Generator-specific files (evaluator, patterns, etc.)

Waveform Generator:

• README.md - Documentation and usage examples
• core/types.ts - Interfaces and configuration
• core/interpolation.ts - Curve interpolation functions (linear, exponential, logarithmic, cubic)
• core/generator.ts - Control point generation and randomness strategies
• renderer/canvas.ts - Canvas rendering with smooth anti-aliased curves
• index.ts - Main exports and convenience functions

Development Notes

• Uses Rolldown Vite for improved performance
• Tailwind CSS for styling (no rounded corners per user preference)
• ESLint configured for React + TypeScript
• All generators support time-based animation parameters
• Image synthesis supports real-time parameter adjustment