Rhythm analysis engine and rehearsal instrument.
Upload a track. Get back meter inference, subdivision graphs, groove profiling, drum hit classification, click tracks, and MIDI — with continuous confidence scoring across every dimension.
┌──────────────┐ ┌──────────────┐ ┌────────────┐
│ Next.js 14 │────▶│ FastAPI │────▶│ PostgreSQL │
│ port 3000 │ │ port 8000 │ │ port 5432 │
└──────────────┘ └──────┬───────┘ └────────────┘
│
┌──────▼──────┐
│ Redis │
│ port 6379 │
└──────┬──────┘
│
┌─────────▼─────────┐
│ Celery Worker │
│ │
│ Engine v2 │
│ Pipeline │
└─────────┬─────────┘
│
┌─────────▼─────────┐
│ File Storage │
│ local / S3 │
└───────────────────┘
| Layer | Technology |
|---|---|
| Frontend | Next.js 14, TypeScript, Tailwind CSS |
| API | FastAPI, SQLAlchemy (async), Pydantic |
| Task queue | Celery + Redis |
| Engine | Python, librosa, madmom, Demucs v4 |
| Database | PostgreSQL 16 |
| Audio extraction | FFmpeg |
Pure-function pipeline with zero database or Celery dependencies. The worker calls in and handles persistence.
Upload
│
├─ 1. Separation ──── FFmpeg extract → Demucs v4 stem isolation
│
├─ 2. Signal ──────── Onset detection → sample-level transient refinement
│
├─ 3. Temporal ────── Beat tracking → downbeats → tempo octave correction → sections
│
├─ 3b. Metrical ───── Multi-resolution periodicity → hypothesis generation →
│ Inference scoring → temporal tracking → modulation detection
│
├─ 3c. Subdivision ── Persistent subdivision graph → multi-layer rhythm grid →
│ Graph phase relations between layers
│
├─ 4. Groove ──────── Swing detection → microtiming → accent profiling
│
├─ 5. Hits ────────── Multi-feature drum hit classification (k/s/h/t/c)
│
├─ 6. Export ──────── MIDI (multi-track) → click track → waveform peaks
│
└─ Confidence ─────── Metric-vector scoring (6 dimensions + overall)
| Stage | Module | Description |
|---|---|---|
| 1 | stages/separation.py |
FFmpeg audio extraction, Demucs v4 stem isolation, spectral SNR |
| 2 | stages/signal.py |
Frame-level onset detection + sample-level transient refinement |
| 3 | stages/temporal.py |
Beat tracking, downbeat detection, tempo octave correction, sections |
| 3b | stages/metrical_inference.py |
Periodicity → hypothesis generation → scoring → tracking |
| 3c | stages/subdivision_graph.py |
Persistent multi-layer subdivision graph with phase relations |
| 4 | stages/groove.py |
Swing, microtiming, accent profiling, groove classification |
| 5 | stages/hits.py |
Drum hit classification (kick/snare/hat/tom/cymbal) |
| 6 | stages/export.py |
MIDI export, click track generation, waveform peaks |
| — | confidence.py |
Continuous [0,1] metric-vector confidence scoring |
| — | versioning.py |
Engine version tracking, artifact caching, stale-stage invalidation |
~2400 lines. Handles complex rhythmic structures: math rock, polymeter, tempo changes, metric modulations.
Onset Impulse Train
│
▼
Multi-Resolution Periodicity Analysis
(autocorrelation + spectral, sliding windows, 4 resolutions)
│
▼
Hypothesis Generator
(period × beat_count × grouping → MeterHypothesis candidates)
│
▼
Hypothesis Scorer
(accent alignment, IOI consistency, prediction error,
structural repetition, harmonic penalty, bar-level accent
periodicity, downbeat-anchored meter scoring)
│
▼
Hypothesis Tracker
(EMA smoothing, hierarchical resolution, dominant tracking,
modulation detection, ambiguity flagging, polyrhythm buffer)
│
▼
InferenceResult
├── window_inferences[]
├── detected_modulations[]
├── persistent_polyrhythms[]
└── global_dominant
PersistentSubdivisionGraphBuilder — windowed analysis of onset data against the beat grid. Detects simultaneous subdivision ratios (2, 3, 5, 7, etc.), tracks layer persistence across time, and computes pairwise phase relationships between layers.
Output: RhythmGraph with SubdivisionLayer[] + PhaseRelation[].
Continuous [0,1] metric-vector. Geometric mean ensures a single weak dimension drags overall score.
| Dimension | Measures |
|---|---|
tempo_stability_score |
Tempo coefficient of variation |
downbeat_alignment_score |
Downbeat proximity to beat grid |
meter_consistency_score |
Meter consistency across sections |
section_contrast_score |
Feature contrast at boundaries |
groove_consistency_score |
Groove pattern consistency |
hit_classification_score |
Hit classification confidence |
overall_confidence_score |
Weighted geometric mean |
Next.js 14 (App Router), TypeScript, Tailwind CSS. Three routes:
| Route | Component | Description |
|---|---|---|
/ |
page.tsx |
Upload console with rhythm scope visualization |
/projects |
projects/page.tsx |
Project list |
/projects/[id] |
projects/[id]/page.tsx |
Analysis dashboard |
Key components:
| Component | Description |
|---|---|
AudioEngine.tsx |
Multi-stem Web Audio API mixer (mute/solo/volume per stem) |
WaveformDisplay.tsx |
Canvas waveform renderer |
ArrangementMap.tsx |
Section arrangement view |
TimelinePanel.tsx |
Timeline visualization |
RhythmPreviewHero.tsx |
Analytical subdivision scope (landing page) |
SubdivisionGraphPanel.tsx |
Subdivision graph debug panel |
RhythmDebugPanel.tsx |
Metrical inference debug view |
ProcessingView.tsx |
Processing status display |
ConfidenceBadge.tsx |
Confidence level indicator |
SessionGrid/
├── apps/
│ ├── api/
│ │ ├── main.py # API routes
│ │ ├── config.py # Settings
│ │ ├── models.py # SQLAlchemy models
│ │ ├── schemas.py # Pydantic schemas
│ │ ├── database.py # DB sessions
│ │ ├── engine/
│ │ │ ├── __init__.py # ENGINE_VERSION
│ │ │ ├── pipeline.py # Pipeline orchestrator
│ │ │ ├── confidence.py # Metric-vector scoring
│ │ │ ├── versioning.py # Version tracking + caching
│ │ │ ├── stages/
│ │ │ │ ├── separation.py # FFmpeg + Demucs
│ │ │ │ ├── signal.py # Onset detection
│ │ │ │ ├── temporal.py # Beats, downbeats, sections
│ │ │ │ ├── metrical_inference.py # Periodicity → hypotheses
│ │ │ │ ├── subdivision_graph.py # Multi-layer rhythm graph
│ │ │ │ ├── groove.py # Swing, microtiming
│ │ │ │ ├── hits.py # Drum hit classification
│ │ │ │ └── export.py # MIDI, click, waveforms
│ │ │ └── evaluation/
│ │ │ ├── ground_truth.py # Ground-truth data model
│ │ │ ├── transcript_parser.py # JSON loading + validation
│ │ │ ├── metrics.py # Metric computation
│ │ │ └── evaluator.py # Evaluation pipeline
│ │ ├── workers/
│ │ │ ├── celery_app.py # Celery config
│ │ │ └── tasks.py # Pipeline task + persistence
│ │ ├── alembic/ # Migrations
│ │ ├── Dockerfile
│ │ └── requirements.txt
│ │
│ └── web/
│ ├── app/
│ │ ├── page.tsx # Upload console
│ │ ├── layout.tsx # Root layout
│ │ ├── globals.css # Styles
│ │ └── projects/
│ │ ├── page.tsx # Project list
│ │ └── [id]/page.tsx # Analysis dashboard
│ ├── components/
│ │ ├── analysis/
│ │ │ ├── ArrangementMap.tsx
│ │ │ ├── ExportPanel.tsx
│ │ │ ├── PracticeDeck.tsx
│ │ │ ├── ProcessingView.tsx
│ │ │ ├── ProjectSidebar.tsx
│ │ │ ├── RhythmDebugPanel.tsx
│ │ │ ├── RhythmPreviewHero.tsx
│ │ │ ├── SubdivisionGraphPanel.tsx
│ │ │ └── TimelinePanel.tsx
│ │ ├── player/
│ │ │ ├── AudioEngine.tsx
│ │ │ └── WaveformDisplay.tsx
│ │ └── ui/
│ │ └── ConfidenceBadge.tsx
│ ├── lib/
│ │ ├── api.ts # API client
│ │ └── types.ts # TypeScript models
│ ├── Dockerfile
│ └── package.json
│
├── docs/
│ ├── PRD.md
│ ├── ARCHITECTURE.md
│ └── VALIDATION.md
│
├── storage/
├── docker-compose.yml
└── .gitignore
git clone https://github.com/acLebert/SessionGrid.git
cd SessionGrid
docker compose up --build| Service | Port |
|---|---|
| web | 3000 |
| api | 8000 |
| worker | — |
| postgres | 5432 |
| redis | 6379 |
Frontend: http://localhost:3000 API docs: http://localhost:8000/docs
Backend:
cd apps/api
python -m venv .venv
.venv/Scripts/activate
pip install -r requirements.txt
uvicorn main:app --reload --port 8000
# separate terminal:
celery -A workers.celery_app worker --loglevel=infoFrontend:
cd apps/web
npm install
npm run dev| Method | Endpoint | Description |
|---|---|---|
GET |
/api/health |
Health check |
GET |
/api/projects |
List projects |
POST |
/api/projects |
Create + upload |
GET |
/api/projects/:id |
Project details |
GET |
/api/projects/:id/status |
Poll status |
POST |
/api/projects/:id/analyze |
Trigger analysis |
GET |
/api/projects/:id/audio |
Stream audio |
GET |
/api/projects/:id/stems/:type |
Download stem |
GET |
/api/projects/:id/click |
Download click |
GET |
/api/projects/:id/waveform |
Waveform data |
GET |
/api/projects/:id/midi |
Download MIDI |
POST |
/api/projects/:id/midi/quantize |
Re-quantize MIDI |
GET |
/api/projects/:id/drum-hits |
Drum hits |
GET |
/api/projects/:id/groove |
Groove profile |
GET |
/api/projects/:id/confidence |
Confidence vector |
GET |
/api/projects/:id/rhythm-debug |
Metrical inference data |
GET |
/api/projects/:id/subdivision-debug |
Subdivision graph data |
PATCH |
/api/projects/:id/sections/:sid |
Edit section |
GET |
/api/projects/:id/export/json |
Full analysis JSON |
DELETE |
/api/projects/:id |
Delete project |
Synthetic test pipeline for metrical inference. No audio required.
| Module | Purpose |
|---|---|
ground_truth.py |
Immutable ground-truth dataclasses |
transcript_parser.py |
JSON loading + schema validation |
metrics.py |
Metric computation (meter accuracy, modulation P/R, polyrhythm recall) |
evaluator.py |
Pipeline + 5 synthetic test scenarios |
Metrics: meter accuracy, grouping accuracy, modulation precision/recall/timing, polyrhythm recall, ambiguity alignment, confidence calibration.
- Engine version semver tracked per run
- Stage-level sub-versioning — only stale stages re-run
- Intermediate artifacts cached as
.npz - Input hash + engine version + model weights + seeds → deterministic output
- Drums-focused analysis pipeline
- Click track generation
- Section detection with confidence
- Engine v2 staged pipeline
- Multi-resolution periodicity detection
- Metrical inference (hypothesis generation, scoring, tracking)
- Hierarchical meter resolution + modulation persistence
- Bar-level accent periodicity scoring
- Downbeat-anchored meter scoring
- Persistent subdivision graph builder
- Metric modulation and polyrhythm detection
- Drum hit classification
- Groove profiling (swing, microtiming, accents)
- MIDI export with quantization control
- Continuous confidence vector
- Multi-stem Web Audio API mixer
- Evaluation framework with synthetic tests
- Engine versioning and artifact caching
- Subdivision graph debug UI
- Metrical inference debug panel
- Speed adjustment for practice
- Count-in before loop playback
- Bass/guitar stem analysis
- Multi-instrument arrangement maps
- Manual section boundary editing
- User accounts & project history
Private — All rights reserved.