# GeneratedLofi Product Spec

## Thesis

GeneratedLofi should not behave like a generic music player with an AI badge on top. It should behave like an autonomous focus room: one coherent seed that determines soundtrack, ambience, scene, timer defaults, and the social tone of the space.

The product promise is simple: open the site, press one button, and immediately feel held by the environment. The user should not have to prompt, curate, or troubleshoot. AI should stay backstage.

## Product Principles

### 1. Rooms, not tracks

Users remember moods better than songs. `Rainy Library` is easier to return to than `track_1847.mp3`. Each room needs a strong identity, a visual palette, a tempo range, ambient layers, and a social rule set.

### 2. Prompting is backstage

Free-form prompting is useful for experimentation, but it is the wrong default for a focus product. The front door should offer room presets, session lengths, and light controls like `same vibe, new track`.

### 3. Calm first, depth second

The first session should start in under five seconds. Advanced controls can exist deeper in the product: room history, saved seeds, ambient stems, group rooms, or custom schedules.

### 4. Social should respect concentration

Persistent global chat will erode the focus product. Presence should begin as quiet signals: listener counts, room occupancy, shared timers, and optional break-only conversation.

## Experience Flow

1. Visitor lands inside a live room with motion already running.
2. Primary CTA starts a 25-minute focus session.
3. The system queues a coherent soundtrack, starts ambience, and locks the user into a low-friction mode.
4. During focus, the interface stays minimal: timer, track state, room switcher, and one quick refresh action.
5. At break, the room brightens slightly, a soft chime fires, and optional social space appears.

## Recommended V1 Architecture

### Client

- Next.js or another React shell for the production app
- Web Audio API for crossfades, stem layering, ambience control, and fallback procedural beds
- Canvas or WebGL scene layer for subtle motion and audio-reactive lighting
- Local persistence for room choice, timer preference, and session intent

### Backend

- Asset metadata in Postgres or Supabase
- Audio, stills, and video loops stored in R2 or S3 behind a CDN
- Queue orchestration service that returns:
  - current room seed
  - current track
  - next two compatible tracks
  - ambient layer mix
  - scene parameters

### Generation Pipeline

- Music generation:
  - Pre-generate 2 to 5 minute tracks or stems in batches
  - Tag each asset with BPM, key, energy, texture, palette, and rights metadata
  - Use a rules engine to queue compatible tracks and hide seams with crossfades
- Ambience:
  - Generate or source looping layers like rain, vinyl, cafe murmur, train hum, HVAC, birds
  - Treat these as composable stems rather than fixed mixed audio
- Visuals:
  - Pre-generate scene stills or short loops
  - Add client-side motion, grain, lighting, weather, and parallax to keep them alive

## Why Hybrid Beats Pure Live Generation

Pure per-listener generation sounds attractive but introduces the wrong constraints:

- higher cost per session
- cold-start latency
- harder moderation and quality control
- licensing and provenance complexity
- more ways for the stream to fail

The better first version is hybrid:

- pre-generated music or stems for reliability
- programmatic ambience for continuity
- programmatic motion for aliveness
- AI generation pipelines running behind the scenes to continuously refresh the catalog

## Core Objects

### Room

- `id`
- `name`
- `tagline`
- `palette`
- `bpmRange`
- `energyLevel`
- `ambientLayers`
- `scenePrompt`
- `chatPolicy`
- `defaultFocusMinutes`

### Asset

- `id`
- `type` (`track`, `stem`, `still`, `loop`, `ambient`)
- `originModel`
- `duration`
- `rightsTier`
- `tags`
- `seed`

### Session

- `roomId`
- `startedAt`
- `focusLength`
- `breakLength`
- `intent`
- `queue`
- `presenceMode`

## V1 Scope

- 4 signature rooms with strong identities
- focus timer with 25, 50, and 90 minute presets
- coherent track queue with crossfades
- ambient layer chips with simple toggles
- subtle presence indicators
- room save/history

## V2 Scope

- group rooms with shared pomodoro cycles
- break-only chat and reactions
- custom room blends
- daily focus streaks and session recap
- voice or text-generated room requests routed through moderation and curation

## UX Notes

- The homepage and the app should feel like the same world.
- Avoid dashboards. Default to a cinematic scene with restrained chrome.
- The best quick action is `same vibe, new track`, not an open prompt field.
- Session completion should feel rewarding but quiet.
- Every room should look and sound good enough to become someone's default work habitat.