Parametric MIDI Sequencer Web Prototype

About

MIDI Progression Editor is a parametric MIDI sequencer for exploring and editing chord progressions. It combines an interactive React/TypeScript web interface with an ASP.NET Core Web API backend, enabling musicians to:

• Visualize chord shapes on an interactive chromatic circle
• Build chord progressions with a dedicated sidebar (up to 8 chords, session-only)
• Explore triads and seventh chords across all root notes and qualities
• Animate smooth transitions between chord shapes
• Display scale degrees and diatonic transparency on the circle
• Choose from 8 scale modes: Major, Natural Minor, Harmonic Minor, Melodic Minor, Dorian, Phrygian, Lydian, and Mixolydian
• Identify voice-leading paths between consecutive chords
• Color-coded chord quality system (major, minor, diminished, augmented, dominant 7th, etc.)
• Inspect individual tones: view note name, chord role, interval from root, and frequency
• Switch between Info mode (click a note to inspect it) and Select mode (click notes to build a custom selection)
• Toggle dark/light theme with persistent preference (stored in localStorage)
• Play back chords with in-browser audio
• Export chord progressions as standard MIDI files (.mid) with configurable BPM and beats-per-chord
• Generate scales from any root note via the backend API

Prerequisites

• Node.js 18 or higher (for frontend)
• .NET 10 SDK (for backend)
• npm (comes with Node.js)

Quick Start

Option 1: Automated (Windows)

./run-dev.bat

This script orchestrates everything:

• Kills any existing processes on ports
• Starts backend on http://localhost:5110
• Starts frontend on http://localhost:5173
• Opens both in separate terminal windows

Option 2: Manual Setup

Terminal 1 Backend

cd server/ParametricMusic.Api
dotnet restore  # First time only
dotnet run

• API listens on: http://localhost:5110
• Swagger UI: http://localhost:5110/swagger
• Health check: GET http://localhost:5110/health

Terminal 2 Frontend

cd client
npm install     # First time only
npm run dev

• App: http://localhost:5173

Environment Variables

Frontend

Create client/.env.local to override defaults:

VITE_API_BASE_URL=http://localhost:5110

Default: http://localhost:5110 (if not set)

See client/.env.example for all available variables.

API Client Type Generation

When you modify backend API endpoints, regenerate the TypeScript types and client functions:

cd client
npm run generate:api

This fetches the OpenAPI spec from your running backend and regenerates src/api/generated/index.ts with complete type-safe client functions.

Requirements:

• Backend must be running on port 5110
• Connected to localhost network

When to regenerate:

• After changing controller endpoints
• After modifying DTOs or response types
• After adding/removing API parameters
• After adding new controllers

Usage:

import { client } from '@/api/client';

// Fully typed, all operations auto-generated from spec
const result = await client.post('/Scale/from-root', {
  query: { note: 'C' },
  body: { scaleType: 'major' }
});

Testing

Backend Tests

cd server/ParametricMusic.Tests
dotnet test

Runs xUnit test suite covering business logic and HTTP controller contracts.

Frontend Tests

cd client
npm test

Runs Vitest in single-pass mode. Currently covers MIDI file construction utilities.

Lint & Code Quality

Frontend

cd client
npm run lint

ESLint enforces zero-warnings (strict mode). All TypeScript files must pass.

Backend

C# code follows:

• Nullable reference types enabled
• Implicit usings (no using statements at top)
• RESTful conventions

Project Structure

High-Level

midi-progression-editor/
 client/              # React + TypeScript + Vite (frontend)
    src/
       api/         # API client & generated types
       app/         # Application root
          components/     # AppHeader (toggles, scale selector, theme)
          providers/      # ThemeContext, ThemeProvider, useTheme, EnharmonicContext, EnharmonicProvider, useEnharmonic
          routes/         # Client-side routing (placeholder)
          store/          # Global state management (placeholder)
       features/    # Feature modules
          audio/              # In-browser chord audio playback
          chord/              # Core chord data, types & utilities
          chord-animation/    # Animated chord shape transitions
          chord-geometry/     # Polygon vertex calculations
          chord-inspection/   # Tone detail inspection panel (ToneInfoPanel)
          chord-intervals/    # Interval pattern visualisation
          chord-morphing/     # Smooth polygon morphing hooks
          chromatic-circle/   # Main 12-note circle visualisation
          color-language/     # Quality-based color system
          current-chord/      # Current-chord info panel
          midi-export/        # MIDI file export (BPM, beats/chord)
          progression-sidebar/ # Chord progression sidebar (max 8 chords)
          scale/              # Scale generation & display (8 modes)
          voice-leading/      # Voice-leading path utilities
       shared/      # Shared components, hooks, types & utilities
          types/CursorMode.ts # 'info' | 'select' cursor modes
       App.tsx
    .env.example     # Environment variable template
    package.json

 server/              # ASP.NET Core .NET 10 (backend)
     ParametricMusic.Api/
         Controllers/     # HealthController, ChordController, ScaleController, ProgressionController
         Models/          # DTOs and enums
         Services/        # ChordGenerator, ScaleGenerator, ProgressionAnalyzer, QuartalChordGenerator
         Program.cs
         ParametricMusic.Api.csproj

For detailed architecture, see ARCHITECTURE.md.

Build

Frontend

cd client
npm run build
# Output: client/dist/ (ready for deployment)

Backend

cd server/ParametricMusic.Api
dotnet build
# Output: bin/Debug/net10.0/

For production:

dotnet publish -c Release -o ./publish

Troubleshooting

Port Already In Use

# Windows
netstat -ano | findstr :5110
taskkill /PID <PID> /F

# Mac/Linux
lsof -i :5110
kill -9 <PID>

Swagger Returns 404

• Check backend is running on port 5110: http://localhost:5110/swagger
• Verify Program.cs has AddSwaggerGen() and Swagger middleware configured

Generated Types Out of Sync

# Regenerate from running backend
cd client
npm run generate:api

Technologies

• Frontend: React 19, TypeScript 5.9, Vite 7, ESLint 9
• Backend: ASP.NET Core .NET 10, Swashbuckle 10.1.4, xUnit 2.9
• API: OpenAPI/Swagger specification with code generation
• Build: npm + dotnet CLI