Framework
Technology
Interactive tools that make AMF concepts tangible and playable.
AMF Technology: Overview
The AMF framework is built in documents — field manuals, practice guides, subsystem blueprints. That's enough to understand it, but it's not enough to practice with it. Understanding that a rhythm cell can be placed on beat two is different from placing it, hearing what it does, and hearing what changes when you shift it to the and-of-two. The technology exists to close that gap. It makes the abstract interactive.
This section describes the tools being built to support that goal, the design principles behind them, and where to find the full specifications.
The Five Interactive Tools
Each tool targets a specific AMF subsystem. Each one gives you something you can click, hear, and think about — not just read about.
Rhythm Grid Editor Build and hear Rhythm Cell patterns in a visual grid interface. You place a cell, you hear it loop, you move it, you hear what shifts. Develops the Rhythm Cell System skill of intentional cell placement — learning where a groove atom lands and why it changes the pocket.
TPS Placement Explorer Click a bass note and select a triad shape; the tool voices it and plays it. You hear the harmonic color — not a description of the color, the color itself. Develops TPS ear training: connecting the visual shape and position to the sound it produces over a specific root.
PCS Set Explorer Explore trichords (three-note pitch-class sets) played over different bass notes. The same set over a different root sounds like a different harmonic environment. Develops the PCS skill of hearing set identity as distinct from chord function — the same object, different context.
12-Bar Generator Generates adaptive backing tracks matched to your current mastery level for the 12-bar blues. Early levels use simpler harmonic motion and slower tempos; later levels introduce substitutions, rhythmic complexity, and genre variation. Develops integration: PDC decision-making in a real musical loop, with the backing track calibrated to stretch but not overwhelm.
Song Workspace Upload a recording, separate it into stems (vocals, bass, drums, other), and receive a MIDI transcription of the harmonic and melodic content. Develops real-song application: connecting AMF vocabulary to music you already know and care about.
The Key Design Principle
Every generated practice environment has an AMF learning question attached to it. The technology is not just "make it sound good" — it's "make you think about what you're hearing."
Here's what that looks like in practice: when the 12-Bar Generator produces a backing track, it doesn't just play. It surfaces a question like "The I chord just moved to the IV — did you hear the harmonic weight shift? What did your ear want to do?" The track is the environment; the question activates PDC. You're not passively looping — you're being asked to perceive, diagnose, and decide. Generated content without that question attached is engagement, not education.
Why Client-Side Audio Matters
The interactive tools use in-browser audio rather than server-generated audio because the learning depends on immediacy. When you click a rhythm cell or a triad shape, you hear it in under 10 milliseconds — the connection between the gesture and the sound is direct enough to feel causal. If the app had to send a request to a server and wait for audio to come back, that half-second gap breaks the loop: your ear has already moved on, and the moment of musical understanding is gone. For playback and loops, latency is a minor inconvenience. For ear training, it's fatal.
For the Developer
The full technical specification is in midi-lab-brd.md. The key architectural decisions are worth knowing upfront: Tone.js handles all interactive real-time audio in the browser — it's the engine behind every click-and-hear interaction. FastAPI serves as the backend for MIDI generation, user data, and API endpoints. PostgreSQL handles progress tracking and mastery-level state. FluidSynth runs server-side for rendered audio export only — it is never used for real-time playback. For the Song Workspace pipeline, Demucs handles stem separation and Basic Pitch handles MIDI transcription; these replace Moises, which introduced a third-party API dependency for a core feature. Everything that needs to respond in real time stays in the browser; everything that can be async stays on the server.
What's in This Section
Two documents live here.
web-project-handoff.md covers the product vision, the content model, the user experience goals, and the user flows. Start here if you're a product person, a designer, or someone who needs to understand what the app is trying to do before looking at specifications.
midi-lab-brd.md is the full Business Requirements Document: tool-by-tool functional specs, data structures, the mastery-level model, and the sprint plan. Start here if you're a developer who needs the ground truth on what gets built and how it fits together.
Current Status
These are design documents, not a shipped product. The files in this section define what gets built. Implementation begins from this foundation — the specifications are complete enough to start, and detailed enough to stay aligned with the AMF framework's educational goals as development proceeds.