Practice Assistant (Smart Practice Plans)

Overview

The Practice Assistant is Practito's structured, goal-oriented practice system that guides students through step-by-step progressive learning with real-time metric tracking.

Key Features: - 🎯 Step-by-step practice plans with specific goals - 📊 Real-time metrics tracking (loops, time, tempo) - 🎓 Three difficulty levels (Beginner, Intermediate, Advanced) - 👨‍🏫 Teacher integration for assignments - 🔄 Auto-configures player settings per step - 💾 Progress saved automatically

Two Modes of Operation

1. Student Self-Directed Practice Plans

How Students Use It:

1. Activate: Click the Assistant button (robot icon 🤖) in practice player controls
2. Select Difficulty:
3. Beginner - Slower tempos (50-75%), smaller sections (4-8 measures), more repetitions (25-30 loops)
4. Intermediate - Moderate progression (60-90% tempo), balanced sections (8-16 measures), 15-25 loops
5. Advanced - Faster progression (75-100% tempo), larger sections (16+ measures), 10-20 loops
6. Practice: System generates 3-8 steps with specific goals
7. Track Progress: Real-time metrics update as you practice
8. Advance: Move to next step when ready (manual progression)

Practice Plan Structure:

Each step includes: - Name & Description - Clear objective (e.g., "Step 1: Learn the Notes - Measures 1-8") - Loop Range - Specific measures to practice (e.g., measures 1-16) - Tempo Target - BPM or % of original tempo (e.g., 50% → 75% → 100%) - Target Loops - Number of repetitions to complete (e.g., 20 loops) - Duration Goal - Suggested practice time (e.g., 10 minutes) - Metronome - Whether to use metronome for this step

UI Features: - Plan overview with all steps (✓ completed, ▶ current, ○ upcoming) - Progress bar showing overall completion percentage - Current step details with goals - Real-time metrics display: - Loops completed / Target - Time spent (stopwatch) - Highest tempo reached

Special Modes: - Learn the Notes - Focus on note reading before tempo - Resume Practice - Continue where you left off - Restart Plan - Begin from step 1 - Skip Assistant - Practice without plan for this session - Delete Plan - Remove plan permanently

2. Teacher-Created Assignment Practice Plans

How It Works:

When teachers create assignments with practice steps: 1. Student clicks "Practice" on assignment 2. Practice Assistant auto-loads (no button click needed) 3. Only teacher-selected steps display 4. Each step auto-configures player settings 5. Progress tracked and visible to teacher

Differences from Self-Directed:

Feature	Self-Directed	Assignment-Based
Activation	Manual (click button)	Auto-loads
Difficulty	Student chooses	Teacher sets
Steps	All from plan	Teacher selects specific
Delete Plan	Yes	No (teacher owns)
Progress Visibility	Student only	Student + Teacher

Teacher Benefits: - View completion rate per step - See average time/loops/tempo per step - Identify struggling students - Track which steps are most challenging - Provide targeted feedback

Implementation Details

Core Class: StepManager.js

Location: assets/js/practice-player/StepManager.js (2486 lines)

Constructor:

constructor(musicPlayer, musicPieceId, userId, assignmentId = null)

Key Methods: - initialize() - Loads plan, creates UI, applies settings - loadPracticePlanAndProgress() - Fetches or creates practice plan - promptForDifficulty() - Shows difficulty selection modal - createUI() - Generates practice interface modal - applyStepSettings() - Auto-configures tempo, loops, metronome - startSessionTracking() - Begins metric tracking - handleStepChange() - Updates UI when step changes

API Endpoints

Student Endpoints: - GET /music/api/practice-plan/{musicPieceId} - Fetch existing plan - POST /music/api/practice-plan/{musicPieceId} - Create new plan - PUT /music/api/practice-plan/{planId}/progress - Update progress - DELETE /music/api/practice-plan/{planId} - Delete plan

Assignment Step Tracking: - POST /student/assignment-step-progress/{progressId}/start - Begin step - POST /student/assignment-step-progress/{progressId}/add-time - Update time - POST /student/assignment-step-progress/{progressId}/complete - Mark complete

Database Entities

PracticePlan: - Belongs to user and music piece - Contains multiple PracticePlanSteps - Stores difficulty level

PracticePlanStep: - Defines step goals (loop range, tempo, loops, duration) - Contains step number, name, description - Metronome usage flag

Assignment: - ManyToMany relationship with PracticePlanStep - Teacher selects which steps to assign

AssignmentStepProgress: - Tracks student progress on each step - Records loops completed, time spent, tempo reached - Completion status and timestamps

Teacher Workflow: Creating Assignments with Steps

4-Step Process:

Step 1: Select Music Pieces

• Browse library and select pieces for assignment
• Can assign multiple pieces, each with own plan

Step 2: Configure Practice Plans

