← Back to Technology

Web Project Handoff

AMF Web Project Handoff

The Adaptive Musician's Framework — Product, Content, and Experience Overview

Version 1.1 | Incorporates audit refinements from Layer 12

Product Vision

AMF (The Adaptive Musician's Framework) is a long-term musicianship system built around one central goal: helping a learner become an adaptive musical contributor rather than a player who memorizes songs, chords, scales, or isolated techniques.

The web project should house AMF as a living learning system. The experience should make the framework easy to understand, revisit, practice, and eventually personalize. The existing document library is the source content. The web project turns that source content into guided learning paths, interactive worksheets, system maps, practice builders, and progress trackers.

Primary goal: Help the learner practice with structure while preserving creative freedom.

Secondary goal: Turn abstract musicianship ideas into usable systems with repeatable SOPs.

Experience goal: Make the learner feel like they are developing an internal band that can respond intelligently in any musical setting.

Content goal: Organize deep manuals, printable cheat sheets, worksheets, exercises, listening prompts, and curriculum into a coherent navigable library.

The Internal Band Metaphor

The unifying metaphor for AMF is an internal band. Each subsystem represents a musical function the learner trains. The learner is not memorizing unrelated systems — they are training an internal ensemble that can rehearse, listen, adapt, and perform.

Genre Labs are the gigs. Practice sessions are rehearsal. Piano and guitar are instrument interfaces into the same framework.

The web project should consistently reinforce this metaphor — not cartoonishly, but as the organizing logic for navigation, content presentation, and practice structure.

AMF System Architecture

AMF — The Adaptive Musician's Framework
  -> PDC: Perceive, Diagnose, Contribute — real-time contribution decision loop
  -> CAS/ARC: Composition Architecture System — whole-piece structure loop
  -> TPS: Triad Placement System — harmonic compression system
  -> Rhythm Cell System: groove compression system
  -> Melodic Shape System (SHAPE): phrase compression system
  -> Blues Root: emotional and rhythmic foundation
  -> RXP: Rhythm Expansion — groove feel and long-time awareness
  -> Genre Labs: practical musical environments for contextual development
  -> Practice Engine: slow work, visualization, spaced repetition, feedback
  -> Interfaces: piano, guitar, voice/body, ear, listening, worksheets, future apps

AMF Subsystem Summaries

PDC — Perceive, Diagnose, Contribute The core musical decision loop. PDC trains the learner to hear the environment, identify what is strong, missing, excessive, or needed, and contribute with restraint and intention. PDC is the bandleader of the internal band.

TPS — Triad Placement System The harmonic compression system. Reduces harmony to a few triad shapes placed intelligently over roots, then shaped through inversion, spacing, register, and purpose. Supports accompaniment, chord melody, fills, improvisation, and composition.

Rhythm Cell System The groove compression system. Reduces rhythm to 2- and 3-based cells, then expands through grouping, placement, accent, silence, and interaction. Supports pocket, comping, rhythmic identity, and ensemble communication.

SHAPE — Melodic Shape System The phrase compression system. Reduces melody and improvisation to seed ideas, targets, contour, pulse, evolution, and space. Prevents scale wandering and supports melodic storytelling.

CAS — Composition Architecture System The whole-piece structure system. Core loop: ARC — Aim, Route, Complete. Teaches composition, arrangement, solo structure, accompaniment architecture, emotional arcs, form, repetition, variation, contrast, and completion.

Blues Root The emotional and rhythmic foundation. Grounds the whole system in feel, call-and-response, tension/release, timing, phrasing, note weight, groove, and emotional honesty.

RXP — Rhythm Expansion Groove feel and long-time awareness. Develops the capacity to feel rhythmic structure across 2-bar, 4-bar, and 12-bar time spans — the whole-form rhythmic breath that underlies all blues-rooted music.

Genre Labs Genre environments used to train specific AMF instincts. Jazz trains interaction and harmonic adaptability; funk trains pocket; gospel trains emotional escalation; folk trains storytelling; ambient/film trains texture; rock trains energy; neo-soul trains color and groove atmosphere.

The 11 Content Object Types

AMF content is structured as reusable objects rather than one long course. This makes the system easier to turn into web pages, cards, tools, and application modules.

1. System

A complete AMF subsystem document. Covers the full depth of one Internal Band member: purpose, mechanics, musical behaviors, levels of mastery, exercises, and cross-system connections.

Examples: PDC Master Manual, TPS Full System Document, CAS/ARC Architecture Guide.

Web presentation: Full manual page + quick-reference card + practice entry point.

2. Concept

A single musical idea or principle. Smaller than a System — covers one idea that may belong to multiple systems.

Examples: "What is a triad?", "What is a rhythm cell?", "What does call-and-response mean?", "What is guide-tone voice leading?"

Web presentation: Single-page card with definition, musical example (notation or audio), and practice connection.

3. SOP — Standard Operating Procedure

A step-by-step protocol for a practice or performance behavior. Answers "how do I do this?" with a numbered checklist.

Examples: "SOP: How to map a chorus with ARC before playing it," "SOP: How to use PDC during a jam session," "SOP: How to diagnose a practice recording."

Web presentation: Printable checklist format, step-by-step numbered procedure.

4. Exercise

A specific drillable practice activity. Has a clear setup, a method, and a success standard.

Examples: "Muted Pulse Drill," "Triad Arpeggio on Three Strings," "027 Color Object Placement," "Call-and-Response Fill."

Web presentation: Exercise card with instructions, time estimate, difficulty level, associated AMF systems, and definition of done.

5. Practice Loop

A repeatable practice session structure combining multiple exercises into a time-boxed session.

Examples: "10-Minute Month 1 Guitar Session," "30-Minute Full AMF Daily Loop," "5-Minute Visualization + Form Pass."

Web presentation: Session template with total time, session segments, and checklist.

6. Worksheet

A fillable practice planning document. Captures decisions, observations, and progress.

Examples: "Weekly Sprint Log," "CAS-ARC Pre-Performance Map," "PDC Listening Analysis Sheet," "Month 1 Definitions of Done Checklist."

Web presentation: Interactive fillable form or printable PDF.

7. Definition of Done

A mastery checkpoint for a specific skill or phase. States the observable behaviors that indicate a skill is ready to build on.

Examples: "Month 1 Guitar Definition of Done," "TPS Level 3 Definition," "Semester 1 Completion Criteria."

Web presentation: Checkbox list with pass/fail criteria per item.

8. Listening Assignment

A specific track or album with guided listening focus. Includes context, what to listen for, and AMF application questions.

Examples: "Louis Armstrong — West End Blues (PDC Listening)," "Blue Monk — Rhythm Placement Study," "The Thrill Is Gone — Arrangement and Restraint."

Web presentation: Listening card with track info, context notes, three to five listening prompts, and one AMF application question.

9. Genre Lab

A complete genre environment document. Covers the genre's historical origin, the specific AMF instincts it develops, recommended listening, and practice protocols.

Examples: Jazz Lab, Funk Lab, Gospel Lab, Folk Lab, Ambient/Film Lab.

Web presentation: Full genre lab page with subsections for each component.

10. Repertoire Item

An anchor song or study piece. Includes historical context, what it trains, listening prompts, and AMF lab tasks. Does not include copyrighted transcriptions or lyrics.

Examples: "Sweet Home Chicago Study," "Blue Monk Study," "The Thrill Is Gone Study."

Web presentation: Repertoire page with historical card, listening prompts, and AMF practice tasks.

11. Reflection Log

A self-assessment recording and written evaluation. Structured around specific diagnostic questions rather than open-ended journaling.

Examples: Weekly sprint recording + self-evaluation questions, Month-end integration recording + written reflection, Capstone recording + full written diagnosis.

Web presentation: Entry form with recording date, recording link/upload, and structured evaluation questions.

Content Model Relationships

System
  -> contains: Concepts, Exercises, SOPs
  -> relates to: other Systems (cross-references)
  -> appears in: Genre Labs, Repertoire Items, Practice Loops

Concept
  -> belongs to: one or more Systems
  -> used in: Exercises, SOPs, Worksheets

Exercise
  -> uses: Concepts, Systems
  -> appears in: Practice Loops, Genre Labs

Practice Loop
  -> contains: Exercises, Concepts
  -> aligns to: Semester, Month, Week level

Repertoire Item
  -> references: Listening Assignments
  -> generates: Practice Loops, Exercises, Worksheets
  -> trains: specific Systems

Genre Lab
  -> references: Repertoire Items, Listening Assignments
  -> contains: Practice Loops, Exercises
  -> develops: specific Systems

Definition of Done
  -> verifies: Exercises, Practice Loops, Semester phases
  -> advances: Semester tracking

Reflection Log
  -> captures: Progress Tracker data
  -> connects to: Definitions of Done, Semester checkpoints

Primary User Flows

Flow 1: New Learner Onboarding

  1. Land on AMF homepage — see the internal band metaphor explained in plain terms
  2. Take a brief orientation: current instrument, musical goal, available time per day
  3. Receive a recommended starting point: PDC Quick Start + Blues Root listening
  4. Begin a 7-day starter rehearsal path (auto-generated from orientation answers)
  5. Access quick-reference cards for core vocabulary (PDC, TPS, Rhythm Cells)
  6. Complete first recording deliverable at end of Day 7

Flow 2: Daily Practice Session

  1. Open dashboard — see today's AMF practice plan from current curriculum position
  2. Choose available time: 5, 10, 15, or 30 minutes
  3. Select instrument focus: guitar, piano, or visualization only
  4. Receive shared core task plus instrument-specific task
  5. If task requires generated materials, click Generate Practice Loop
  6. App produces materials (MIDI backing track, worksheet, listening reference)
  7. Practice, optionally record externally, log reflection
  8. Mark definitions of done and advance tracking

Flow 3: Progress Review

  1. Open Progress Tracker — see current skill levels across all AMF systems
  2. Select a skill that needs review — see its last recorded level, recording date, and evaluation notes
  3. Access the recommended review exercise for that skill
  4. Complete a brief reassessment practice session
  5. Update the skill level based on evidence, not mood
  6. View month-end checkpoint status — are the Definitions of Done met?

Feature Priority List

Features are ordered from highest educational ROI to lowest, informed by audit findings.

Priority 1 — Interactive real-time tools (highest ROI)

  • Rhythm Grid Editor (Tone.js, client-side, <10ms latency)
  • TPS Placement Explorer (piano keyboard + chord labels)
  • 12-Bar Generator (adaptive backing tracks with AMF parameters)

Priority 2 — Adaptive feedback and tracking

  • Progress Tracker (skill levels, Definitions of Done, weekly sprint logs)
  • Weekly recording deliverable with structured self-evaluation questions
  • Adaptive difficulty in the MIDI generator (tempo, density, complexity adjust to mastery level)

Priority 3 — Content library

  • Curriculum browser (Semester 1 full curriculum, week-by-week)
  • System library (PDC, TPS, Rhythm Cells, etc.)
  • Listening assignment pages with guided prompts

Priority 4 — Generation and export

  • MIDI file download (generated backing tracks)
  • Worksheet PDF export
  • PCS explorer (interactive set visualization)

Priority 5 — Song study

  • Moises-Assisted Song Workspace (revised: self-hosted Demucs + Basic Pitch pipeline)
  • Anchor song study pages (Sweet Home Chicago, Blue Monk, The Thrill Is Gone)

Technology Stack (Corrected — Incorporates Layer 12 Audit)

The original BRD assumed server-side FluidSynth for all audio including interactive tools. This is architecturally wrong for real-time interactive use (200–500ms latency per click). The corrected architecture separates real-time interactive audio from non-real-time export audio:

Frontend:

  • Next.js (React framework)
  • Tone.js (client-side audio — all interactive tools, <10ms latency)
  • Tonal.js (music theory computations: chord analysis, scale construction, interval calculations)
  • VexFlow (notation snippets, rhythm examples)
  • alphaTab (guitar tablature display + built-in AlphaSynth WebAssembly playback — evaluating as guitar track primary renderer)

Backend:

  • FastAPI (Python)
  • pretty_midi (MIDI generation)
  • mido (MIDI I/O)
  • music21 (offline/pre-computed use only — NOT in real-time request paths)
  • PostgreSQL (user data, progress tracking, generated content cache)

Audio architecture:

  • Interactive real-time audio: Tone.js in browser (Rhythm Grid, TPS Explorer, PCS Explorer, preview playback)
  • Non-real-time audio export: FluidSynth server-side (generates downloadable MP3/WAV backing tracks from MIDI)
  • SoundFont decision: SoundFont quality is a first-class content decision, not a default. GeneralUser GS is adequate but not blues-authentic. Blues-appropriate piano and guitar samples must be evaluated before launch.

Song study pipeline (replaces Moises API dependency):

  • Demucs v4 (Meta, self-hosted, async job) — stem separation
  • Basic Pitch (Spotify, open source) — audio-to-MIDI transcription
  • Moises remains available as a manual companion (user opens Moises separately and imports results)

Key architectural note on music21: music21 is a powerful music theory library but is computationally expensive — deepcopy operations are slow and the object model makes it unsuitable for per-request API use. It must be confined to offline analysis jobs and pre-computed content generation. It must not appear in the hot path of any real-time API endpoint.

The Moises Workspace Concept and Revised Architecture

The original BRD described Moises API integration for stem separation and chord detection. Layer 12 audit identified two concerns: (1) Moises chord detection accuracy degrades on complex jazz harmonies (extended chords, alterations, slash chords), and (2) API dependency creates ongoing cost and a single point of failure.

Revised architecture:

The Song Workspace remains as a product feature. Its backend pipeline changes:

  1. User uploads audio file to the Song Workspace
  2. Demucs v4 runs as an async job (60–90 seconds on CPU for a 3-minute track) — produces stems: vocal, drums, bass, other
  3. Basic Pitch runs on the "other" stem — produces an audio-to-MIDI transcription for the melodic/harmonic content
  4. User reviews and annotates the results in the Song Workspace UI (chord symbols, section markers, tempo, key)
  5. App generates AMF practice tasks from the structured song data — PDC, RXP, TPS, PCS, guitar, and piano prompts

What Moises becomes: A manual companion. If the user already uses Moises, they can export or copy their session data into the Song Workspace fields. Moises API integration is not a build requirement.

Why this architecture is better: The app owns the pipeline. It can improve Demucs processing, improve Basic Pitch post-processing, and improve the AMF task generation without depending on an external API's accuracy, pricing, or availability.

Design and Tone Guidelines

  • Make the framework feel serious but not academic
  • Use the internal band metaphor consistently — not cartoonishly
  • Prefer visual maps, cards, checklists, and examples over dense prose
  • Every page should answer: What is this? Why does it matter? How do I use it? How do I practice it?
  • Use clear levels: overview → deep dive → practice → worksheet → definition of done
  • Do not show all possibilities at once — reveal depth progressively
  • Preserve core AMF identity: adaptive, rhythm-first, accompaniment-aware, blues-rooted, genre-lab-enabled

Recommended MVP Scope

MVP 1 — AMF Library: A clean web home for the master blueprint and system manuals. Browsable, organized, searchable.

MVP 2 — Quick Reference Hub: Mobile/print-friendly cheat sheets for all core systems (PDC, TPS, Rhythm Cells, SHAPE, CAS-ARC, Blues Root).

MVP 3 — Practice Session Templates: Static guided practice flows for 5, 10, 15, and 30 minutes, per instrument.

MVP 4 — Curriculum Browser: Semester 1 full curriculum — week-by-week, with deliverables and self-evaluation questions.

MVP 5 — Interactive MIDI Tools: Rhythm Grid Editor and TPS Explorer using Tone.js (client-side audio). This is where the product becomes more than a document library.

MVP 6 — Progress Tracker: Skill tracking table, weekly sprint logs, month-end checkpoints, capstone evidence.

Post-MVP — Song Workspace: Demucs + Basic Pitch pipeline for anchor song study.

Risks and Guardrails

Copyright: Do not store or distribute copyrighted audio publicly. For personal study, allow user-managed song notes and links, but keep generated AMF exercises original. Avoid generating full copyrighted charts or lyrics in exported materials.

Scope creep: The highest-ROI features are interactive real-time tools and adaptive difficulty. Do not build passive content libraries at the expense of the interactive core.

Gamification: Avoid points, badges, and leaderboards not tied to musical quality — engagement boost is short-lived and does not transfer to skill gains.

Over-building for multi-user SaaS: Personal-use MVP first. Do not prematurely build multi-tenant auth, complex CI/CD, or cloud infrastructure before the core loop works.

Audio quality: SoundFont selection is a first-class content decision. Launching with a poor-quality SoundFont creates a bad first impression of the tool. Select before launch.