# 🎵 SongSense

AI-powered music analysis with spectrograms, lyrics transcription, and intelligent reviews.

## Features

- **Upload or paste links** — YouTube, SoundCloud, Spotify, Dropbox, or local files
- **Interactive visualizer** — Play a game while your music is being analyzed
- **AI-powered reviews** — Production analysis + lyric breakdown powered by Claude
- **Spectral analysis** — Visual spectrograms showing frequency content
- **Beautiful UI** — Dark mode, glassmorphism, smooth animations

## Tech Stack

- **Frontend:** Next.js 15, React, TypeScript, Tailwind CSS, Framer Motion
- **Backend:** Next.js API routes, Node.js
- **Processing:** ffmpeg, yt-dlp, OpenAI Whisper, songsee, Claude API
- **Deployment:** Railway (recommended) or any Node.js host

## Local Development

```bash
npm install
npm run dev
```

Open http://localhost:3000

## Environment Variables

Required:
- `OPENAI_API_KEY` — For Whisper transcription
- `ANTHROPIC_API_KEY` — For AI review generation

## Deploy to Railway

1. Push to GitHub
2. Connect Railway to your repo
3. Add environment variables in Railway dashboard
4. Railway will auto-detect Next.js and deploy

System dependencies (ffmpeg, yt-dlp) are handled via `nixpacks.toml`.

**Note:** songsee must be installed manually or via a build script (not in nixpkgs).

## Architecture

```
src/
├── app/                    # Next.js pages and API routes
│   ├── page.tsx           # Landing page
│   ├── analyze/[jobId]/   # Game/visualizer page
│   ├── review/[jobId]/    # Review results page
│   └── api/               # Backend endpoints
├── components/            # React components
│   ├── game/             # Audio visualizer
│   ├── review/           # Review display components
│   ├── upload/           # File/URL input
│   └── ui/               # Reusable UI components
└── lib/                  # Backend logic
    ├── processing/       # Audio processing pipeline
    ├── store.ts          # In-memory job store
    └── types.ts          # Shared TypeScript types
```

## How It Works

1. User uploads audio or pastes URL
2. Backend downloads and converts to MP3
3. Whisper API transcribes lyrics
4. songsee generates spectrograms
5. Claude analyzes spectrograms + lyrics
6. User gets beautiful review with ratings

Built by agent teams in ~20 minutes. Reviewed and deployed by Buba 🤖