Generate New Plan: 1. Click "Generate New Plan" 2. Select difficulty (Beginner/Intermediate/Advanced) 3. Preview generated steps (3-8 steps)

Or Select Existing Plan: 1. Choose from dropdown of previously created plans 2. Reuse effective plans

Step 3: Select Practice Steps

• Review all steps from each plan
• Check boxes to include specific steps
• Strategic selection based on student level
• Each step card shows goals (tempo, loops, measures, duration)

Step 4: Assignment Details

• Set title, instructions, due date
• Select recipients (students or classes)
• Review summary and create

Student Best Practices

Self-Directed Practice: 1. Choose appropriate difficulty (don't overestimate) 2. Complete each step's goals before advancing 3. Focus on all three metrics: loops AND time AND tempo 4. Use "Learn the Notes" mode for unfamiliar pieces 5. Don't skip steps - progressive learning works

Assignment Practice: 1. Review all steps before starting 2. Understand teacher's expectations 3. Complete steps in order 4. Track progress regularly 5. Ask teacher if goals unclear

Teacher Best Practices

Plan Design: - Break pieces into logical musical sections - Start at 50-60% tempo for beginners - Increase tempo in 10-15% increments - Set achievable loop targets (15-30 reps) - Enable metronome for rhythm-focused steps

Assignment Strategy: - First assignment: 2-3 simple steps to familiarize - Regular assignments: 3-5 steps - Advanced assignments: 5-8 steps - Set realistic due dates - Monitor mid-assignment progress

Communication: - Explain system to students first - Reference specific steps in feedback - Encourage following order - Ask which steps were helpful

Technical Architecture

Service: PracticePlanGenerator

Location: src/Service/PracticePlanGenerator.php

Methods:

// Generate plan based on difficulty
public function generatePlan(
    MusicPiece $piece, 
    User $user, 
    string $difficulty = 'intermediate'
): PracticePlan

// Custom plan with specific parameters
public function generateCustomPlan(
    MusicPiece $piece,
    int $chunkSize,      // Measures per step
    int $startTempo,     // Starting BPM
    User $user
): PracticePlan

Templates: - getBeginnerTemplate() - Slow, small chunks, many reps - getIntermediateTemplate() - Balanced progression - getAdvancedTemplate() - Fast progression, larger chunks

Auto-Initialization Logic

For Personal Practice Plans:

// Check if user has existing plan
const response = await fetch(`/music/api/practice-plan/${musicPieceId}`);
if (response.ok && data.plan && data.progress) {
    // Auto-initialize to show resume prompt
    await initializeStepManager();
}

For Assignment Practice:

{% if assignmentId and hasAssignmentSteps %}
    console.log('[StepManager] Assignment practice detected - auto-initializing');
    await initializeStepManager();
{% endif %}

UI Components

Modal Structure:

┌─────────────────────────────────────────┐
│  Practice Plan Overview                 │
│  ├─ Progress Bar (X% complete)         │
│  ├─ All Steps List                     │
│  │  ├─ ✓ Completed steps               │
│  │  ├─ ▶ Current step (highlighted)    │
│  │  └─ ○ Upcoming steps                │
│  └─ Jump-to-step buttons               │
├─────────────────────────────────────────┤
│  Current Step Details                   │
│  ├─ Step Name & Description            │
│  ├─ Practice Goals                     │
│  └─ Real-Time Metrics                  │
├─────────────────────────────────────────┤
│  Actions                                │
│  ├─ [Disable for This Session]         │
│  └─ [Delete Plan]                      │
└─────────────────────────────────────────┘

Testing

Test Practice Assistant: 1. Login as student 2. Open any piece in practice player 3. Click Assistant button (robot icon) 4. Select difficulty and generate plan 5. Verify step details display 6. Practice and check metrics update 7. Advance to next step

Test Assignment Integration: 1. Login as teacher 2. Create assignment with practice steps 3. Assign to test student 4. Login as that student 5. Click "Practice" on assignment 6. Verify Assistant auto-loads 7. Complete a step and check teacher view

Documentation Links

• Comprehensive Guide: PRACTICE_ASSISTANT_GUIDE.md
• User Manual Section: PRACTITO_USER_MANUAL.md
• Assignment System: ASSIGNMENT_SYSTEM.md
• Teacher Assignment Docs: teachers/assignments.md
• Student Practice Docs: students/practice-player.md

NOT AI-Based

Important: The Practice Assistant is NOT powered by AI or machine learning. It uses: - ✅ Rule-based progressive learning templates - ✅ Pre-defined difficulty algorithms - ✅ Structured step generation based on piece attributes - ✅ Goal-based metric tracking

Does NOT include: - ❌ Automatic difficult section detection - ❌ AI-powered practice suggestions - ❌ Machine learning performance analysis - ❌ Automated break or posture reminders

The system provides proven pedagogical structure through programmatic step generation and real-time progress tracking.