Skip to content

README.md

Latest commit

 

History

History
103 lines (73 loc) · 2.7 KB

README.md

File metadata and controls

103 lines (73 loc) · 2.7 KB
Raw

SoundCluster

License: MIT

SoundCluster

SoundCluster maps songs into a 3D emotional space. The app searches track metadata through iTunes, fetches lyrics through LRCLIB when available, analyzes the song with Gemini, stores reusable analysis/share data in MongoDB Atlas, and renders the resulting 5D emotion vector with React Three Fiber.

Stack

  • Frontend: React, TypeScript, Vite, React Three Fiber, Three.js, CSS Modules
  • Backend: Express, TypeScript, Server-Sent Events
  • LLM: Google @google/genai
  • External APIs: iTunes Search API, LRCLIB API
  • Storage: MongoDB Atlas
  • Deployment: Vercel frontend, Render backend, MongoDB Atlas database
  • Tests: TypeScript build + node:test

Deployment

Current Features

  • iTunes track search by title and optional artist
  • LRCLIB lyrics lookup with fallback to title/artist-only analysis
  • Gemini 5D emotion analysis
  • MongoDB-backed analysis cache
  • SSE progress events for analysis state
  • R3F 3D music space rendering
  • Axis on/off projection controls for five emotion dimensions
  • Hover metadata popup with album image, title, artist, and emotion values
  • Selected track HUD with emotion detail panel and remove action
  • Nearest/farthest relation calculation and visual connection lines
  • nanoid share URLs backed by MongoDB snapshot storage
  • Duplicate share snapshot detection through stable snapshot hashes

Run

Frontend:

corepack pnpm dev

Backend:

corepack pnpm run server:build
corepack pnpm run server:start

Default URLs:

Frontend: http://localhost:5173
Backend:  http://127.0.0.1:3001
Health:   http://127.0.0.1:3001/api/health

Environment

Required backend environment variables:

GEMINI_API_KEY=
MONGODB_URI=
MONGODB_DB_NAME=

The frontend should call the deployed Render backend in production and the local backend during local development.

Validation

corepack pnpm run test
corepack pnpm run lint
corepack pnpm run server:build
corepack pnpm run build

Documents

Branch Policy

  • main: integrated stable branch
  • dev: active integration branch
  • feature/*: task or milestone branches

Implementation work is tracked through GitHub issues and mirrored in docs/checklist.md.

License

MIT