PsychOS — Spotify Listening Observatory

An emotionally intelligent analytics platform built from Spotify Extended Streaming History JSON exports. Dark, cinematic UI with probabilistic behavioral narratives — not pseudoscience.

Note: The deployed demo uses synthetic sample data (public/data/demo-analytics.json). The author developed and runs PsychOS locally with their own real export via pnpm preprocess. Visitors can upload their JSON files in the app (Settings) — processing stays in the browser.

Stack

• Next.js (App Router) + TypeScript
• pnpm for package management
• Tailwind CSS + Radix primitives + Framer Motion
• Recharts + D3 for visualizations
• Zustand for client state
• Analytics engine: shared src/lib/preprocess/ (Node + browser)

Quick start

cd psych-os
pnpm install
pnpm generate-demo   # synthetic demo bundle for deploy / first run
pnpm dev

Open http://localhost:3000.

Use your own export (browser)

1. Request Extended streaming history from Spotify (Account → Privacy → Download your data).
2. Open Settings → Your listening data → Choose JSON files.
3. Select Streaming_History_Audio_*.json file(s). Analysis runs locally; nothing is uploaded to a server.

Use your own export (CLI, local dev)

SPOTIFY_DATA_DIR="D:/path/to/exports" pnpm preprocess

Writes public/data/analytics.json (gitignored). For local-only use; the public site uses demo data + browser upload.

Project structure

psych-os/
├── scripts/preprocess.ts           # CLI wrapper
├── scripts/generate-demo.ts        # Synthetic demo data
├── public/data/demo-analytics.json # Committed demo bundle
├── src/lib/preprocess/             # Shared analytics engine
├── src/components/settings/      # JSON upload UI
└── src/app/                        # Routes

Pages

Route	Description
/	Landing
/dashboard	Overview stats & charts
/psychology	Behavioral scores & identity eras
/evolution	Taste drift & similarity
/artists	Network graph & rankings
/habits	Sessions, skips, platforms
/audio	Audio aura (proxy / Spotify API)
/wrapped	Yearly story slides + PNG/PDF export
/explorer	Paginated track table
/settings	Upload export · data source

Deploy to Vercel

1. Push to GitHub — safe to use a public repo (no personal analytics.json committed).
2. Import on Vercel — Next.js, root ., build pnpm build.
3. Regenerate demo data after engine changes: pnpm generate-demo and commit demo-analytics.json.
4. Spotify API env vars are optional and usually unnecessary.

Optional Spotify API

Copy .env.example → .env.local. Most new developer apps cannot access Audio Features (Spotify policy, Nov 2024). The dashboard does not require API keys.

Analytical ethics

• Observed vs interpretation labels on insights
• Confidence levels (low / medium / high)
• No clinical or diagnostic claims

Scripts

Command	Action
pnpm dev	Development server
pnpm generate-demo	Build synthetic demo-analytics.json
pnpm preprocess	Build analytics.json from local export (gitignored)
pnpm build	Production build
pnpm start	Serve production

---

Built for portfolio-quality deployment. Your archive, interpreted with restraint.