From 6daacb6bb53ef199c99c0ef4163f5d211898e34f Mon Sep 17 00:00:00 2001
From: b1rdmania <102524336+b1rdmania@users.noreply.github.com>
Date: Thu, 18 Dec 2025 14:43:20 +0000
Subject: [PATCH] Update README for GitHub and add project About details.

---
 README.md | 88 +++++++++++++++++++++++++++++++++++--------------------
 1 file changed, 57 insertions(+), 31 deletions(-)

diff --git a/README.md b/README.md
index e09f0a5..8016c19 100644
--- a/README.md
+++ b/README.md
@@ -1,59 +1,85 @@
 # MOTIF
 
-**Procedural Music Synthesis from MIDI Structure**
+Search real MIDI, play it in-browser, then generate a Motif variation.
 
-Motif extracts structural information from existing music and re-instantiates it as original, real-time audio using the Web Audio API. Music as executable structure, not static audio.
+MOTIF is a small experiment in **music-as-code**: treat MIDI as structural data, not audio. It pulls MIDI patterns from the web, plays the original performance, then generates a “similar-but-different” procedural version using Web Audio.
 
-## Quick Start
+## About
+
+- **What it does**: Search songs → pick a result → play the original MIDI → generate and play a Motif variant.
+- **Why it’s fun**: It’s like “hear a MIDI version of anything”, then remix it into something new.
+- **Status**: Working locally end-to-end. Hosted frontend exists, backend hosting may be separate depending on deployment.
+
+## Live demo
+
+- **Frontend**: `https://motif-46uf00ypw-boom-test-c54cde04.vercel.app`
+
+Note: if the backend isn’t deployed/configured for the demo environment, search/fetch won’t work from the hosted URL. Run locally for the full experience.
+
+## Features
+
+- **MIDI search** (currently BitMidi; additional sources optional)
+- **MIDI fetch + validation + caching** via an Express backend
+- **Browser playback** with multiple engines:
+  - Tone.js sampled piano
+  - Soundfont piano
+  - Custom WebAudio synth preview
+- **Motif generation**: role-based synthesis (bass / drone / ostinato / texture / accents) from parsed MIDI structure
+
+## Quick start (local)
 
 ```bash
-# Install dependencies for both frontend and backend
+# Install frontend deps
 npm install
+
+# Install backend deps
 cd server && npm install && cd ..
 
-# Run both frontend and backend
-npm run dev:all
+# Run backend (http://localhost:3001)
+npm run dev:backend
 
-# Or run separately:
-npm run dev:backend  # Backend on :3001
-npm run dev          # Frontend on :3000
+# Run frontend (Vite prints the URL, typically http://localhost:5173)
+npm run dev
 ```
 
-## Architecture
+## How it works (pipeline)
 
-- **Frontend**: TypeScript + Vite + Web Audio API
-- **Backend**: Express API for MIDI search and fetching
-- **MIDI Sources**: BitMidi, Dongrays (with synthetic fallback)
-- **Synthesis**: Pure procedural Web Audio (no samples)
+1. User searches for a song
+2. Backend searches MIDI sources and returns ranked candidates
+3. Backend fetches the selected `.mid`, validates it, and caches it
+4. Frontend parses MIDI into normalized note events
+5. User can:
+   - **Play original MIDI** (soundfont/sampler playback), or
+   - **Generate Motif** (procedural Web Audio synthesis derived from structure)
 
-## How it works
+## Backend API
 
-1. Search for MIDI by song name
-2. Extract structural features (tempo, density, roles)
-3. Map to synthesis layers (bass, drone, ostinato, texture)
-4. Generate original audio with similar "feel"
+- `GET /api/midi/search?q=song`
+- `GET /api/midi/fetch?u=url` (URL must be encoded)
+- `GET /api/midi/parse?u=url`
+- `GET /health`
 
-## Project Structure
+## Project structure
 
 ```
 src/
 ├── core/           # MotifEngine, RoleMapper
-├── synthesis/      # Web Audio synthesis engine  
-├── midi/           # MIDI parsing and processing
+├── midi/           # Parsing + feature extraction
 ├── services/       # Backend API client
+├── synthesis/      # Players + procedural synthesis engine
 └── types/          # TypeScript interfaces
 
 server/
 ├── src/
-│   ├── adapters/   # MIDI search adapters
-│   ├── services/   # Search and fetch logic
-│   └── utils/      # Scoring and validation
-└── cache/          # MIDI file cache
+│   ├── adapters/   # MIDI search adapters (sources)
+│   ├── services/   # Search/fetch/parse
+│   └── utils/      # Scoring, validation, MIDI helpers
+└── cache/          # Downloaded MIDI cache (local dev)
 ```
 
-## API
+## Roadmap
 
-- `GET /api/midi/search?q=song` - Search for MIDI files
-- `GET /api/midi/fetch?u=url` - Fetch and validate MIDI
-
-Built as a technical experiment in procedural audio and Web Audio capabilities.
\ No newline at end of file
+- **More sources**: add/replace flaky scrapers with more reliable sources
+- **Better matching**: smarter ranking + metadata validation
+- **Motif controls**: “more ominous”, “more dancey”, “more ambient”, etc.
+- **Deployment**: host backend and wire frontend to it via env config
\ No newline at end of file