Initial commit: EEG Motor Imagery Music Composer

- Gradio-based web application for EEG motor imagery music composition
- Real-time EEG signal processing and classification
- Interactive music building with 5 movement types (left/right hand, left/right leg, tongue)
- DJ effects phase with audio processing
- File saving currently disabled for testing
- Includes pre-trained shallow neural network model
- Audio state management to prevent Gradio component restarts

.gitattributes

@@ -0,0 +1,3 @@
+data/*.mat filter=lfs diff=lfs merge=lfs -text
+sounds/*.wav filter=lfs diff=lfs merge=lfs -text
+model.pth filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,59 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual Environment
+.venv/
+venv/
+ENV/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Project specific
+*.wav
+*.mp3
+*.pth
+mixed_composition_*.wav
+*_fx_*.wav
+app_old.py
+app_new.py
+test_mixed.wav
+silent.wav
+
+# Data files
+data/
+*.mat

README.md

@@ -0,0 +1,78 @@
+# 🧠 EEG Motor Imagery Music Composer
+
+A sophisticated machine learning application that transforms brain signals into music compositions using motor imagery classification. This system uses a trained ShallowFBCSPNet model to classify different motor imagery tasks from EEG data and creates layered musical compositions based on the classification results.
+
+## 🎯 Features
+
+- **Real-time EEG Classification**: Uses ShallowFBCSPNet architecture for motor imagery classification
+- **Music Composition**: Automatically creates layered music compositions from classification results
+- **Interactive Gradio Interface**: User-friendly web interface for real-time interaction
+- **Six Motor Imagery Classes**: Left/right hand, left/right leg, tongue, and neutral states
+- **Sound Mapping**: Each motor imagery class is mapped to different musical instruments
+- **Composition Management**: Save, clear, and manage your musical creations
+
+## 🏗️ Architecture
+
+### Project Structure
+```
+├── app.py                    # Main Gradio application
+├── classifier.py             # Motor imagery classifier with ShallowFBCSPNet
+├── data_processor.py         # EEG data loading and preprocessing
+├── sound_library.py          # Sound management and composition system
+├── config.py                 # Configuration settings
+├── requirements.txt          # Python dependencies
+├── SoundHelix-Song-1/        # Audio files for different instruments
+│   ├── bass.wav
+│   ├── drums.wav
+│   ├── other.wav
+│   └── vocals.wav
+└── src/                      # Additional source files
+    ├── model.py
+    ├── preprocessing.py
+    ├── train.py
+    └── visualize.py
+```
+
+### System Components
+
+1. **EEGDataProcessor** (`data_processor.py`)
+   - Loads and processes .mat EEG files
+   - Handles epoching and preprocessing
+   - Simulates real-time data for demo purposes
+
+2. **MotorImageryClassifier** (`classifier.py`)
+   - Implements ShallowFBCSPNet model
+   - Performs real-time classification
+   - Provides confidence scores and probability distributions
+
+3. **SoundManager** (`sound_library.py`)
+   - Maps classifications to audio files
+   - Manages composition layers
+   - Handles audio file loading and playback
+
+4. **Gradio Interface** (`app.py`)
+   - Web-based user interface
+   - Real-time visualization
+   - Composition management tools
+
+## 🚀 Quick Start
+
+### Requirements
+
+Python 3.9–3.11 recommended. Install dependencies:
+
+```bash
+python -m pip install -r requirements.txt
+```
+
+### How to run (Gradio)
+
+Local launch:
+
+```bash
+python app.py
+```
+
+This starts a server on `http://127.0.0.1:7860` by default.
+
+#

app.py

@@ -0,0 +1,1168 @@
+"""
+EEG Motor Imagery Music Composer - Redesigned Interface
+=======================================================
+Brain-Computer Interface that creates music compositions based on imagined movements.
+"""
+
+import gradio as gr
+import numpy as np
+import matplotlib.pyplot as plt
+import time
+import threading
+from typing import Dict, Tuple, Any, List
+
+# Import our custom modules
+from sound_library import SoundManager
+from data_processor import EEGDataProcessor
+from classifier import MotorImageryClassifier
+from config import DEMO_DATA_PATHS, CLASS_NAMES, CONFIDENCE_THRESHOLD
+
+def validate_data_setup() -> str:
+    """Validate that required data files are available."""
+    missing_files = []
+    
+    for subject_id, path in DEMO_DATA_PATHS.items():
+        try:
+            import os
+            if not os.path.exists(path):
+                missing_files.append(f"Subject {subject_id}: {path}")
+        except Exception as e:
+            missing_files.append(f"Subject {subject_id}: Error checking {path}")
+    
+    if missing_files:
+        return f"❌ Missing data files:\n" + "\n".join(missing_files)
+    return "✅ All data files found"
+
+# Global app state
+app_state = {
+    'is_running': False,
+    'demo_data': None,
+    'demo_labels': None,
+    'classification_history': [],
+    'composition_active': False,
+    'auto_mode': False,
+    'last_audio_state': {
+        'left_hand_audio': None,
+        'right_hand_audio': None,
+        'left_leg_audio': None,
+        'right_leg_audio': None,
+        'tongue_audio': None
+    }
+}
+
+# Initialize components
+print("🧠 EEG Motor Imagery Music Composer")
+print("=" * 50)
+print("Starting Gradio application...")
+
+try:
+    sound_manager = SoundManager()
+    data_processor = EEGDataProcessor()
+    classifier = MotorImageryClassifier()
+    
+    # Load demo data
+    import os
+    existing_files = [f for f in DEMO_DATA_PATHS if os.path.exists(f)]
+    if existing_files:
+        app_state['demo_data'], app_state['demo_labels'] = data_processor.process_files(existing_files)
+    else:
+        app_state['demo_data'], app_state['demo_labels'] = None, None
+    
+    if app_state['demo_data'] is not None:
+        # Initialize classifier with proper dimensions
+        classifier.load_model(n_chans=app_state['demo_data'].shape[1], n_times=app_state['demo_data'].shape[2])
+        print(f"✅ Pre-trained model loaded successfully from {classifier.model_path}")
+        print(f"Pre-trained Demo: {len(app_state['demo_data'])} samples from {len(existing_files)} subjects")
+    else:
+        print("⚠️  No demo data loaded - check your .mat files")
+        
+    print(f"Available sound classes: {list(sound_manager.current_sound_mapping.keys())}")
+    
+except Exception as e:
+    print(f"❌ Error during initialization: {e}")
+    raise RuntimeError(
+        "Cannot initialize app without real EEG data. "
+        "Please check your data files and paths."
+    )
+
+def get_movement_sounds() -> Dict[str, str]:
+    """Get the current sound files for each movement."""
+    sounds = {}
+    for movement, sound_file in sound_manager.current_sound_mapping.items():
+        if movement in ['left_hand', 'right_hand', 'left_leg', "right_leg", 'tongue']:  # Only show main movements
+            if sound_file is not None:  # Check if sound_file is not None
+                sound_path = sound_manager.sound_dir / sound_file
+                if sound_path.exists():
+                    # Convert to absolute path for Gradio audio components
+                    sounds[movement] = str(sound_path.resolve())
+    return sounds
+
+def start_composition():
+    """Start the composition process and perform initial classification."""
+    global app_state
+    
+    # Only start new cycle if not already active
+    if not app_state['composition_active']:
+        app_state['composition_active'] = True
+        sound_manager.start_new_cycle()  # Reset composition only when starting fresh
+    
+    if app_state['demo_data'] is None:
+        return "❌ No data", "❌ No data", "❌ No data", None, None, None, None, None, None, "No EEG data available"
+    
+    # Get current target
+    target_movement = sound_manager.get_current_target_movement()
+    print(f"DEBUG start_composition: current target = {target_movement}")
+    
+    # Check if cycle is complete
+    if target_movement == "cycle_complete":
+        return "🎵 Cycle Complete!", "🎵 Complete", "Remap sounds to continue", None, None, None, None, None, None, "Cycle complete - remap sounds to continue"
+    
+    # Perform initial EEG classification
+    epoch_data, true_label = data_processor.simulate_real_time_data(
+        app_state['demo_data'], app_state['demo_labels'], mode="class_balanced"
+    )
+    
+    # Classify the epoch
+    predicted_class, confidence, probabilities = classifier.predict(epoch_data)
+    predicted_name = classifier.class_names[predicted_class]
+    
+    # Process classification
+    result = sound_manager.process_classification(predicted_name, confidence, CONFIDENCE_THRESHOLD)
+    
+    # Create visualization
+    fig = create_eeg_plot(epoch_data, target_movement, predicted_name, confidence, result['sound_added'])
+    
+    # Initialize all audio components to silent (to clear any previous sounds)
+    silent_file = "silent.wav"
+    left_hand_audio = silent_file
+    right_hand_audio = silent_file 
+    left_leg_audio = silent_file
+    right_leg_audio = silent_file
+    tongue_audio = silent_file
+    
+    # Debug: Print classification result
+    print(f"DEBUG start_composition: predicted={predicted_name}, confidence={confidence:.3f}, sound_added={result['sound_added']}")
+    
+    # Only play the sound if it was just added and matches the prediction
+    if result['sound_added']:
+        sounds = get_movement_sounds()
+        print(f"DEBUG: Available sounds: {list(sounds.keys())}")
+        if predicted_name == 'left_hand' and 'left_hand' in sounds:
+            left_hand_audio = sounds['left_hand']
+            print(f"DEBUG: Setting left_hand_audio to {sounds['left_hand']}")
+        elif predicted_name == 'right_hand' and 'right_hand' in sounds:
+            right_hand_audio = sounds['right_hand']
+            print(f"DEBUG: Setting right_hand_audio to {sounds['right_hand']}")
+        elif predicted_name == 'left_leg' and 'left_leg' in sounds:
+            left_leg_audio = sounds['left_leg']
+            print(f"DEBUG: Setting left_leg_audio to {sounds['left_leg']}")
+        elif predicted_name == 'right_leg' and 'right_leg' in sounds:
+            right_leg_audio = sounds['right_leg']
+            print(f"DEBUG: Setting right_leg_audio to {sounds['right_leg']}")
+        elif predicted_name == 'tongue' and 'tongue' in sounds:
+            tongue_audio = sounds['tongue']
+            print(f"DEBUG: Setting tongue_audio to {sounds['tongue']}")
+    else:
+        print("DEBUG: No sound added - confidence too low or other issue")
+    
+    # Format next target with progress information
+    next_target = sound_manager.get_current_target_movement()
+    completed_count = len(sound_manager.movements_completed)
+    total_count = len(sound_manager.current_movement_sequence)
+    
+    if next_target == "cycle_complete":
+        target_text = "🎵 Cycle Complete!"
+    else:
+        target_text = f"🎯 Any Movement ({completed_count}/{total_count} complete) - Use 'Classify Epoch' button to continue"
+    
+    predicted_text = f"🧠 Predicted: {predicted_name.replace('_', ' ').title()} ({confidence:.2f})"
+    
+    # Get composition info
+    composition_info = sound_manager.get_composition_info()
+    status_text = format_composition_summary(composition_info)
+    
+    return (
+        target_text,
+        predicted_text,
+        "2-3 seconds",
+        fig,
+        left_hand_audio,
+        right_hand_audio, 
+        left_leg_audio,
+        right_leg_audio,
+        tongue_audio,
+        status_text
+    )
+
+def stop_composition():
+    """Stop the composition process."""
+    global app_state
+    app_state['composition_active'] = False
+    app_state['auto_mode'] = False
+    return (
+        "Composition stopped. Click 'Start Composing' to begin again",
+        "--",
+        "--",
+        "Stopped - click Start to resume"
+    )
+
+def start_automatic_composition():
+    """Start automatic composition with continuous classification."""
+    global app_state
+    
+    # Only start new cycle if not already active
+    if not app_state['composition_active']:
+        app_state['composition_active'] = True
+        app_state['auto_mode'] = True
+        sound_manager.start_new_cycle()  # Reset composition only when starting fresh
+    
+    if app_state['demo_data'] is None:
+        return "❌ No data", "❌ No data", "❌ No data", "❌ No data", None, None, None, None, None, None, "No EEG data available"
+    
+    # Get current target
+    target_movement = sound_manager.get_current_target_movement()
+    print(f"DEBUG start_automatic_composition: current target = {target_movement}")
+    
+    # Check if cycle is complete
+    if target_movement == "cycle_complete":
+        # Mark current cycle as complete
+        sound_manager.complete_current_cycle()
+        
+        # Check if rehabilitation session should end
+        if sound_manager.should_end_session():
+            app_state['auto_mode'] = False  # Stop automatic mode
+            return (
+                "🎉 Session Complete!", 
+                "🏆 Amazing Progress!", 
+                "Rehabilitation session finished!",
+                "🌟 Congratulations! You've created 2 unique brain-music compositions!\n\n" +
+                "💪 Your motor imagery skills are improving!\n\n" +
+                "🎵 You can review your compositions above, or start a new session anytime.\n\n" +
+                "Would you like to continue with more cycles, or take a well-deserved break?",
+                None, None, None, None, None, None, 
+                f"✅ Session Complete: {sound_manager.completed_cycles}/{sound_manager.max_cycles} compositions finished!"
+            )
+        else:
+            # Start next cycle automatically
+            sound_manager.start_new_cycle()
+            print("🔄 Cycle completed! Starting new cycle automatically...")
+            target_movement = sound_manager.get_current_target_movement()  # Get new target
+    
+    # Show user prompt - encouraging start message
+    cycle_num = sound_manager.current_cycle
+    if cycle_num == 1:
+        prompt_text = "🌟 Welcome to your rehabilitation session! Let's start with any movement you can imagine..."
+    elif cycle_num == 2:
+        prompt_text = "💪 Excellent work on your first composition! Ready for composition #2?"
+    else:
+        prompt_text = "🧠 Let's continue - imagine any movement now..."
+    
+    # Perform initial EEG classification
+    epoch_data, true_label = data_processor.simulate_real_time_data(
+        app_state['demo_data'], app_state['demo_labels'], mode="class_balanced"  
+    )
+    
+    # Classify the epoch
+    predicted_class, confidence, probabilities = classifier.predict(epoch_data)
+    predicted_name = classifier.class_names[predicted_class]
+    
+    # Handle DJ effects or building phase
+    if sound_manager.current_phase == "dj_effects" and confidence > CONFIDENCE_THRESHOLD:
+        # DJ Effects Mode - toggle effects instead of adding sounds
+        dj_result = sound_manager.toggle_dj_effect(predicted_name)
+        result = {
+            'sound_added': dj_result['effect_applied'],
+            'mixed_composition': dj_result.get('mixed_composition'),
+            'effect_name': dj_result.get('effect_name', ''),
+            'effect_status': dj_result.get('effect_status', '')
+        }
+    else:
+        # Building Mode - process classification normally
+        result = sound_manager.process_classification(predicted_name, confidence, CONFIDENCE_THRESHOLD)
+    
+    # Create visualization
+    fig = create_eeg_plot(epoch_data, target_movement, predicted_name, confidence, result['sound_added'])
+    
+    # Initialize all audio components to silent by default
+    silent_file = "silent.wav"
+    left_hand_audio = silent_file
+    right_hand_audio = silent_file 
+    left_leg_audio = silent_file
+    right_leg_audio = silent_file
+    tongue_audio = silent_file
+    
+    # Debug: Print classification result
+    print(f"DEBUG start_automatic_composition: predicted={predicted_name}, confidence={confidence:.3f}, sound_added={result['sound_added']}")
+    
+    # Handle audio display based on current phase
+    if sound_manager.current_phase == "dj_effects":
+        # DJ Effects Phase - show mixed composition with effects
+        if result.get('mixed_composition'):
+            # Show the mixed composition (all sounds combined) in one player
+            left_hand_audio = result['mixed_composition']  # Use first player for mixed audio
+            print(f"DEBUG DJ: Playing mixed composition with effects: {result['mixed_composition']}")
+        else:
+            # Fallback to showing accumulated sounds
+            sounds = get_movement_sounds()
+            completed_movements = sound_manager.movements_completed
+            if 'left_hand' in completed_movements and 'left_hand' in sounds:
+                left_hand_audio = sounds['left_hand']
+    else:
+        # Building Phase - show ALL accumulated sounds (layered composition)
+        sounds = get_movement_sounds()
+        completed_movements = sound_manager.movements_completed
+        print(f"DEBUG: Available sounds: {list(sounds.keys())}")
+        print(f"DEBUG: Completed movements: {completed_movements}")
+        
+        # Display all completed movement sounds (cumulative layering)
+        if 'left_hand' in completed_movements and 'left_hand' in sounds:
+            left_hand_audio = sounds['left_hand']
+            print(f"DEBUG: Showing accumulated left_hand_audio: {sounds['left_hand']}")
+        if 'right_hand' in completed_movements and 'right_hand' in sounds:
+            right_hand_audio = sounds['right_hand']
+            print(f"DEBUG: Showing accumulated right_hand_audio: {sounds['right_hand']}")
+        if 'left_leg' in completed_movements and 'left_leg' in sounds:
+            left_leg_audio = sounds['left_leg']
+            print(f"DEBUG: Showing accumulated left_leg_audio: {sounds['left_leg']}")
+        if 'right_leg' in completed_movements and 'right_leg' in sounds:
+            right_leg_audio = sounds['right_leg']
+            print(f"DEBUG: Showing accumulated right_leg_audio: {sounds['right_leg']}")
+        if 'tongue' in completed_movements and 'tongue' in sounds:
+            tongue_audio = sounds['tongue']
+            print(f"DEBUG: Showing accumulated tongue_audio: {sounds['tongue']}")
+        
+        # If a sound was just added, make sure it's included immediately
+        if result['sound_added'] and predicted_name in sounds:
+            if predicted_name == 'left_hand':
+                left_hand_audio = sounds['left_hand']
+            elif predicted_name == 'right_hand':
+                right_hand_audio = sounds['right_hand']
+            elif predicted_name == 'left_leg':
+                left_leg_audio = sounds['left_leg']
+            elif predicted_name == 'right_leg':
+                right_leg_audio = sounds['right_leg']
+            elif predicted_name == 'tongue':
+                tongue_audio = sounds['tongue']
+            print(f"DEBUG: Just added {predicted_name} sound: {sounds[predicted_name]}")
+    
+    # Check for phase transition to DJ effects
+    completed_count = len(sound_manager.movements_completed)
+    total_count = len(sound_manager.current_movement_sequence)
+    
+    # Transition to DJ effects if all movements completed but still in building phase
+    if completed_count >= 5 and sound_manager.current_phase == "building":
+        sound_manager.transition_to_dj_phase()
+    
+    # Format display based on current phase
+    if sound_manager.current_phase == "dj_effects":
+        target_text = "🎧 DJ Mode Active - Use movements to control effects!"
+    else:
+        next_target = sound_manager.get_current_target_movement()
+        if next_target == "cycle_complete":
+            target_text = "🎵 Composition Complete!"
+        else:
+            target_text = f"🎯 Building Composition ({completed_count}/{total_count} layers)"
+    
+    # Update display text based on phase
+    if sound_manager.current_phase == "dj_effects":
+        if result.get('effect_name') and result.get('effect_status'):
+            predicted_text = f"🎛️ {result['effect_name']}: {result['effect_status']}"
+        else:
+            predicted_text = f"🧠 Detected: {predicted_name.replace('_', ' ').title()} ({confidence:.2f})"
+        timer_text = "🎧 DJ Mode - Effects updating every 3 seconds..."
+    else:
+        predicted_text = f"🧠 Predicted: {predicted_name.replace('_', ' ').title()} ({confidence:.2f})"
+        timer_text = "⏱️ Next trial in 2-3 seconds..."
+    
+    # Get composition info
+    composition_info = sound_manager.get_composition_info()
+    status_text = format_composition_summary(composition_info)
+    
+    # Phase-based instruction visibility
+    building_visible = sound_manager.current_phase == "building"
+    dj_visible = sound_manager.current_phase == "dj_effects"
+    
+    return (
+        target_text,
+        predicted_text,
+        timer_text,
+        prompt_text,
+        fig,
+        left_hand_audio,
+        right_hand_audio, 
+        left_leg_audio,
+        right_leg_audio,
+        tongue_audio,
+        status_text,
+        gr.update(visible=building_visible),  # building_instructions
+        gr.update(visible=dj_visible)         # dj_instructions
+    )
+
+def manual_classify():
+    """Manual classification for testing purposes."""
+    global app_state
+    
+    if app_state['demo_data'] is None:
+        return "❌ No data", "❌ No data", "Manual mode", None, "No EEG data available", None, None, None, None, None
+    
+    # Get EEG data sample
+    epoch_data, true_label = data_processor.simulate_real_time_data(
+        app_state['demo_data'], app_state['demo_labels'], mode="class_balanced"
+    )
+    
+    # Classify the epoch
+    predicted_class, confidence, probabilities = classifier.predict(epoch_data)
+    predicted_name = classifier.class_names[predicted_class]
+    
+    # Create visualization (without composition context)
+    fig = create_eeg_plot(epoch_data, "manual_test", predicted_name, confidence, False)
+    
+    # Format results
+    target_text = "🎯 Manual Test Mode"
+    predicted_text = f"🧠 {predicted_name.replace('_', ' ').title()} ({confidence:.2f})"
+    
+    # Update results log
+    import time
+    timestamp = time.strftime("%H:%M:%S")
+    result_entry = f"[{timestamp}] Predicted: {predicted_name.replace('_', ' ').title()} (confidence: {confidence:.3f})"
+    
+    # Get sound files for preview (no autoplay)
+    sounds = get_movement_sounds()
+    left_hand_audio = sounds.get('left_hand', None)
+    right_hand_audio = sounds.get('right_hand', None)
+    left_leg_audio = sounds.get('left_leg', None)
+    right_leg_audio = sounds.get('right_leg', None)
+    tongue_audio = sounds.get('tongue', None)
+    
+    return (
+        target_text,
+        predicted_text,
+        "Manual mode - click button to classify",
+        fig,
+        result_entry,
+        left_hand_audio,
+        right_hand_audio,
+        left_leg_audio,
+        right_leg_audio,
+        tongue_audio
+    )
+
+def clear_manual():
+    """Clear manual testing results."""
+    return (
+        "🎯 Manual Test Mode",
+        "--",
+        "Manual mode",
+        None,
+        "Manual classification results cleared...",
+        None, None, None, None, None
+    )
+
+def continue_automatic_composition():
+    """Continue automatic composition - called for subsequent trials."""
+    global app_state
+    
+    if not app_state['composition_active'] or not app_state['auto_mode']:
+        return "🛑 Stopped", "--", "--", "Automatic composition stopped", None, None, None, None, None, None, "Stopped", gr.update(visible=True), gr.update(visible=False)
+    
+    if app_state['demo_data'] is None:
+        return "❌ No data", "❌ No data", "❌ No data", "❌ No data", None, None, None, None, None, None, "No EEG data available", gr.update(visible=True), gr.update(visible=False)
+    
+    # Get current target
+    target_movement = sound_manager.get_current_target_movement()
+    print(f"DEBUG continue_automatic_composition: current target = {target_movement}")
+    
+    # Check if cycle is complete
+    if target_movement == "cycle_complete":
+        # Mark current cycle as complete
+        sound_manager.complete_current_cycle()
+        
+        # Check if rehabilitation session should end
+        if sound_manager.should_end_session():
+            app_state['auto_mode'] = False  # Stop automatic mode
+            return (
+                "🎉 Session Complete!", 
+                "🏆 Amazing Progress!", 
+                "Rehabilitation session finished!",
+                "🌟 Congratulations! You've created 2 unique brain-music compositions!\n\n" +
+                "💪 Your motor imagery skills are improving!\n\n" +
+                "🎵 You can review your compositions above, or start a new session anytime.\n\n" +
+                "Would you like to continue with more cycles, or take a well-deserved break?",
+                None, None, None, None, None, None, 
+                f"✅ Session Complete: {sound_manager.completed_cycles}/{sound_manager.max_cycles} compositions finished!",
+                gr.update(visible=True), gr.update(visible=False)
+            )
+        else:
+            # Start next cycle automatically
+            sound_manager.start_new_cycle()
+            print("🔄 Cycle completed! Starting new cycle automatically...")
+            target_movement = sound_manager.get_current_target_movement()  # Get new target
+    
+    # Show next user prompt - rehabilitation-focused messaging
+    prompts = [
+        "💪 Great work! Imagine your next movement...",
+        "🎯 You're doing amazing! Focus and imagine any movement...", 
+        "✨ Excellent progress! Ready for the next movement?",
+        "🌟 Keep it up! Concentrate and imagine now...",
+        "🏆 Fantastic! Next trial - imagine any movement..."
+    ]
+    import random
+    prompt_text = random.choice(prompts)
+    
+    # Add progress encouragement
+    completed_count = len(sound_manager.movements_completed)
+    total_count = len(sound_manager.current_movement_sequence)
+    if completed_count > 0:
+        prompt_text += f" ({completed_count}/{total_count} movements completed this cycle)"
+    
+    # Perform EEG classification
+    epoch_data, true_label = data_processor.simulate_real_time_data(
+        app_state['demo_data'], app_state['demo_labels'], mode="class_balanced"  
+    )
+    
+    # Classify the epoch
+    predicted_class, confidence, probabilities = classifier.predict(epoch_data)
+    predicted_name = classifier.class_names[predicted_class]
+    
+    # Handle DJ effects or building phase
+    if sound_manager.current_phase == "dj_effects" and confidence > CONFIDENCE_THRESHOLD:
+        # DJ Effects Mode - toggle effects instead of adding sounds
+        dj_result = sound_manager.toggle_dj_effect(predicted_name)
+        result = {
+            'sound_added': dj_result['effect_applied'],
+            'mixed_composition': dj_result.get('mixed_composition'),
+            'effect_name': dj_result.get('effect_name', ''),
+            'effect_status': dj_result.get('effect_status', '')
+        }
+    else:
+        # Building Mode - process classification normally
+        result = sound_manager.process_classification(predicted_name, confidence, CONFIDENCE_THRESHOLD)
+        
+        # Check if we should transition to DJ phase
+        completed_count = len(sound_manager.movements_completed)
+        if completed_count >= 5 and sound_manager.current_phase == "building":
+            if sound_manager.transition_to_dj_phase():
+                print(f"DEBUG: Successfully transitioned to DJ phase with {completed_count} completed movements")
+    
+    # Create visualization
+    fig = create_eeg_plot(epoch_data, target_movement, predicted_name, confidence, result['sound_added'])
+    
+    # Initialize all audio components to silent by default
+    silent_file = "silent.wav"
+    left_hand_audio = silent_file
+    right_hand_audio = silent_file 
+    left_leg_audio = silent_file
+    right_leg_audio = silent_file
+    tongue_audio = silent_file
+    
+    # Handle audio differently based on phase
+    if sound_manager.current_phase == "dj_effects":
+        # DJ Mode: Play mixed composition with effects in the center position (tongue)
+        # Keep individual tracks silent to avoid overlapping audio
+        # Only update audio if the mixed composition file has actually changed
+        if sound_manager.mixed_composition_file and os.path.exists(sound_manager.mixed_composition_file):
+            # Only update if the file path has changed from last time
+            if app_state['last_audio_state']['tongue_audio'] != sound_manager.mixed_composition_file:
+                tongue_audio = sound_manager.mixed_composition_file
+                app_state['last_audio_state']['tongue_audio'] = sound_manager.mixed_composition_file
+                print(f"DEBUG continue: DJ mode - NEW mixed composition loaded: {sound_manager.mixed_composition_file}")
+            elif app_state['last_audio_state']['tongue_audio'] is not None:
+                # Use the same file as before to prevent Gradio from restarting audio
+                tongue_audio = app_state['last_audio_state']['tongue_audio']
+                # No debug print to reduce spam
+            else:
+                # Handle case where cached state is None - use the current file
+                tongue_audio = sound_manager.mixed_composition_file
+                app_state['last_audio_state']['tongue_audio'] = sound_manager.mixed_composition_file
+                print(f"DEBUG continue: DJ mode - Loading mixed composition (state was None): {sound_manager.mixed_composition_file}")
+        # Note: We don't update with processed effects files to prevent audio restarts
+    else:
+        # Building Mode: Show ALL accumulated sounds (layered composition)
+        sounds = get_movement_sounds()
+        completed_movements = sound_manager.movements_completed
+        print(f"DEBUG continue: Available sounds: {list(sounds.keys())}")
+        print(f"DEBUG continue: Completed movements: {completed_movements}")
+        
+        # Display all completed movement sounds (cumulative layering) - only update when changed
+        if 'left_hand' in completed_movements and 'left_hand' in sounds:
+            new_left_hand = sounds['left_hand']
+            if app_state['last_audio_state']['left_hand_audio'] != new_left_hand:
+                left_hand_audio = new_left_hand
+                app_state['last_audio_state']['left_hand_audio'] = new_left_hand
+                print(f"DEBUG continue: NEW left_hand_audio: {new_left_hand}")
+            elif app_state['last_audio_state']['left_hand_audio'] is not None:
+                left_hand_audio = app_state['last_audio_state']['left_hand_audio']
+            else:
+                # Handle case where cached state is None - use the current file
+                left_hand_audio = new_left_hand
+                app_state['last_audio_state']['left_hand_audio'] = new_left_hand
+                
+        if 'right_hand' in completed_movements and 'right_hand' in sounds:
+            new_right_hand = sounds['right_hand']
+            # TEMP FIX: Always update right_hand to test audio issue
+            right_hand_audio = new_right_hand
+            app_state['last_audio_state']['right_hand_audio'] = new_right_hand
+            print(f"DEBUG continue: ALWAYS UPDATE right_hand_audio: {new_right_hand}")
+                
+        if 'left_leg' in completed_movements and 'left_leg' in sounds:
+            new_left_leg = sounds['left_leg']
+            if app_state['last_audio_state']['left_leg_audio'] != new_left_leg:
+                left_leg_audio = new_left_leg
+                app_state['last_audio_state']['left_leg_audio'] = new_left_leg
+                print(f"DEBUG continue: NEW left_leg_audio: {new_left_leg}")
+            elif app_state['last_audio_state']['left_leg_audio'] is not None:
+                left_leg_audio = app_state['last_audio_state']['left_leg_audio']
+            else:
+                # Handle case where cached state is None - use the current file
+                left_leg_audio = new_left_leg
+                app_state['last_audio_state']['left_leg_audio'] = new_left_leg
+                
+        if 'right_leg' in completed_movements and 'right_leg' in sounds:
+            new_right_leg = sounds['right_leg']
+            if app_state['last_audio_state']['right_leg_audio'] != new_right_leg:
+                right_leg_audio = new_right_leg
+                app_state['last_audio_state']['right_leg_audio'] = new_right_leg
+                print(f"DEBUG continue: NEW right_leg_audio: {new_right_leg}")
+            elif app_state['last_audio_state']['right_leg_audio'] is not None:
+                right_leg_audio = app_state['last_audio_state']['right_leg_audio']
+            else:
+                # Handle case where cached state is None - use the current file
+                right_leg_audio = new_right_leg
+                app_state['last_audio_state']['right_leg_audio'] = new_right_leg
+                
+        if 'tongue' in completed_movements and 'tongue' in sounds:
+            new_tongue = sounds['tongue']
+            # Note: Don't update tongue audio in building mode if we're about to transition to DJ mode
+            if sound_manager.current_phase == "building":
+                if app_state['last_audio_state']['tongue_audio'] != new_tongue:
+                    tongue_audio = new_tongue
+                    app_state['last_audio_state']['tongue_audio'] = new_tongue
+                    print(f"DEBUG continue: NEW tongue_audio: {new_tongue}")
+                elif app_state['last_audio_state']['tongue_audio'] is not None:
+                    tongue_audio = app_state['last_audio_state']['tongue_audio']
+                else:
+                    # Handle case where cached state is None - use the current file
+                    tongue_audio = new_tongue
+                    app_state['last_audio_state']['tongue_audio'] = new_tongue
+        
+        # If a sound was just added, make sure it gets updated immediately (override state check)
+        if result['sound_added'] and predicted_name in sounds:
+            new_sound = sounds[predicted_name]
+            if predicted_name == 'left_hand':
+                left_hand_audio = new_sound
+                app_state['last_audio_state']['left_hand_audio'] = new_sound
+            elif predicted_name == 'right_hand':
+                right_hand_audio = new_sound
+                app_state['last_audio_state']['right_hand_audio'] = new_sound
+            elif predicted_name == 'left_leg':
+                left_leg_audio = new_sound
+                app_state['last_audio_state']['left_leg_audio'] = new_sound
+            elif predicted_name == 'right_leg':
+                right_leg_audio = new_sound
+                app_state['last_audio_state']['right_leg_audio'] = new_sound
+            elif predicted_name == 'tongue':
+                tongue_audio = new_sound
+                app_state['last_audio_state']['tongue_audio'] = new_sound
+            print(f"DEBUG continue: Force update - just added {predicted_name} sound: {new_sound}")
+    
+    # Format display with progress information
+    completed_count = len(sound_manager.movements_completed)
+    total_count = len(sound_manager.current_movement_sequence)
+    
+    if sound_manager.current_phase == "dj_effects":
+        target_text = f"🎧 DJ Mode - Control Effects with Movements"
+        predicted_text = f"🧠 Predicted: {predicted_name.replace('_', ' ').title()} ({confidence:.2f})"
+        if result.get('effect_applied'):
+            effect_name = result.get('effect_name', '')
+            effect_status = result.get('effect_status', '')
+            timer_text = f"�️ {effect_name}: {effect_status}"
+        else:
+            timer_text = "🎵 Move to control effects..."
+    else:
+        target_text = f"�🎯 Any Movement ({completed_count}/{total_count} complete)"
+        predicted_text = f"🧠 Predicted: {predicted_name.replace('_', ' ').title()} ({confidence:.2f})"
+        timer_text = "⏱️ Next trial in 2-3 seconds..." if app_state['auto_mode'] else "Stopped"
+    
+    # Get composition info
+    composition_info = sound_manager.get_composition_info()
+    status_text = format_composition_summary(composition_info)
+    
+    # Phase-based instruction visibility
+    building_visible = sound_manager.current_phase == "building"
+    dj_visible = sound_manager.current_phase == "dj_effects"
+    
+    return (
+        target_text,
+        predicted_text,
+        timer_text,
+        prompt_text,
+        fig,
+        left_hand_audio,
+        right_hand_audio, 
+        left_leg_audio,
+        right_leg_audio,
+        tongue_audio,
+        status_text,
+        gr.update(visible=building_visible),  # building_instructions
+        gr.update(visible=dj_visible)         # dj_instructions
+    )
+
+def classify_epoch():
+    """Classify a single EEG epoch and update composition."""
+    global app_state
+    
+    if not app_state['composition_active']:
+        return "❌ Not active", "❌ Not active", "❌ Not active", None, None, None, None, None, None, "Click 'Start Composing' first"
+    
+    if app_state['demo_data'] is None:
+        return "❌ No data", "❌ No data", "❌ No data", None, None, None, None, None, None, "No EEG data available"
+    
+    # Get current target
+    target_movement = sound_manager.get_current_target_movement()
+    print(f"DEBUG classify_epoch: current target = {target_movement}")
+    
+    if target_movement == "cycle_complete":
+        return "🎵 Cycle Complete!", "🎵 Complete", "Remap sounds to continue", None, None, None, None, None, None, "Cycle complete - remap sounds to continue"
+    
+    # Get EEG data sample
+    epoch_data, true_label = data_processor.simulate_real_time_data(
+        app_state['demo_data'], app_state['demo_labels'], mode="class_balanced"
+    )
+    
+    # Classify the epoch
+    predicted_class, confidence, probabilities = classifier.predict(epoch_data)
+    predicted_name = classifier.class_names[predicted_class]
+    
+    # Process classification
+    result = sound_manager.process_classification(predicted_name, confidence, CONFIDENCE_THRESHOLD)
+    
+    # Check if we should transition to DJ phase
+    completed_count = len(sound_manager.movements_completed)
+    if completed_count >= 5 and sound_manager.current_phase == "building":
+        if sound_manager.transition_to_dj_phase():
+            print(f"DEBUG: Successfully transitioned to DJ phase with {completed_count} completed movements")
+    
+    # Create visualization
+    fig = create_eeg_plot(epoch_data, target_movement, predicted_name, confidence, result['sound_added'])
+    
+    # Initialize all audio components to silent (to clear any previous sounds)
+    silent_file = "silent.wav"
+    left_hand_audio = silent_file
+    right_hand_audio = silent_file 
+    left_leg_audio = silent_file
+    right_leg_audio = silent_file
+    tongue_audio = silent_file
+    
+    # Only play the sound if it was just added and matches the prediction
+    if result['sound_added']:
+        sounds = get_movement_sounds()
+        if predicted_name == 'left_hand' and 'left_hand' in sounds:
+            left_hand_audio = sounds['left_hand']
+        elif predicted_name == 'right_hand' and 'right_hand' in sounds:
+            right_hand_audio = sounds['right_hand']
+        elif predicted_name == 'left_leg' and 'left_leg' in sounds:
+            left_leg_audio = sounds['left_leg']
+        elif predicted_name == 'right_leg' and 'right_leg' in sounds:
+            right_leg_audio = sounds['right_leg']
+        elif predicted_name == 'tongue' and 'tongue' in sounds:
+            tongue_audio = sounds['tongue']
+    
+    # Format next target
+    next_target = sound_manager.get_current_target_movement()
+    target_text = f"🎯 Target: {next_target.replace('_', ' ').title()}" if next_target != "cycle_complete" else "🎵 Cycle Complete!"
+    
+    predicted_text = f"🧠 Predicted: {predicted_name.replace('_', ' ').title()} ({confidence:.2f})"
+    
+    # Get composition info
+    composition_info = sound_manager.get_composition_info()
+    status_text = format_composition_summary(composition_info)
+    
+    return (
+        target_text,
+        predicted_text,
+        "2-3 seconds",
+        fig,
+        left_hand_audio,
+        right_hand_audio, 
+        left_leg_audio,
+        right_leg_audio,
+        tongue_audio,
+        status_text
+    )
+
+def create_eeg_plot(eeg_data: np.ndarray, target_movement: str, predicted_name: str, confidence: float, sound_added: bool) -> plt.Figure:
+    """Create EEG plot with target movement and classification result."""
+    fig, axes = plt.subplots(2, 2, figsize=(12, 8))
+    axes = axes.flatten()
+    
+    # Plot 4 channels
+    time_points = np.arange(eeg_data.shape[1]) / 200  # 200 Hz sampling rate
+    channel_names = ['C3', 'C4', 'T3', 'T4']  # Motor cortex channels
+    
+    for i in range(min(4, eeg_data.shape[0])):
+        color = 'green' if sound_added else 'blue'
+        axes[i].plot(time_points, eeg_data[i], color=color, linewidth=1)
+        
+        if i < len(channel_names):
+            axes[i].set_title(f'{channel_names[i]} (Ch {i+1})')
+        else:
+            axes[i].set_title(f'Channel {i+1}')
+            
+        axes[i].set_xlabel('Time (s)')
+        axes[i].set_ylabel('Amplitude (µV)')
+        axes[i].grid(True, alpha=0.3)
+    
+    # Add overall title with status
+    status = "✓ SOUND ADDED" if sound_added else "○ No sound"
+    title = f"Target: {target_movement.replace('_', ' ').title()} | Predicted: {predicted_name.replace('_', ' ').title()} ({confidence:.2f}) | {status}"
+    fig.suptitle(title, fontsize=12, fontweight='bold')
+    fig.tight_layout()
+    return fig
+
+def format_composition_summary(composition_info: Dict) -> str:
+    """Format composition information for display."""
+    if not composition_info.get('layers_by_cycle'):
+        return "No composition layers yet"
+    
+    summary = []
+    for cycle, layers in composition_info['layers_by_cycle'].items():
+        summary.append(f"Cycle {cycle + 1}: {len(layers)} layers")
+        for layer in layers:
+            movement = layer.get('movement', 'unknown')
+            confidence = layer.get('confidence', 0)
+            summary.append(f"  • {movement.replace('_', ' ').title()} ({confidence:.2f})")
+    
+    return "\n".join(summary) if summary else "No composition layers"
+
+# Create Gradio interface
+def create_interface():
+    with gr.Blocks(title="EEG Motor Imagery Music Composer", theme=gr.themes.Soft()) as demo:
+        gr.Markdown("# 🧠🎵 EEG Motor Imagery Rehabilitation Composer")
+        gr.Markdown("**Therapeutic Brain-Computer Interface for Motor Recovery**\n\nCreate beautiful music compositions using your brain signals! This rehabilitation tool helps strengthen motor imagery skills while creating personalized musical pieces.")
+        
+        with gr.Tabs() as tabs:
+            # Main Composition Tab
+            with gr.TabItem("🎵 Automatic Composition"):
+                with gr.Row():
+                    # Left side - Task and EEG information
+                    with gr.Column(scale=2):
+                        # Task instructions - Building Phase
+                        with gr.Group() as building_instructions:
+                            gr.Markdown("### 🎯 Rehabilitation Session Instructions")
+                            gr.Markdown("""
+                            **Motor Imagery Training:**
+                            - **Imagine** opening or closing your **right or left hand**
+                            - **Visualize** briefly moving your **right or left leg or foot**  
+                            - **Think about** pronouncing **"L"** with your tongue
+                            - **Rest state** (no movement imagination)
+                            
+                            *🌟 Each successful imagination creates a musical layer!*
+                            
+                            **Session Structure:** Build composition, then control DJ effects
+                            *Press Start to begin your personalized rehabilitation session*
+                            """)
+                        
+                        # DJ Instructions - Effects Phase (initially hidden)
+                        with gr.Group(visible=False) as dj_instructions:
+                            gr.Markdown("### 🎧 DJ Controller Mode")
+                            gr.Markdown("""
+                            **🎉 Composition Complete! You are now the DJ!**
+                            
+                            **Use the same movements to control audio effects:**
+                            - 👈 **Left Hand**: Volume Fade On/Off
+                            - 👉 **Right Hand**: High Pass Filter On/Off  
+                            - 🦵 **Left Leg**: Reverb Effect On/Off
+                            - 🦵 **Right Leg**: Low Pass Filter On/Off
+                            - 👅 **Tongue**: Bass Boost On/Off
+                            
+                            *🎛️ Each movement toggles an effect - Mix your creation!*
+                            """)
+                        
+                        # Start button
+                        with gr.Row():
+                            start_btn = gr.Button("🎵 Start Composing", variant="primary", size="lg")
+                            continue_btn = gr.Button("⏭️ Continue", variant="primary", size="lg", visible=False)
+                            stop_btn = gr.Button("🛑 Stop", variant="secondary", size="lg")
+                        
+                        # Session completion options (shown after 2 cycles)
+                        with gr.Row(visible=False) as session_complete_row:
+                            new_session_btn = gr.Button("🔄 Start New Session", variant="primary", size="lg")
+                            extend_session_btn = gr.Button("➕ Continue Session", variant="secondary", size="lg")
+                        
+                        # Timer for automatic progression (hidden from user)
+                        timer = gr.Timer(value=3.0, active=False)  # 3 second intervals
+                        
+                        # User prompt display
+                        user_prompt = gr.Textbox(label="💭 User Prompt", interactive=False, value="Click 'Start Composing' to begin", 
+                                               elem_classes=["prompt-display"])
+                        
+                        # Current status
+                        with gr.Row():
+                            target_display = gr.Textbox(label="🎯 Current Target", interactive=False, value="Ready to start")
+                            predicted_display = gr.Textbox(label="🧠 Predicted", interactive=False, value="--") 
+                        
+                        timer_display = gr.Textbox(label="⏱️ Next Trial In", interactive=False, value="--")
+                        
+                        eeg_plot = gr.Plot(label="EEG Data Visualization")
+                        
+                    # Right side - Compositional layers  
+                    with gr.Column(scale=1):
+                        gr.Markdown("### 🎵 Compositional Layers")
+                        
+                        # Show 5 movement sounds 
+                        left_hand_sound = gr.Audio(label="👈 Left Hand", interactive=False, autoplay=True, visible=True)
+                        right_hand_sound = gr.Audio(label="👉 Right Hand", interactive=False, autoplay=True, visible=True) 
+                        left_leg_sound = gr.Audio(label="🦵 Left Leg", interactive=False, autoplay=True, visible=True)
+                        right_leg_sound = gr.Audio(label="🦵 Right Leg", interactive=False, autoplay=True, visible=True)
+                        tongue_sound = gr.Audio(label="👅 Tongue", interactive=False, autoplay=True, visible=True)
+                        
+                        # Composition status
+                        composition_status = gr.Textbox(label="Composition Status", interactive=False, lines=5)
+            
+            # Manual Testing Tab 
+            with gr.TabItem("🧠 Manual Testing"):
+                with gr.Row():
+                    with gr.Column(scale=2):
+                        gr.Markdown("### 🔬 Manual EEG Classification Testing")
+                        gr.Markdown("Use this tab to manually test the EEG classifier without the composition system.")
+                        
+                        with gr.Row():
+                            classify_btn = gr.Button("🧠 Classify Single Epoch", variant="primary")
+                            clear_btn = gr.Button("�️ Clear", variant="secondary")
+                        
+                        # Manual status displays
+                        manual_target_display = gr.Textbox(label="🎯 Current Target", interactive=False, value="Ready")
+                        manual_predicted_display = gr.Textbox(label="🧠 Predicted", interactive=False, value="--")
+                        manual_timer_display = gr.Textbox(label="⏱️ Status", interactive=False, value="Manual mode")
+                        
+                        manual_eeg_plot = gr.Plot(label="EEG Data Visualization")
+                        
+                    with gr.Column(scale=1):
+                        gr.Markdown("### 📊 Classification Results")
+                        manual_results = gr.Textbox(label="Results Log", interactive=False, lines=10, value="Manual classification results will appear here...")
+                        
+                        # Individual sound previews (no autoplay in manual mode)
+                        gr.Markdown("### 🔊 Sound Preview")
+                        manual_left_hand_sound = gr.Audio(label="👈 Left Hand", interactive=False, autoplay=False, visible=True)
+                        manual_right_hand_sound = gr.Audio(label="👉 Right Hand", interactive=False, autoplay=False, visible=True)
+                        manual_left_leg_sound = gr.Audio(label="🦵 Left Leg", interactive=False, autoplay=False, visible=True)
+                        manual_right_leg_sound = gr.Audio(label="🦵 Right Leg", interactive=False, autoplay=False, visible=True)
+                        manual_tongue_sound = gr.Audio(label="👅 Tongue", interactive=False, autoplay=False, visible=True)
+        
+        # Session management functions
+        def start_new_session():
+            """Reset everything and start a completely new rehabilitation session"""
+            global sound_manager
+            sound_manager.completed_cycles = 0
+            sound_manager.current_cycle = 0
+            sound_manager.movements_completed = set()
+            sound_manager.composition_layers = []
+            
+            # Start fresh session
+            result = start_automatic_composition()
+            return (
+                result[0],  # target_display
+                result[1],  # predicted_display  
+                result[2],  # timer_display
+                result[3],  # user_prompt
+                result[4],  # eeg_plot
+                result[5],  # left_hand_sound
+                result[6],  # right_hand_sound
+                result[7],  # left_leg_sound
+                result[8],  # right_leg_sound
+                result[9],  # tongue_sound
+                result[10], # composition_status
+                result[11], # building_instructions
+                result[12], # dj_instructions
+                gr.update(visible=True),   # continue_btn - show it
+                gr.update(active=True),    # timer - activate it
+                gr.update(visible=False)   # session_complete_row - hide it
+            )
+        
+        def extend_current_session():
+            """Continue current session beyond the 2-cycle limit"""
+            sound_manager.max_cycles += 2  # Add 2 more cycles
+            
+            # Continue with current session
+            result = continue_automatic_composition()
+            return (
+                result[0],  # target_display
+                result[1],  # predicted_display  
+                result[2],  # timer_display
+                result[3],  # user_prompt
+                result[4],  # eeg_plot
+                result[5],  # left_hand_sound
+                result[6],  # right_hand_sound
+                result[7],  # left_leg_sound
+                result[8],  # right_leg_sound
+                result[9],  # tongue_sound
+                result[10], # composition_status
+                result[11], # building_instructions
+                result[12], # dj_instructions
+                gr.update(visible=True),   # continue_btn - show it
+                gr.update(active=True),    # timer - activate it
+                gr.update(visible=False)   # session_complete_row - hide it
+            )
+
+        # Wrapper functions for timer control
+        def start_with_timer():
+            """Start composition and activate automatic timer"""
+            result = start_automatic_composition()
+            # Show continue button and activate timer
+            return (
+                result[0],  # target_display
+                result[1],  # predicted_display  
+                result[2],  # timer_display
+                result[3],  # user_prompt
+                result[4],  # eeg_plot
+                result[5],  # left_hand_sound
+                result[6],  # right_hand_sound
+                result[7],  # left_leg_sound
+                result[8],  # right_leg_sound
+                result[9],  # tongue_sound
+                result[10], # composition_status
+                result[11], # building_instructions
+                result[12], # dj_instructions
+                gr.update(visible=True),  # continue_btn - show it
+                gr.update(active=True)    # timer - activate it
+            )
+        
+        def continue_with_timer():
+            """Continue composition and manage timer state"""
+            result = continue_automatic_composition()
+            
+            # Check if session is complete (rehabilitation session finished)
+            if "🎉 Session Complete!" in result[0]:
+                # Show session completion options
+                return (
+                    result[0],  # target_display
+                    result[1],  # predicted_display  
+                    result[2],  # timer_display
+                    result[3],  # user_prompt
+                    result[4],  # eeg_plot
+                    result[5],  # left_hand_sound
+                    result[6],  # right_hand_sound
+                    result[7],  # left_leg_sound
+                    result[8],  # right_leg_sound
+                    result[9],  # tongue_sound
+                    result[10], # composition_status
+                    result[11], # building_instructions
+                    result[12], # dj_instructions  
+                    gr.update(active=False),  # timer - deactivate it
+                    gr.update(visible=True)   # session_complete_row - show options
+                )
+            # Check if composition is complete (old logic for other cases)
+            elif "🎵 Cycle Complete!" in result[0]:
+                # Stop the timer when composition is complete
+                return (
+                    result[0],  # target_display
+                    result[1],  # predicted_display  
+                    result[2],  # timer_display
+                    result[3],  # user_prompt
+                    result[4],  # eeg_plot
+                    result[5],  # left_hand_sound
+                    result[6],  # right_hand_sound
+                    result[7],  # left_leg_sound
+                    result[8],  # right_leg_sound
+                    result[9],  # tongue_sound
+                    result[10], # composition_status
+                    result[11], # building_instructions
+                    result[12], # dj_instructions
+                    gr.update(active=False),  # timer - deactivate it
+                    gr.update(visible=False)  # session_complete_row - keep hidden
+                )
+            else:
+                # Keep timer active for next iteration
+                return (
+                    result[0],  # target_display
+                    result[1],  # predicted_display  
+                    result[2],  # timer_display
+                    result[3],  # user_prompt
+                    result[4],  # eeg_plot
+                    result[5],  # left_hand_sound
+                    result[6],  # right_hand_sound
+                    result[7],  # left_leg_sound
+                    result[8],  # right_leg_sound
+                    result[9],  # tongue_sound
+                    result[10], # composition_status
+                    result[11], # building_instructions
+                    result[12], # dj_instructions
+                    gr.update(active=True),   # timer - keep active
+                    gr.update(visible=False)  # session_complete_row - keep hidden
+                )
+        
+        # Event handlers for automatic composition tab
+        start_btn.click(
+            fn=start_with_timer,
+            outputs=[target_display, predicted_display, timer_display, user_prompt, eeg_plot,
+                    left_hand_sound, right_hand_sound, left_leg_sound, right_leg_sound, tongue_sound, composition_status,
+                    building_instructions, dj_instructions, continue_btn, timer]
+        )
+        
+        continue_btn.click(
+            fn=continue_with_timer,
+            outputs=[target_display, predicted_display, timer_display, user_prompt, eeg_plot,
+                    left_hand_sound, right_hand_sound, left_leg_sound, right_leg_sound, tongue_sound, composition_status,
+                    building_instructions, dj_instructions, timer, session_complete_row]
+        )
+        
+        # Timer automatically triggers continuation
+        timer.tick(
+            fn=continue_with_timer,
+            outputs=[target_display, predicted_display, timer_display, user_prompt, eeg_plot,
+                    left_hand_sound, right_hand_sound, left_leg_sound, right_leg_sound, tongue_sound, composition_status,
+                    building_instructions, dj_instructions, timer, session_complete_row]
+        )
+        
+        # Session completion event handlers
+        new_session_btn.click(
+            fn=start_new_session,
+            outputs=[target_display, predicted_display, timer_display, user_prompt, eeg_plot,
+                    left_hand_sound, right_hand_sound, left_leg_sound, right_leg_sound, tongue_sound, composition_status,
+                    building_instructions, dj_instructions, continue_btn, timer, session_complete_row]
+        )
+        
+        extend_session_btn.click(
+            fn=extend_current_session,
+            outputs=[target_display, predicted_display, timer_display, user_prompt, eeg_plot,
+                    left_hand_sound, right_hand_sound, left_leg_sound, right_leg_sound, tongue_sound, composition_status,
+                    building_instructions, dj_instructions, continue_btn, timer, session_complete_row]
+        )
+        
+        def stop_with_timer():
+            """Stop composition and deactivate timer"""
+            result = stop_composition()
+            return (
+                result[0],  # target_display
+                result[1],  # predicted_display
+                result[2],  # timer_display
+                result[3],  # user_prompt
+                gr.update(visible=False),  # continue_btn - hide it
+                gr.update(active=False)    # timer - deactivate it
+            )
+        
+        stop_btn.click(
+            fn=stop_with_timer,
+            outputs=[target_display, predicted_display, timer_display, user_prompt, continue_btn, timer]
+        )
+        
+        # Event handlers for manual testing tab
+        classify_btn.click(
+            fn=manual_classify,
+            outputs=[manual_target_display, manual_predicted_display, manual_timer_display, manual_eeg_plot, manual_results,
+                    manual_left_hand_sound, manual_right_hand_sound, manual_left_leg_sound, manual_right_leg_sound, manual_tongue_sound]
+        )
+        
+        clear_btn.click(
+            fn=clear_manual,
+            outputs=[manual_target_display, manual_predicted_display, manual_timer_display, manual_eeg_plot, manual_results,
+                    manual_left_hand_sound, manual_right_hand_sound, manual_left_leg_sound, manual_right_leg_sound, manual_tongue_sound] 
+        )
+        
+        # Note: No auto-loading of sounds to prevent playing all sounds on startup
+    
+    return demo
+
+if __name__ == "__main__":
+    demo = create_interface()
+    demo.launch(server_name="0.0.0.0", server_port=7867)

classifier.py

@@ -0,0 +1,179 @@
+"""
+EEG Motor Imagery Classifier Module
+----------------------------------
+Handles model loading, inference, and real-time prediction for motor imagery classification.
+Based on the ShallowFBCSPNet architecture from the original eeg_motor_imagery.py script.
+"""
+
+import torch
+import torch.nn as nn
+import numpy as np
+from braindecode.models import ShallowFBCSPNet
+from typing import Dict, Tuple, Optional
+import os
+from sklearn.metrics import accuracy_score
+from data_processor import EEGDataProcessor
+from config import DEMO_DATA_PATHS
+
+class MotorImageryClassifier:
+    """
+    Motor imagery classifier using ShallowFBCSPNet model.
+    """
+    
+    def __init__(self, model_path: str = "shallow_weights_all.pth"):
+        self.device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+        self.model = None
+        self.model_path = model_path
+        self.class_names = {
+            0: "left_hand",
+            1: "right_hand", 
+            2: "neutral",
+            3: "left_leg",
+            4: "tongue",
+            5: "right_leg"
+        }
+        self.is_loaded = False
+        
+    def load_model(self, n_chans: int, n_times: int, n_outputs: int = 6):
+        """Load the pre-trained ShallowFBCSPNet model."""
+        try:
+            self.model = ShallowFBCSPNet(
+                n_chans=n_chans,
+                n_outputs=n_outputs,
+                n_times=n_times,
+                final_conv_length="auto"
+            ).to(self.device)
+            
+            if os.path.exists(self.model_path):
+                try:
+                    state_dict = torch.load(self.model_path, map_location=self.device)
+                    self.model.load_state_dict(state_dict)
+                    self.model.eval()
+                    self.is_loaded = True
+                    print(f"✅ Pre-trained model loaded successfully from {self.model_path}")
+                except Exception as model_error:
+                    print(f"⚠️  Pre-trained model found but incompatible: {model_error}")
+                    print("🔄 Starting LOSO training with available EEG data...")
+                    self.is_loaded = False
+            else:
+                print(f"❌ Pre-trained model weights not found at {self.model_path}")
+                print("🔄 Starting LOSO training with available EEG data...")
+                self.is_loaded = False
+                
+        except Exception as e:
+            print(f"❌ Error loading model: {e}")
+            print("🔄 Starting LOSO training with available EEG data...")
+            self.is_loaded = False
+    
+    def get_model_status(self) -> str:
+        """Get current model status for user interface."""
+        if self.is_loaded:
+            return "✅ Pre-trained model loaded and ready"
+        else:
+            return "🔄 Using LOSO training (training new model from EEG data)"
+            
+    def predict(self, eeg_data: np.ndarray) -> Tuple[int, float, Dict[str, float]]:
+        """
+        Predict motor imagery class from EEG data.
+        
+        Args:
+            eeg_data: EEG data array of shape (n_channels, n_times)
+            
+        Returns:
+            predicted_class: Predicted class index
+            confidence: Confidence score
+            probabilities: Dictionary of class probabilities
+        """
+        if not self.is_loaded:
+            return self._fallback_loso_classification(eeg_data)
+            
+        # Ensure input is the right shape: (batch, channels, time)
+        if eeg_data.ndim == 2:
+            eeg_data = eeg_data[np.newaxis, ...]
+        
+        # Convert to tensor
+        x = torch.from_numpy(eeg_data.astype(np.float32)).to(self.device)
+        
+        with torch.no_grad():
+            output = self.model(x)
+            probabilities = torch.softmax(output, dim=1)
+            predicted_class = torch.argmax(probabilities, dim=1).cpu().numpy()[0]
+            confidence = probabilities.max().cpu().numpy()
+            
+            # Convert to dictionary
+            prob_dict = {
+                self.class_names[i]: probabilities[0, i].cpu().numpy()
+                for i in range(len(self.class_names))
+            }
+            
+        return predicted_class, confidence, prob_dict
+
+    def _fallback_loso_classification(self, eeg_data: np.ndarray) -> Tuple[int, float, Dict[str, float]]:
+        """
+        Fallback classification using LOSO (Leave-One-Session-Out) training.
+        Trains a model on available data when pre-trained model isn't available.
+        """
+        try:
+            print("🔄 No pre-trained model available. Training new model using LOSO method...")
+            print("⏳ This may take a moment - training on real EEG data...")
+            
+            # Initialize data processor
+            processor = EEGDataProcessor()
+            
+            # Check if demo data files exist
+            available_files = [f for f in DEMO_DATA_PATHS if os.path.exists(f)]
+            if len(available_files) < 2:
+                raise ValueError(f"Not enough data files for LOSO training. Need at least 2 files, found {len(available_files)}. "
+                               f"Available files: {available_files}")
+            
+            # Perform LOSO split (using first session as test)
+            X_train, y_train, X_test, y_test, session_info = processor.prepare_loso_split(
+                available_files, test_session_idx=0
+            )
+            
+            # Get data dimensions
+            n_chans = X_train.shape[1]
+            n_times = X_train.shape[2]
+            
+            # Create and train model
+            self.model = ShallowFBCSPNet(
+                n_chans=n_chans,
+                n_outputs=6,
+                n_times=n_times,
+                final_conv_length="auto"
+            ).to(self.device)
+            
+            # Simple training loop
+            optimizer = torch.optim.Adam(self.model.parameters(), lr=0.001)
+            criterion = nn.CrossEntropyLoss()
+            
+            # Convert training data to tensors
+            X_train_tensor = torch.from_numpy(X_train).float().to(self.device)
+            y_train_tensor = torch.from_numpy(y_train).long().to(self.device)
+            
+            # Quick training (just a few epochs for demo)
+            self.model.train()
+            for epoch in range(50):
+                optimizer.zero_grad()
+                outputs = self.model(X_train_tensor)
+                loss = criterion(outputs, y_train_tensor)
+                loss.backward()
+                optimizer.step()
+                
+                if epoch % 5 == 0:
+                    print(f"LOSO Training - Epoch {epoch}, Loss: {loss.item():.4f}")
+            
+            # Switch to evaluation mode
+            self.model.eval()
+            self.is_loaded = True
+            
+            print("✅ LOSO model trained successfully! Ready for classification.")
+            
+            # Now make prediction with the trained model
+            return self.predict(eeg_data)
+            
+        except Exception as e:
+            print(f"Error in LOSO training: {e}")
+            raise RuntimeError(f"Failed to initialize classifier. Neither pre-trained model nor LOSO training succeeded: {e}")
+    
+    

config.py

@@ -0,0 +1,93 @@
+"""
+Configuration settings for the EEG Motor Imagery Music Composer
+"""
+
+import os
+from pathlib import Path
+
+# Application settings
+APP_NAME = "EEG Motor Imagery Music Composer"
+VERSION = "1.0.0"
+
+# Data paths
+BASE_DIR = Path(__file__).parent
+DATA_DIR = BASE_DIR / "data"
+SOUND_DIR = BASE_DIR / "sounds"
+MODEL_DIR = BASE_DIR
+
+# Model settings
+MODEL_PATH = MODEL_DIR / "shallow_weights_all.pth"
+# Model architecture: Always uses ShallowFBCSPNet from braindecode
+# If pre-trained weights not found, will train using LOSO on available data
+
+# EEG Data settings
+SAMPLING_RATE = 200  # Hz
+EPOCH_DURATION = 1.5  # seconds
+N_CHANNELS = 19 # without ground and reference 19 electrodes
+N_CLASSES = 6 # or 4
+
+# Classification settings
+CONFIDENCE_THRESHOLD = 0.3  # Minimum confidence to add sound layer (lowered for testing)
+MAX_COMPOSITION_LAYERS = 6  # Maximum layers in composition
+
+# Sound settings
+SOUND_MAPPING = {
+    "left_hand": "1_SoundHelix-Song-6_(Bass).wav",
+    "right_hand": "1_SoundHelix-Song-6_(Drums).wav", 
+    "neutral": None,  # No sound for neutral/rest state
+    "left_leg": "1_SoundHelix-Song-6_(Other).wav",
+    "tongue": "1_SoundHelix-Song-6_(Vocals).wav",
+    "right_leg": "1_SoundHelix-Song-6_(Bass).wav"  # Can be remapped by user
+}
+
+# Motor imagery class names
+CLASS_NAMES = {
+    0: "left_hand",
+    1: "right_hand", 
+    2: "neutral",
+    3: "left_leg",
+    4: "tongue",
+    5: "right_leg"
+}
+
+CLASS_DESCRIPTIONS = {
+    "left_hand": "🤚 Left Hand Movement",
+    "right_hand": "🤚 Right Hand Movement", 
+    "neutral": "😐 Neutral/Rest State",
+    "left_leg": "🦵 Left Leg Movement",
+    "tongue": "👅 Tongue Movement",
+    "right_leg": "🦵 Right Leg Movement"
+}
+
+# Demo data paths (optional) - updated with available files
+DEMO_DATA_PATHS = [
+    "data/raw_mat/HaLTSubjectA1602236StLRHandLegTongue.mat",
+    "data/raw_mat/HaLTSubjectA1603086StLRHandLegTongue.mat",
+    "data/raw_mat/HaLTSubjectA1603106StLRHandLegTongue.mat",
+]
+
+# Gradio settings
+GRADIO_PORT = 7860
+GRADIO_HOST = "0.0.0.0"
+GRADIO_SHARE = False  # Set to True to create public links
+
+# Logging settings
+LOG_LEVEL = "INFO"
+LOG_FILE = BASE_DIR / "logs" / "app.log"
+
+# Create necessary directories
+def create_directories():
+    """Create necessary directories if they don't exist."""
+    directories = [
+        DATA_DIR,
+        SOUND_DIR,
+        MODEL_DIR,
+        LOG_FILE.parent
+    ]
+    
+    for directory in directories:
+        directory.mkdir(parents=True, exist_ok=True)
+        
+if __name__ == "__main__":
+    create_directories()
+    print("Configuration directories created successfully!")

data_processor.py

@@ -0,0 +1,257 @@
+"""
+EEG Data Processing Module
+-------------------------
+Handles EEG data loading, preprocessing, and epoching for real-time classification.
+Adapted from the original eeg_motor_imagery.py script.
+"""
+
+import scipy.io
+import numpy as np
+import mne
+import torch
+import pandas as pd
+from typing import List, Tuple, Dict, Optional
+from pathlib import Path
+from scipy.signal import butter, lfilter
+
+class EEGDataProcessor:
+    """
+    Processes EEG data from .mat files for motor imagery classification.
+    """
+    
+    def __init__(self):
+        self.fs = None
+        self.ch_names = None
+        self.event_id = {
+            "left_hand": 1,
+            "right_hand": 2,
+            "neutral": 3,
+            "left_leg": 4,
+            "tongue": 5,
+            "right_leg": 6,
+        }
+        
+    def load_mat_file(self, file_path: str) -> Tuple[np.ndarray, np.ndarray, List[str], int]:
+        """Load and parse a single .mat EEG file."""
+        mat = scipy.io.loadmat(file_path)
+        content = mat['o'][0, 0]
+
+        labels = content[4].flatten()
+        signals = content[5]
+        chan_names_raw = content[6]
+        channels = [ch[0][0] for ch in chan_names_raw]
+        fs = int(content[2][0, 0])
+
+        return signals, labels, channels, fs
+    
+    def create_raw_object(self, signals: np.ndarray, channels: List[str], fs: int, 
+                         drop_ground_electrodes: bool = True) -> mne.io.RawArray:
+        """Create MNE Raw object from signal data."""
+        df = pd.DataFrame(signals, columns=channels)
+        
+        if drop_ground_electrodes:
+            # Drop auxiliary channels that should be excluded
+            aux_exclude = ('X3', 'X5')
+            columns_to_drop = [ch for ch in channels if ch in aux_exclude]
+            
+            df = df.drop(columns=columns_to_drop, errors="ignore")
+            print(f"Dropped auxiliary channels {columns_to_drop}. Remaining channels: {len(df.columns)}")
+        
+        eeg = df.values.T
+        ch_names = df.columns.tolist()
+        
+        self.ch_names = ch_names
+        self.fs = fs
+
+        info = mne.create_info(ch_names=ch_names, sfreq=fs, ch_types="eeg")
+        raw = mne.io.RawArray(eeg, info)
+        
+        return raw
+    
+    def extract_events(self, labels: np.ndarray) -> np.ndarray:
+        """Extract events from label array."""
+        onsets = np.where((labels[1:] != 0) & (labels[:-1] == 0))[0] + 1
+        event_codes = labels[onsets].astype(int)
+        events = np.c_[onsets, np.zeros_like(onsets), event_codes]
+        
+        # Keep only relevant events
+        mask = np.isin(events[:, 2], np.arange(1, 7))
+        events = events[mask]
+        
+        return events
+    
+    def create_epochs(self, raw: mne.io.RawArray, events: np.ndarray, 
+                     tmin: float = 0, tmax: float = 1.5) -> mne.Epochs:
+        """Create epochs from raw data and events."""
+        epochs = mne.Epochs(
+            raw,
+            events=events,
+            event_id=self.event_id,
+            tmin=tmin,
+            tmax=tmax,
+            baseline=None,
+            preload=True,
+        )
+        
+        return epochs
+    
+    def process_files(self, file_paths: List[str]) -> Tuple[np.ndarray, np.ndarray]:
+        """Process multiple EEG files and return combined data."""
+        all_epochs = []
+        
+        for file_path in file_paths:
+            signals, labels, channels, fs = self.load_mat_file(file_path)
+            raw = self.create_raw_object(signals, channels, fs, drop_ground_electrodes=True)
+            events = self.extract_events(labels)
+            epochs = self.create_epochs(raw, events)
+            all_epochs.append(epochs)
+        
+        if len(all_epochs) > 1:
+            epochs_combined = mne.concatenate_epochs(all_epochs)
+        else:
+            epochs_combined = all_epochs[0]
+        
+        # Convert to arrays for model input
+        X = epochs_combined.get_data().astype("float32")
+        y = (epochs_combined.events[:, -1] - 1).astype("int64")  # classes 0..5
+        
+        return X, y
+    
+    def load_continuous_data(self, file_paths: List[str]) -> Tuple[np.ndarray, int]:
+        """
+        Load continuous raw EEG data without epoching.
+        
+        Args:
+            file_paths: List of .mat file paths
+            
+        Returns:
+            raw_data: Continuous EEG data [n_channels, n_timepoints]
+            fs: Sampling frequency
+        """
+        all_raw_data = []
+        
+        for file_path in file_paths:
+            signals, labels, channels, fs = self.load_mat_file(file_path)
+            raw = self.create_raw_object(signals, channels, fs, drop_ground_electrodes=True)
+            
+            # Extract continuous data (no epoching)
+            continuous_data = raw.get_data()  # [n_channels, n_timepoints]
+            all_raw_data.append(continuous_data)
+        
+        # Concatenate all continuous data along time axis
+        if len(all_raw_data) > 1:
+            combined_raw = np.concatenate(all_raw_data, axis=1)
+        else:
+            combined_raw = all_raw_data[0]
+            
+        return combined_raw, fs
+    
+    def prepare_loso_split(self, file_paths: List[str], test_subject_idx: int = 0) -> Tuple:
+        """
+        Prepare Leave-One-Subject-Out (LOSO) split for EEG data.
+        
+        Args:
+            file_paths: List of .mat file paths (one per subject)
+            test_subject_idx: Index of subject to use for testing
+            
+        Returns:
+            X_train, y_train, X_test, y_test, subject_info
+        """
+        all_subjects_data = []
+        subject_info = []
+        
+        # Load each subject separately
+        for i, file_path in enumerate(file_paths):
+            signals, labels, channels, fs = self.load_mat_file(file_path)
+            raw = self.create_raw_object(signals, channels, fs, drop_ground_electrodes=True)
+            events = self.extract_events(labels)
+            epochs = self.create_epochs(raw, events)
+            
+            # Convert to arrays
+            X_subject = epochs.get_data().astype("float32")
+            y_subject = (epochs.events[:, -1] - 1).astype("int64")
+            
+            all_subjects_data.append((X_subject, y_subject))
+            subject_info.append({
+                'file_path': file_path,
+                'subject_id': f"Subject_{i+1}",
+                'n_epochs': len(X_subject),
+                'channels': channels,
+                'fs': fs
+            })
+        
+        # LOSO split: one subject for test, others for train
+        test_subject = all_subjects_data[test_subject_idx]
+        train_subjects = [all_subjects_data[i] for i in range(len(all_subjects_data)) if i != test_subject_idx]
+        
+        # Combine training subjects
+        if len(train_subjects) > 1:
+            X_train = np.concatenate([subj[0] for subj in train_subjects], axis=0)
+            y_train = np.concatenate([subj[1] for subj in train_subjects], axis=0)
+        else:
+            X_train, y_train = train_subjects[0]
+        
+        X_test, y_test = test_subject
+        
+        print("LOSO Split:")
+        print(f"  Test Subject: {subject_info[test_subject_idx]['subject_id']} ({len(X_test)} epochs)")
+        print(f"  Train Subjects: {len(train_subjects)} subjects ({len(X_train)} epochs)")
+        
+        return X_train, y_train, X_test, y_test, subject_info
+    
+    def simulate_real_time_data(self, X: np.ndarray, y: np.ndarray, mode: str = "random") -> Tuple[np.ndarray, int]:
+        """
+        Simulate real-time EEG data for demo purposes.
+        
+        Args:
+            X: EEG data array (currently epoched data)
+            y: Labels array  
+            mode: "random", "sequential", or "class_balanced"
+            
+        Returns:
+            Single epoch and its true label
+        """
+        if mode == "random":
+            idx = np.random.randint(0, len(X))
+        elif mode == "sequential":
+            # Use a counter for sequential sampling (would need to store state)
+            idx = np.random.randint(0, len(X))  # Simplified for now
+        elif mode == "class_balanced":
+            # Sample ensuring we get different classes
+            available_classes = np.unique(y)
+            target_class = np.random.choice(available_classes)
+            class_indices = np.where(y == target_class)[0]
+            idx = np.random.choice(class_indices)
+        else:
+            idx = np.random.randint(0, len(X))
+            
+        return X[idx], y[idx]
+    
+    def simulate_continuous_stream(self, raw_data: np.ndarray, fs: int, window_size: float = 1.5) -> np.ndarray:
+        """
+        Simulate continuous EEG stream by extracting sliding windows from raw data.
+        
+        Args:
+            raw_data: Continuous EEG data [n_channels, n_timepoints]
+            fs: Sampling frequency
+            window_size: Window size in seconds
+            
+        Returns:
+            Single window of EEG data [n_channels, window_samples]
+        """
+        window_samples = int(window_size * fs)  # e.g., 1.5s * 200Hz = 300 samples
+        
+        # Ensure we don't go beyond the data
+        max_start = raw_data.shape[1] - window_samples
+        if max_start <= 0:
+            return raw_data  # Return full data if too short
+        
+        # Random starting point in the continuous stream
+        start_idx = np.random.randint(0, max_start)
+        end_idx = start_idx + window_samples
+        
+        # Extract window
+        window = raw_data[:, start_idx:end_idx]
+        
+        return window
+

demo.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+"""
+Demo script for the EEG Motor Imagery Music Composer
+"""
+
+import sys
+import os
+from pathlib import Path
+
+# Add the current directory to Python path
+current_dir = Path(__file__).parent
+sys.path.insert(0, str(current_dir))
+
+from data_processor import EEGDataProcessor
+from classifier import MotorImageryClassifier
+from sound_library import SoundManager
+from utils import setup_logging, create_classification_summary
+import numpy as np
+
+def run_demo():
+    """Run a simple demo of the system components."""
+    print("🧠 EEG Motor Imagery Music Composer - Demo")
+    print("=" * 50)
+    
+    # Initialize components
+    print("Initializing components...")
+    data_processor = EEGDataProcessor()
+    classifier = MotorImageryClassifier()
+    sound_manager = SoundManager()
+    
+    # Create mock data for demo
+    print("Creating mock EEG data...")
+    mock_data = np.random.randn(10, 32, 384).astype(np.float32)  # 10 samples, 32 channels, 384 time points
+    mock_labels = np.random.randint(0, 6, 10)
+    
+    # Initialize classifier
+    print("Loading classifier...")
+    classifier.load_model(n_chans=32, n_times=384)
+    
+    print(f"Available sounds: {sound_manager.get_available_sounds()}")
+    print()
+    
+    # Run classification demo
+    print("Running classification demo...")
+    print("-" * 30)
+    
+    for i in range(5):
+        # Get random sample
+        sample_idx = np.random.randint(0, len(mock_data))
+        eeg_sample = mock_data[sample_idx]
+        true_label = mock_labels[sample_idx]
+        
+        # Classify
+        predicted_class, confidence, probabilities = classifier.predict(eeg_sample)
+        predicted_name = classifier.class_names[predicted_class]
+        true_name = classifier.class_names[true_label]
+        
+        # Create summary
+        summary = create_classification_summary(predicted_name, confidence, probabilities)
+        
+        print(f"Sample {i+1}:")
+        print(f"  True class: {true_name}")
+        print(f"  Predicted: {summary['emoji']} {predicted_name} ({summary['confidence_percent']})")
+        
+        # Add to composition if confidence is high
+        if confidence > 0.7 and predicted_name != 'neutral':
+            sound_manager.add_layer(predicted_name, confidence)
+            print(f"  ♪ Added to composition: {predicted_name}")
+        else:
+            print(f"  - Not added (low confidence or neutral)")
+        
+        print()
+    
+    # Show composition summary
+    composition_info = sound_manager.get_composition_info()
+    print("Final Composition:")
+    print("-" * 20)
+    if composition_info:
+        for i, layer in enumerate(composition_info, 1):
+            print(f"{i}. {layer['class']} (confidence: {layer['confidence']:.2f})")
+    else:
+        print("No composition layers created")
+    
+    print()
+    print("Demo completed! 🎵")
+    print("To run the full Gradio interface, execute: python app.py")
+
+if __name__ == "__main__":
+    try:
+        run_demo()
+    except KeyboardInterrupt:
+        print("\nDemo interrupted by user")
+    except Exception as e:
+        print(f"Error running demo: {e}")
+        import traceback
+        traceback.print_exc()

enhanced_utils.py

@@ -0,0 +1,236 @@
+"""
+Enhanced utilities incorporating useful functions from the original src/ templates
+"""
+
+import torch
+import numpy as np
+import matplotlib.pyplot as plt
+import seaborn as sns
+from sklearn.metrics import confusion_matrix, classification_report, accuracy_score
+from typing import Dict, List, Tuple, Optional
+import logging
+
+def evaluate_model_performance(model, dataloader, device, class_names: List[str]) -> Dict:
+    """
+    Comprehensive model evaluation with metrics and visualizations.
+    Enhanced version of src/evaluate.py
+    """
+    model.eval()
+    all_preds = []
+    all_labels = []
+    all_probs = []
+
+    with torch.no_grad():
+        for inputs, labels in dataloader:
+            inputs = inputs.to(device)
+            labels = labels.to(device)
+
+            outputs = model(inputs)
+            probs = torch.softmax(outputs, dim=1)
+            _, preds = torch.max(outputs, 1)
+            
+            all_preds.extend(preds.cpu().numpy())
+            all_labels.extend(labels.cpu().numpy())
+            all_probs.extend(probs.cpu().numpy())
+
+    # Calculate metrics
+    accuracy = accuracy_score(all_labels, all_preds)
+    cm = confusion_matrix(all_labels, all_preds)
+    report = classification_report(all_labels, all_preds, target_names=class_names, output_dict=True)
+    
+    return {
+        'accuracy': accuracy,
+        'predictions': all_preds,
+        'labels': all_labels,
+        'probabilities': all_probs,
+        'confusion_matrix': cm,
+        'classification_report': report
+    }
+
+def plot_confusion_matrix(cm: np.ndarray, class_names: List[str], title: str = "Confusion Matrix") -> plt.Figure:
+    """
+    Plot confusion matrix with proper formatting.
+    Enhanced version from src/visualize.py
+    """
+    fig, ax = plt.subplots(figsize=(8, 6))
+    
+    sns.heatmap(cm, annot=True, fmt='d', cmap='Blues', 
+                xticklabels=class_names, yticklabels=class_names, ax=ax)
+    
+    ax.set_title(title)
+    ax.set_ylabel('True Label')
+    ax.set_xlabel('Predicted Label')
+    
+    plt.tight_layout()
+    return fig
+
+def plot_classification_probabilities(probabilities: np.ndarray, class_names: List[str], 
+                                    sample_indices: Optional[List[int]] = None) -> plt.Figure:
+    """
+    Plot classification probabilities for selected samples.
+    """
+    if sample_indices is None:
+        sample_indices = list(range(min(10, len(probabilities))))
+    
+    fig, ax = plt.subplots(figsize=(12, 6))
+    
+    x = np.arange(len(class_names))
+    width = 0.8 / len(sample_indices)
+    
+    for i, sample_idx in enumerate(sample_indices):
+        offset = (i - len(sample_indices)/2) * width
+        ax.bar(x + offset, probabilities[sample_idx], width, 
+               label=f'Sample {sample_idx}', alpha=0.8)
+    
+    ax.set_xlabel('Motor Imagery Classes')
+    ax.set_ylabel('Probability')
+    ax.set_title('Classification Probabilities')
+    ax.set_xticks(x)
+    ax.set_xticklabels(class_names, rotation=45)
+    ax.legend()
+    ax.grid(True, alpha=0.3)
+    
+    plt.tight_layout()
+    return fig
+
+def plot_training_history(history: Dict[str, List[float]]) -> plt.Figure:
+    """
+    Plot training history (loss and accuracy).
+    Enhanced version from src/visualize.py
+    """
+    fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(15, 5))
+    
+    # Plot accuracy
+    if 'train_accuracy' in history and 'val_accuracy' in history:
+        ax1.plot(history['train_accuracy'], label='Train', linewidth=2)
+        ax1.plot(history['val_accuracy'], label='Validation', linewidth=2)
+        ax1.set_title('Model Accuracy')
+        ax1.set_xlabel('Epoch')
+        ax1.set_ylabel('Accuracy')
+        ax1.legend()
+        ax1.grid(True, alpha=0.3)
+    
+    # Plot loss
+    if 'train_loss' in history and 'val_loss' in history:
+        ax2.plot(history['train_loss'], label='Train', linewidth=2)
+        ax2.plot(history['val_loss'], label='Validation', linewidth=2)
+        ax2.set_title('Model Loss')
+        ax2.set_xlabel('Epoch')
+        ax2.set_ylabel('Loss')
+        ax2.legend()
+        ax2.grid(True, alpha=0.3)
+    
+    plt.tight_layout()
+    return fig
+
+def plot_eeg_channels(eeg_data: np.ndarray, channel_names: Optional[List[str]] = None, 
+                     sample_rate: int = 256, title: str = "EEG Channels") -> plt.Figure:
+    """
+    Plot multiple EEG channels.
+    Enhanced visualization for EEG data.
+    """
+    n_channels, n_samples = eeg_data.shape
+    time_axis = np.arange(n_samples) / sample_rate
+    
+    # Determine subplot layout
+    n_rows = int(np.ceil(np.sqrt(n_channels)))
+    n_cols = int(np.ceil(n_channels / n_rows))
+    
+    fig, axes = plt.subplots(n_rows, n_cols, figsize=(15, 10))
+    if n_channels == 1:
+        axes = [axes]
+    else:
+        axes = axes.flatten()
+    
+    for i in range(n_channels):
+        ax = axes[i]
+        ax.plot(time_axis, eeg_data[i], 'b-', linewidth=1)
+        
+        channel_name = channel_names[i] if channel_names else f'Channel {i+1}'
+        ax.set_title(channel_name)
+        ax.set_xlabel('Time (s)')
+        ax.set_ylabel('Amplitude')
+        ax.grid(True, alpha=0.3)
+    
+    # Hide unused subplots
+    for i in range(n_channels, len(axes)):
+        axes[i].set_visible(False)
+    
+    plt.suptitle(title)
+    plt.tight_layout()
+    return fig
+
+class EarlyStopping:
+    """
+    Early stopping utility from src/types/index.py
+    """
+    def __init__(self, patience=7, min_delta=0, restore_best_weights=True, verbose=False):
+        self.patience = patience
+        self.min_delta = min_delta
+        self.restore_best_weights = restore_best_weights
+        self.verbose = verbose
+        self.best_loss = None
+        self.counter = 0
+        self.best_weights = None
+
+    def __call__(self, val_loss, model):
+        if self.best_loss is None:
+            self.best_loss = val_loss
+            self.save_checkpoint(model)
+        elif val_loss < self.best_loss - self.min_delta:
+            self.best_loss = val_loss
+            self.counter = 0
+            self.save_checkpoint(model)
+        else:
+            self.counter += 1
+
+        if self.counter >= self.patience:
+            if self.verbose:
+                print(f'Early stopping triggered after {self.counter} epochs of no improvement')
+            if self.restore_best_weights:
+                model.load_state_dict(self.best_weights)
+            return True
+        return False
+
+    def save_checkpoint(self, model):
+        """Save model when validation loss decreases."""
+        if self.restore_best_weights:
+            self.best_weights = model.state_dict().copy()
+
+def create_enhanced_evaluation_report(model, test_loader, class_names: List[str], 
+                                    device, save_plots: bool = True) -> Dict:
+    """
+    Create a comprehensive evaluation report with plots and metrics.
+    """
+    # Get evaluation results
+    results = evaluate_model_performance(model, test_loader, device, class_names)
+    
+    # Create visualizations
+    plots = {}
+    
+    # Confusion Matrix
+    plots['confusion_matrix'] = plot_confusion_matrix(
+        results['confusion_matrix'], class_names, 
+        title="Motor Imagery Classification - Confusion Matrix"
+    )
+    
+    # Classification Probabilities (sample)
+    plots['probabilities'] = plot_classification_probabilities(
+        np.array(results['probabilities']), class_names, 
+        sample_indices=list(range(min(5, len(results['probabilities']))))
+    )
+    
+    if save_plots:
+        for plot_name, fig in plots.items():
+            fig.savefig(f'{plot_name}.png', dpi=300, bbox_inches='tight')
+    
+    return {
+        'metrics': results,
+        'plots': plots,
+        'summary': {
+            'accuracy': results['accuracy'],
+            'n_samples': len(results['labels']),
+            'n_classes': len(class_names),
+            'class_names': class_names
+        }
+    }

requirements.txt

@@ -0,0 +1,14 @@
+gradio
+pandas
+numpy
+scipy
+matplotlib
+torch
+torchvision
+mne
+braindecode
+scikit-learn
+pydub
+soundfile
+librosa
+threading

sound_library.py

@@ -0,0 +1,783 @@
+"""
+Sound Management System for EEG Motor Imagery Classification
+-----------------------------------------------------------
+Handles sound mapping, layering, and music composition based on motor imagery predictions.
+Uses local SoundHelix audio files for different motor imagery classes.
+"""
+
+import numpy as np
+import soundfile as sf
+import os
+from typing import Dict, List, Optional, Tuple
+import threading
+import time
+from pathlib import Path
+import tempfile
+
+# Professional audio effects processor using scipy and librosa
+from scipy import signal
+import librosa
+
+class AudioEffectsProcessor:
+    """Professional audio effects for DJ mode using scipy and librosa."""
+    
+    @staticmethod
+    def apply_volume_fade(data: np.ndarray, fade_type: str = "out", fade_length: float = 0.5) -> np.ndarray:
+        """Apply volume fade effect with linear fade in/out."""
+        try:
+            samples = len(data)
+            fade_samples = int(fade_length * samples)
+            
+            if fade_type == "out":
+                # Fade out: linear decrease from 1.0 to 0.3
+                fade_curve = np.linspace(1.0, 0.3, fade_samples)
+                data[-fade_samples:] *= fade_curve
+            elif fade_type == "in":
+                # Fade in: linear increase from 0.3 to 1.0
+                fade_curve = np.linspace(0.3, 1.0, fade_samples)
+                data[:fade_samples] *= fade_curve
+            
+            return data
+        except Exception as e:
+            print(f"Volume fade effect failed: {e}")
+            return data
+    
+    @staticmethod
+    def apply_high_pass_filter(data: np.ndarray, samplerate: int, cutoff: float = 800.0) -> np.ndarray:
+        """Apply high-pass filter to emphasize highs and cut lows."""
+        try:
+            # Design butterworth high-pass filter
+            nyquist = samplerate / 2
+            normalized_cutoff = cutoff / nyquist
+            b, a = signal.butter(4, normalized_cutoff, btype='high', analog=False)
+            
+            # Apply filter
+            filtered_data = signal.filtfilt(b, a, data)
+            return filtered_data
+        except Exception as e:
+            print(f"High-pass filter failed: {e}")
+            return data
+    
+    @staticmethod
+    def apply_low_pass_filter(data: np.ndarray, samplerate: int, cutoff: float = 1200.0) -> np.ndarray:
+        """Apply low-pass filter to emphasize lows and cut highs."""
+        try:
+            # Design butterworth low-pass filter
+            nyquist = samplerate / 2
+            normalized_cutoff = cutoff / nyquist
+            b, a = signal.butter(4, normalized_cutoff, btype='low', analog=False)
+            
+            # Apply filter
+            filtered_data = signal.filtfilt(b, a, data)
+            return filtered_data
+        except Exception as e:
+            print(f"Low-pass filter failed: {e}")
+            return data
+    
+    @staticmethod
+    def apply_reverb(data: np.ndarray, samplerate: int, room_size: float = 0.5) -> np.ndarray:
+        """Apply simple reverb effect using delay and feedback."""
+        try:
+            # Simple reverb using multiple delayed copies
+            delay_samples = int(0.1 * samplerate)  # 100ms delay
+            decay = 0.3 * room_size
+            
+            # Create reverb buffer
+            reverb_data = np.copy(data)
+            
+            # Add delayed copies with decay
+            for i in range(3):
+                delay = delay_samples * (i + 1)
+                if delay < len(data):
+                    gain = decay ** (i + 1)
+                    reverb_data[delay:] += data[:-delay] * gain
+            
+            # Mix original with reverb
+            return 0.7 * data + 0.3 * reverb_data
+        except Exception as e:
+            print(f"Reverb effect failed: {e}")
+            return data
+    
+    @staticmethod
+    def apply_bass_boost(data: np.ndarray, samplerate: int, boost_db: float = 6.0) -> np.ndarray:
+        """Apply bass boost using low-frequency shelving filter."""
+        try:
+            # Design low-shelf filter for bass boost
+            freq = 250.0  # Bass frequency cutoff
+            nyquist = samplerate / 2
+            normalized_freq = freq / nyquist
+            
+            # Convert dB to linear gain
+            gain = 10 ** (boost_db / 20)
+            
+            # Simple bass boost: amplify low frequencies
+            b, a = signal.butter(2, normalized_freq, btype='low', analog=False)
+            low_freq = signal.filtfilt(b, a, data)
+            
+            # Mix boosted lows with original
+            boosted_data = data + (low_freq * (gain - 1))
+            
+            # Normalize to prevent clipping
+            max_val = np.max(np.abs(boosted_data))
+            if max_val > 0.95:
+                boosted_data = boosted_data * 0.95 / max_val
+            
+            return boosted_data
+        except Exception as e:
+            print(f"Bass boost failed: {e}")
+            return data
+    
+    @staticmethod
+    def process_with_effects(audio_file: str, active_effects: Dict[str, bool]) -> str:
+        """Process audio file with active effects and return processed version."""
+        try:
+            # Check if audio_file is valid
+            if not audio_file or not os.path.exists(audio_file):
+                print(f"Invalid audio file: {audio_file}")
+                return audio_file
+            
+            # Read audio file
+            data, samplerate = sf.read(audio_file)
+            
+            # Handle stereo to mono conversion if needed
+            if len(data.shape) > 1:
+                data = np.mean(data, axis=1)
+            
+            # Apply effects based on active states
+            processed_data = np.copy(data)
+            effect_names = []
+            
+            if active_effects.get("left_hand", False):  # Volume Fade
+                processed_data = AudioEffectsProcessor.apply_volume_fade(processed_data, "out")
+                effect_names.append("fade")
+            
+            if active_effects.get("right_hand", False):  # High Pass Filter
+                processed_data = AudioEffectsProcessor.apply_high_pass_filter(processed_data, samplerate)
+                effect_names.append("hpf")
+            
+            if active_effects.get("left_leg", False):  # Reverb
+                processed_data = AudioEffectsProcessor.apply_reverb(processed_data, samplerate)
+                effect_names.append("rev")
+            
+            if active_effects.get("right_leg", False):  # Low Pass Filter
+                processed_data = AudioEffectsProcessor.apply_low_pass_filter(processed_data, samplerate)
+                effect_names.append("lpf")
+            
+            if active_effects.get("tongue", False):  # Bass Boost
+                processed_data = AudioEffectsProcessor.apply_bass_boost(processed_data, samplerate)
+                effect_names.append("bass")
+            
+            # Create unique filename based on active effects
+            base_name = os.path.splitext(audio_file)[0]
+            effects_suffix = "_".join(effect_names) if effect_names else "clean"
+            processed_file = f"{base_name}_fx_{effects_suffix}.wav"
+            
+            # Save processed audio
+            # sf.write(processed_file, processed_data, samplerate)
+            print(f"🎛️ Audio processed with effects: {effects_suffix} (FILE SAVING DISABLED)")
+            
+            # Return absolute path (using original file since saving is disabled)
+            return os.path.abspath(audio_file)
+            
+        except Exception as e:
+            print(f"Audio processing failed: {e}")
+            return os.path.abspath(audio_file) if audio_file else None
+
+class SoundManager:
+    """
+    Manages cyclic sound composition for motor imagery classification.
+    Supports full-cycle composition with user-customizable movement-sound mappings.
+    """
+    
+    def __init__(self, sound_dir: str = "sounds", include_neutral_in_cycle: bool = False):
+        self.sound_dir = Path(sound_dir)
+        self.include_neutral_in_cycle = include_neutral_in_cycle
+        
+        # Composition state
+        self.composition_layers = []  # All layers across all cycles
+        self.current_cycle = 0
+        self.current_step = 0  # Current step within cycle (0-5)
+        self.cycle_complete = False
+        self.completed_cycles = 0  # Track completed cycles for session management
+        self.max_cycles = 2  # Rehabilitation session limit
+        
+        # DJ Effects phase management
+        self.current_phase = "building"  # "building" or "dj_effects"
+        self.mixed_composition_file = None  # Path to current mixed composition
+        self.active_effects = {  # Track which effects are currently active
+            "left_hand": False,    # Volume fade
+            "right_hand": False,   # Filter sweep
+            "left_leg": False,     # Reverb
+            "right_leg": False,    # Tempo modulation  
+            "tongue": False        # Bass boost
+        }
+        
+        # All possible movements (neutral is optional for composition)
+        self.all_movements = ["left_hand", "right_hand", "neutral", "left_leg", "tongue", "right_leg"]
+        
+        # Active movements that contribute to composition (excluding neutral)
+        self.active_movements = ["left_hand", "right_hand", "left_leg", "tongue", "right_leg"]
+        
+        # Current cycle's random movement sequence (shuffled each cycle)
+        self.current_movement_sequence = []
+        self.movements_completed = set()  # Track which movements have been successfully completed
+        self._generate_new_sequence()
+        
+        # User-customizable sound mapping (can be updated after each cycle)
+        self.current_sound_mapping = {
+            "left_hand": "1_SoundHelix-Song-6_(Bass).wav",
+            "right_hand": "1_SoundHelix-Song-6_(Drums).wav", 
+            "neutral": None,  # No sound for neutral/rest state
+            "left_leg": "1_SoundHelix-Song-6_(Other).wav",
+            "tongue": "1_SoundHelix-Song-6_(Vocals).wav",
+            "right_leg": "1_SoundHelix-Song-6_(Bass).wav"  # Can be remapped
+        }
+        
+        # Available sound files
+        self.available_sounds = [
+            "1_SoundHelix-Song-6_(Bass).wav",
+            "1_SoundHelix-Song-6_(Drums).wav", 
+            "1_SoundHelix-Song-6_(Other).wav",
+            "1_SoundHelix-Song-6_(Vocals).wav"
+        ]
+        
+        # Load sound files
+        self.loaded_sounds = {}
+        self._load_sound_files()
+        
+        # Cycle statistics
+        self.cycle_stats = {
+            'total_cycles': 0,
+            'successful_classifications': 0,
+            'total_attempts': 0
+        }
+        
+    def _load_sound_files(self):
+        """Load all available sound files into memory."""
+        for class_name, filename in self.current_sound_mapping.items():
+            if filename is None:
+                continue
+                
+            file_path = self.sound_dir / filename
+            if file_path.exists():
+                try:
+                    data, sample_rate = sf.read(str(file_path))
+                    self.loaded_sounds[class_name] = {
+                        'data': data,
+                        'sample_rate': sample_rate,
+                        'file_path': str(file_path)
+                    }
+                    print(f"Loaded sound for {class_name}: {filename}")
+                except Exception as e:
+                    print(f"Error loading {filename}: {e}")
+            else:
+                print(f"Sound file not found: {file_path}")
+    
+    def get_sound_for_class(self, class_name: str) -> Optional[Dict]:
+        """Get sound data for a specific motor imagery class."""
+        return self.loaded_sounds.get(class_name)
+    
+    def _generate_new_sequence(self):
+        """Generate a new random sequence of movements for the current cycle."""
+        import random
+        # Choose which movements to include based on configuration
+        movements_for_cycle = self.all_movements.copy() if self.include_neutral_in_cycle else self.active_movements.copy()
+        random.shuffle(movements_for_cycle)
+        self.current_movement_sequence = movements_for_cycle
+        self.movements_completed = set()
+        
+        cycle_size = len(movements_for_cycle)
+        print(f"🎯 New random sequence ({cycle_size} movements): {' → '.join([m.replace('_', ' ').title() for m in self.current_movement_sequence])}")
+    
+    def get_current_target_movement(self) -> str:
+        """Get the current movement the user should imagine."""
+        if self.current_step < len(self.current_movement_sequence):
+            return self.current_movement_sequence[self.current_step]
+        return "cycle_complete"
+    
+    def get_next_random_movement(self) -> str:
+        """Get a random movement from those not yet completed in this cycle."""
+        # Use the same movement set as the current cycle
+        cycle_movements = self.all_movements if self.include_neutral_in_cycle else self.active_movements
+        remaining_movements = [m for m in cycle_movements if m not in self.movements_completed]
+        if not remaining_movements:
+            return "cycle_complete"
+        
+        import random
+        return random.choice(remaining_movements)
+    
+    def process_classification(self, predicted_class: str, confidence: float, threshold: float = 0.7) -> Dict:
+        """
+        Process a classification result in the context of the current cycle.
+        Uses random movement prompting - user can choose any movement at any time.
+        
+        Args:
+            predicted_class: The predicted motor imagery class
+            confidence: Confidence score
+            threshold: Minimum confidence to add sound layer
+            
+        Returns:
+            Dictionary with processing results and next action
+        """
+        self.cycle_stats['total_attempts'] += 1
+        
+        # Check if this movement was already completed in this cycle
+        already_completed = predicted_class in self.movements_completed
+        
+        result = {
+            'predicted_class': predicted_class,
+            'confidence': confidence,
+            'above_threshold': confidence >= threshold,
+            'already_completed': already_completed,
+            'sound_added': False,
+            'cycle_complete': False,
+            'next_action': 'continue',
+            'movements_remaining': len(self.current_movement_sequence) - len(self.movements_completed),
+            'movements_completed': list(self.movements_completed)
+        }
+        
+        # Check if prediction is above threshold and not already completed
+        if result['above_threshold'] and not already_completed:
+            # Get sound file for this movement
+            sound_file = self.current_sound_mapping.get(predicted_class)
+            
+            if sound_file is None:
+                # No sound for this movement (e.g., neutral), but still count as completed
+                self.movements_completed.add(predicted_class)
+                result['sound_added'] = False  # No sound, but movement completed
+                self.cycle_stats['successful_classifications'] += 1
+                cycle_size = len(self.current_movement_sequence)
+                print(f"✓ Cycle {self.current_cycle+1}: {predicted_class} completed (no sound) ({len(self.movements_completed)}/{cycle_size} complete)")
+            elif predicted_class in self.loaded_sounds:
+                # Add sound layer
+                layer_info = {
+                    'cycle': self.current_cycle,
+                    'step': len(self.movements_completed),  # Step based on number completed
+                    'movement': predicted_class,
+                    'sound_file': sound_file,
+                    'confidence': confidence,
+                    'timestamp': time.time(),
+                    'sound_data': self.loaded_sounds[predicted_class]
+                }
+                self.composition_layers.append(layer_info)
+                self.movements_completed.add(predicted_class)
+                result['sound_added'] = True
+                
+                print(f"DEBUG: Added layer {len(self.composition_layers)}, total layers now: {len(self.composition_layers)}")
+                print(f"DEBUG: Composition layers: {[layer['movement'] for layer in self.composition_layers]}")
+                
+                # Return individual sound file for this classification
+                sound_path = os.path.join(self.sound_dir, sound_file)
+                result['audio_file'] = sound_path if os.path.exists(sound_path) else None
+                
+                # Also create mixed composition for potential saving (but don't return it)
+                mixed_file = self.get_current_mixed_composition()
+                result['mixed_composition'] = mixed_file
+                
+                self.cycle_stats['successful_classifications'] += 1
+                cycle_size = len(self.current_movement_sequence)
+                print(f"✓ Cycle {self.current_cycle+1}: Added {sound_file} for {predicted_class} ({len(self.movements_completed)}/{cycle_size} complete)")
+        
+        # Check if cycle is complete (all movements in current sequence completed)
+        cycle_movements = self.all_movements if self.include_neutral_in_cycle else self.active_movements
+        if len(self.movements_completed) >= len(cycle_movements):
+            result['cycle_complete'] = True
+            result['next_action'] = 'remap_sounds'
+            self.cycle_complete = True
+            cycle_size = len(cycle_movements)
+            print(f"🎵 Cycle {self.current_cycle+1} complete! All {cycle_size} movements successfully classified!")
+        
+        return result
+    
+    def start_new_cycle(self, new_sound_mapping: Dict[str, str] = None):
+        """Start a new composition cycle with optional new sound mapping."""
+        if new_sound_mapping:
+            self.current_sound_mapping.update(new_sound_mapping)
+            print(f"Updated sound mapping for cycle {self.current_cycle+2}")
+        
+        self.current_cycle += 1
+        self.current_step = 0
+        self.cycle_complete = False
+        self.cycle_stats['total_cycles'] += 1
+        
+        # Generate new random sequence for this cycle
+        self._generate_new_sequence()
+        
+        print(f"🔄 Starting Cycle {self.current_cycle+1}")
+        if self.current_cycle == 1:
+            print("💪 Let's create your first brain-music composition!")
+        elif self.current_cycle == 2:
+            print("� Great progress! Let's create your second composition!")
+        else:
+            print("�🎯 Imagine ANY movement - you can choose the order!")
+    
+    def should_end_session(self) -> bool:
+        """Check if the rehabilitation session should end after max cycles."""
+        return self.completed_cycles >= self.max_cycles
+    
+    def complete_current_cycle(self):
+        """Mark current cycle as complete and track progress."""
+        self.completed_cycles += 1
+        print(f"✅ Cycle {self.current_cycle} completed! ({self.completed_cycles}/{self.max_cycles} compositions finished)")
+    
+    def transition_to_dj_phase(self):
+        """Transition from building phase to DJ effects phase."""
+        if len(self.movements_completed) >= 5:  # All movements completed
+            self.current_phase = "dj_effects"
+            # Create mixed composition for DJ effects
+            self._create_mixed_composition()
+            print("🎵 Composition Complete! Transitioning to DJ Effects Phase...")
+            print("🎧 You are now the DJ! Use movements to control effects:")
+            print("   👈 Left Hand: Volume Fade")
+            print("   👉 Right Hand: High Pass Filter") 
+            print("   🦵 Left Leg: Reverb Effect")
+            print("   🦵 Right Leg: Low Pass Filter")
+            print("   👅 Tongue: Bass Boost")
+            return True
+        return False
+    
+    def _create_mixed_composition(self):
+        """Create a mixed audio file from all completed layers."""
+        try:
+            import hashlib
+            movement_hash = hashlib.md5(str(sorted(self.movements_completed)).encode()).hexdigest()[:8]
+            self.mixed_composition_file = os.path.abspath(f"mixed_composition_{movement_hash}.wav")
+            
+            # FILE SAVING DISABLED: Use existing base audio file instead
+            # Try to use the first available completed movement's audio file
+            for movement in self.movements_completed:
+                if movement in self.current_sound_mapping and self.current_sound_mapping[movement] is not None:
+                    sound_file = os.path.join(self.sound_dir, self.current_sound_mapping[movement])
+                    if os.path.exists(sound_file):
+                        self.mixed_composition_file = os.path.abspath(sound_file)
+                        print(f"📀 Using existing audio as mixed composition: {self.mixed_composition_file} (FILE SAVING DISABLED)")
+                        return
+            
+            # If file already exists, use it
+            if os.path.exists(self.mixed_composition_file):
+                print(f"📀 Using existing mixed composition: {self.mixed_composition_file}")
+                return
+            
+            # Create actual mixed composition by layering completed sounds
+            mixed_data = None
+            sample_rate = 44100  # Default sample rate
+            
+            for movement in self.movements_completed:
+                if movement in self.current_sound_mapping and self.current_sound_mapping[movement] is not None:
+                    sound_file = os.path.join(self.sound_dir, self.current_sound_mapping[movement])
+                    if os.path.exists(sound_file):
+                        try:
+                            data, sr = sf.read(sound_file)
+                            sample_rate = sr
+                            
+                            # Convert stereo to mono
+                            if len(data.shape) > 1:
+                                data = np.mean(data, axis=1)
+                            
+                            # Initialize or add to mixed data
+                            if mixed_data is None:
+                                mixed_data = data * 0.8  # Reduce volume to prevent clipping
+                            else:
+                                # Ensure same length by padding shorter audio
+                                if len(data) > len(mixed_data):
+                                    mixed_data = np.pad(mixed_data, (0, len(data) - len(mixed_data)))
+                                elif len(mixed_data) > len(data):
+                                    data = np.pad(data, (0, len(mixed_data) - len(data)))
+                                
+                                # Mix the audio (layer them)
+                                mixed_data += data * 0.8
+                        except Exception as e:
+                            print(f"Error mixing {sound_file}: {e}")
+            
+            # Save mixed composition or create silent fallback
+            if mixed_data is not None:
+                # Normalize to prevent clipping
+                max_val = np.max(np.abs(mixed_data))
+                if max_val > 0.95:
+                    mixed_data = mixed_data * 0.95 / max_val
+                
+                # sf.write(self.mixed_composition_file, mixed_data, sample_rate)
+                print(f"📀 Mixed composition created: {self.mixed_composition_file} (FILE SAVING DISABLED)")
+            else:
+                # Create silent fallback file
+                silent_data = np.zeros(int(sample_rate * 2))  # 2 seconds of silence
+                # sf.write(self.mixed_composition_file, silent_data, sample_rate)
+                print(f"📀 Silent fallback composition created: {self.mixed_composition_file} (FILE SAVING DISABLED)")
+                
+        except Exception as e:
+            print(f"Error creating mixed composition: {e}")
+            # Create minimal fallback file with actual content
+            self.mixed_composition_file = os.path.abspath("mixed_composition_fallback.wav")
+            try:
+                # Create a short silent audio file as fallback
+                sample_rate = 44100
+                silent_data = np.zeros(int(sample_rate * 2))  # 2 seconds of silence
+                # sf.write(self.mixed_composition_file, silent_data, sample_rate)
+                print(f"📀 Silent fallback composition created: {self.mixed_composition_file} (FILE SAVING DISABLED)")
+            except Exception as fallback_error:
+                print(f"Failed to create fallback file: {fallback_error}")
+                self.mixed_composition_file = None
+    
+    def toggle_dj_effect(self, movement: str) -> dict:
+        """Toggle a DJ effect for the given movement and process audio."""
+        if self.current_phase != "dj_effects":
+            return {"effect_applied": False, "message": "Not in DJ effects phase"}
+        
+        if movement not in self.active_effects:
+            return {"effect_applied": False, "message": f"Unknown movement: {movement}"}
+        
+        # Toggle the effect
+        self.active_effects[movement] = not self.active_effects[movement]
+        effect_status = "ON" if self.active_effects[movement] else "OFF"
+        
+        effect_names = {
+            "left_hand": "Volume Fade",
+            "right_hand": "High Pass Filter",
+            "left_leg": "Reverb Effect", 
+            "right_leg": "Low Pass Filter",
+            "tongue": "Bass Boost"
+        }
+        
+        effect_name = effect_names.get(movement, movement)
+        print(f"🎛️ {effect_name}: {effect_status}")
+        
+        # Process audio with current active effects
+        if self.mixed_composition_file and os.path.exists(self.mixed_composition_file):
+            processed_file = AudioEffectsProcessor.process_with_effects(
+                self.mixed_composition_file, 
+                self.active_effects
+            )
+        else:
+            # If no mixed composition exists, create one from current sounds
+            self._create_mixed_composition()
+            # Only process if we successfully created a mixed composition
+            if self.mixed_composition_file and os.path.exists(self.mixed_composition_file):
+                processed_file = AudioEffectsProcessor.process_with_effects(
+                    self.mixed_composition_file, 
+                    self.active_effects
+                )
+            else:
+                print("Failed to create mixed composition, using fallback")
+                processed_file = self.mixed_composition_file
+        
+        return {
+            "effect_applied": True,
+            "effect_name": effect_name,
+            "effect_status": effect_status,
+            "mixed_composition": processed_file
+        }
+        
+    def get_cycle_success_rate(self) -> float:
+        """Get success rate for current cycle."""
+        if self.cycle_stats['total_attempts'] == 0:
+            return 0.0
+        return self.cycle_stats['successful_classifications'] / self.cycle_stats['total_attempts']
+    
+    def clear_composition(self):
+        """Clear all composition layers."""
+        self.composition_layers = []
+        self.current_composition = None
+        print("Composition cleared")
+    
+    def _get_audio_file_for_gradio(self, movement):
+        """Get the actual audio file path for Gradio audio output"""
+        if movement in self.current_sound_mapping:
+            sound_file = self.current_sound_mapping[movement]
+            audio_path = os.path.join(self.sound_dir, sound_file)
+            if os.path.exists(audio_path):
+                return audio_path
+        return None
+
+    def _mix_audio_files(self, audio_files: List[str]) -> str:
+        """Mix multiple audio files into a single layered audio file."""
+        if not audio_files:
+            return None
+            
+        # Load all audio files and convert to mono
+        audio_data_list = []
+        sample_rate = None
+        max_length = 0
+        
+        for file_path in audio_files:
+            if os.path.exists(file_path):
+                data, sr = sf.read(file_path)
+                
+                # Ensure data is numpy array and handle shape properly
+                data = np.asarray(data)
+                
+                # Convert to mono if stereo/multi-channel
+                if data.ndim > 1:
+                    if data.shape[1] > 1:  # Multi-channel
+                        data = np.mean(data, axis=1)
+                    else:  # Single channel with extra dimension
+                        data = data.flatten()
+                
+                # Ensure final data is 1D
+                data = np.asarray(data).flatten()
+                
+                audio_data_list.append(data)
+                if sample_rate is None:
+                    sample_rate = sr
+                max_length = max(max_length, len(data))
+        
+        if not audio_data_list:
+            return None
+        
+        # Pad all audio to same length and mix
+        mixed_audio = np.zeros(max_length)
+        for data in audio_data_list:
+            # Ensure data is 1D (flatten any remaining multi-dimensional arrays)
+            data_flat = np.asarray(data).flatten()
+            
+            # Pad or truncate to match max_length
+            if len(data_flat) < max_length:
+                padded = np.pad(data_flat, (0, max_length - len(data_flat)), 'constant')
+            else:
+                padded = data_flat[:max_length]
+            
+            # Add to mix (normalize to prevent clipping)
+            mixed_audio += padded / len(audio_data_list)
+        
+        # Create a unique identifier for this composition
+        import hashlib
+        composition_hash = hashlib.md5(''.join(sorted(audio_files)).encode()).hexdigest()[:8]
+        
+        # FILE SAVING DISABLED: Return first available audio file instead of creating mixed composition
+        mixed_audio_path = os.path.join(self.sound_dir, f"mixed_composition_{composition_hash}.wav")
+        
+        # Since file saving is disabled, use the first available audio file from the list
+        if audio_files:
+            # Use the first audio file as the "mixed" composition
+            first_audio_file = os.path.join(self.sound_dir, audio_files[0])
+            if os.path.exists(first_audio_file):
+                print(f"DEBUG: Using first audio file as mixed composition: {os.path.basename(first_audio_file)} (FILE SAVING DISABLED)")
+                return first_audio_file
+        
+        # Fallback: if mixed composition file already exists, use it
+        if os.path.exists(mixed_audio_path):
+            print(f"DEBUG: Reusing existing mixed audio file: {os.path.basename(mixed_audio_path)}")
+            return mixed_audio_path
+        
+        # Final fallback: return first available base audio file
+        base_files = ["1_SoundHelix-Song-6_(Vocals).wav", "1_SoundHelix-Song-6_(Drums).wav", "1_SoundHelix-Song-6_(Bass).wav", "1_SoundHelix-Song-6_(Other).wav"]
+        for base_file in base_files:
+            base_path = os.path.join(self.sound_dir, base_file)
+            if os.path.exists(base_path):
+                print(f"DEBUG: Using base audio file as fallback: {base_file} (FILE SAVING DISABLED)")
+                return base_path
+        
+        return mixed_audio_path
+
+    def get_current_mixed_composition(self) -> str:
+        """Get the current composition as a mixed audio file."""
+        # Get all audio files from current composition layers
+        audio_files = []
+        for layer in self.composition_layers:
+            movement = layer.get('movement')
+            if movement and movement in self.current_sound_mapping:
+                sound_file = self.current_sound_mapping[movement]
+                audio_path = os.path.join(self.sound_dir, sound_file)
+                if os.path.exists(audio_path):
+                    audio_files.append(audio_path)
+        
+        # Debug: print current composition state
+        print(f"DEBUG: Current composition has {len(self.composition_layers)} layers: {[layer.get('movement') for layer in self.composition_layers]}")
+        print(f"DEBUG: Audio files to mix: {[os.path.basename(f) for f in audio_files]}")
+        
+        return self._mix_audio_files(audio_files)
+
+    def get_composition_info(self) -> Dict:
+        """Get comprehensive information about current composition."""
+        layers_by_cycle = {}
+        for layer in self.composition_layers:
+            cycle = layer['cycle']
+            if cycle not in layers_by_cycle:
+                layers_by_cycle[cycle] = []
+            layers_by_cycle[cycle].append({
+                'step': layer['step'],
+                'movement': layer['movement'], 
+                'sound_file': layer['sound_file'],
+                'confidence': layer['confidence']
+            })
+        
+        # Also track completed movements without sounds (like neutral)
+        completed_without_sound = [mov for mov in self.movements_completed 
+                                 if self.current_sound_mapping.get(mov) is None]
+        
+        return {
+            'total_cycles': self.current_cycle + (1 if self.composition_layers else 0),
+            'current_cycle': self.current_cycle + 1,
+            'current_step': len(self.movements_completed) + 1,  # Current step in cycle
+            'target_movement': self.get_current_target_movement(),
+            'movements_completed': len(self.movements_completed),
+            'movements_remaining': len(self.current_movement_sequence) - len(self.movements_completed),
+            'cycle_complete': self.cycle_complete,
+            'total_layers': len(self.composition_layers),
+            'completed_movements': list(self.movements_completed),
+            'completed_without_sound': completed_without_sound,
+            'layers_by_cycle': layers_by_cycle,
+            'current_mapping': self.current_sound_mapping.copy(),
+            'success_rate': self.get_cycle_success_rate(),
+            'stats': self.cycle_stats.copy()
+        }
+    
+    def get_sound_mapping_options(self) -> Dict:
+        """Get available sound mapping options for user customization."""
+        return {
+            'movements': self.all_movements,  # All possible movements for mapping
+            'available_sounds': self.available_sounds,
+            'current_mapping': self.current_sound_mapping.copy()
+        }
+    
+    def update_sound_mapping(self, new_mapping: Dict[str, str]) -> bool:
+        """Update the sound mapping for future cycles."""
+        try:
+            # Validate that all sounds exist
+            for movement, sound_file in new_mapping.items():
+                if sound_file not in self.available_sounds:
+                    print(f"Warning: Sound file {sound_file} not available")
+                    return False
+                    
+            self.current_sound_mapping.update(new_mapping)
+            print("✓ Sound mapping updated successfully")
+            return True
+        except Exception as e:
+            print(f"Error updating sound mapping: {e}")
+            return False
+    
+    def reset_composition(self):
+        """Reset the entire composition to start fresh."""
+        self.composition_layers = []
+        self.current_cycle = 0
+        self.current_step = 0
+        self.cycle_complete = False
+        self.cycle_stats = {
+            'total_cycles': 0,
+            'successful_classifications': 0,
+            'total_attempts': 0
+        }
+        print("🔄 Composition reset - ready for new session")
+    
+    def save_composition(self, output_path: str = "composition.wav"):
+        """Save the current composition as a mixed audio file."""
+        if not self.composition_layers:
+            print("No layers to save")
+            return False
+            
+        try:
+            # For simplicity, we'll just save the latest layer
+            # In a real implementation, you'd mix multiple audio tracks
+            latest_layer = self.composition_layers[-1]
+            sound_data = latest_layer['sound_data']
+            
+            sf.write(output_path, sound_data['data'], sound_data['sample_rate'])
+            print(f"Composition saved to {output_path}")
+            return True
+            
+        except Exception as e:
+            print(f"Error saving composition: {e}")
+            return False
+    
+    def get_available_sounds(self) -> List[str]:
+        """Get list of available sound classes."""
+        return list(self.loaded_sounds.keys())

source/eeg_motor_imagery.py

@@ -0,0 +1,142 @@
+"""
+EEG Motor Imagery Classification with Shallow ConvNet
+-----------------------------------------------------
+This script trains and evaluates a ShallowFBCSPNet model
+on motor imagery EEG data stored in .mat files.
+"""
+
+# === 1. Imports ===
+import scipy.io
+import numpy as np
+import mne
+import torch
+from torch.utils.data import TensorDataset, DataLoader
+from sklearn.model_selection import train_test_split
+from braindecode.models import ShallowFBCSPNet
+import torch.nn as nn
+import pandas as pd
+
+# === 2. Data Loading and Epoching ===
+# Load .mat EEG files, create Raw objects, extract events, and epoch the data
+files = [
+    "../data/raw_mat/HaLTSubjectA1602236StLRHandLegTongue.mat",
+    "../data/raw_mat/HaLTSubjectA1603086StLRHandLegTongue.mat",
+    
+]
+
+all_epochs = []
+for f in files:
+    mat = scipy.io.loadmat(f)
+    content = mat['o'][0, 0]
+
+    labels = content[4].flatten()
+    signals = content[5]
+    chan_names_raw = content[6]
+    channels = [ch[0][0] for ch in chan_names_raw]
+    fs = int(content[2][0, 0])
+
+    df = pd.DataFrame(signals, columns=channels).drop(columns=["X5"], errors="ignore")
+    eeg = df.values.T
+    ch_names = df.columns.tolist()
+
+    info = mne.create_info(ch_names=ch_names, sfreq=fs, ch_types="eeg")
+    raw = mne.io.RawArray(eeg, info)
+
+    # Create events
+    onsets = np.where((labels[1:] != 0) & (labels[:-1] == 0))[0] + 1
+    event_codes = labels[onsets].astype(int)
+    events = np.c_[onsets, np.zeros_like(onsets), event_codes]
+
+    # Keep only relevant events
+    mask = np.isin(events[:, 2], np.arange(1, 7))
+    events = events[mask]
+
+    event_id = {
+        "left_hand": 1,
+        "right_hand": 2,
+        "neutral": 3,
+        "left_leg": 4,
+        "tongue": 5,
+        "right_leg": 6,
+    }
+
+    # Epoching
+    epochs = mne.Epochs(
+        raw,
+        events=events,
+        event_id=event_id,
+        tmin=0,
+        tmax=1.5,
+        baseline=None,
+        preload=True,
+    )
+
+    all_epochs.append(epochs)
+
+epochs_all = mne.concatenate_epochs(all_epochs)
+
+# === 3. Minimal Preprocessing + Train/Validation Split ===
+# Convert epochs to numpy arrays (N, C, T) and split into train/val sets
+X = epochs_all.get_data().astype("float32")
+y = (epochs_all.events[:, -1] - 1).astype("int64")  # classes 0..5
+
+X_train, X_val, y_train, y_val = train_test_split(
+    X, y, test_size=0.2, random_state=42, stratify=y
+)
+
+# === 4. Torch DataLoaders ===
+train_ds = TensorDataset(torch.from_numpy(X_train), torch.from_numpy(y_train))
+val_ds   = TensorDataset(torch.from_numpy(X_val),   torch.from_numpy(y_val))
+
+train_loader = DataLoader(train_ds, batch_size=32, shuffle=True)
+val_loader   = DataLoader(val_ds, batch_size=32)
+
+# === 5. Model – Shallow ConvNet ===
+# Reference: Schirrmeister et al. (2017)
+device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+
+model = ShallowFBCSPNet(
+    n_chans=X.shape[1],
+    n_outputs=len(np.unique(y)),
+    n_times=X.shape[2],
+    final_conv_length="auto"
+).to(device)
+
+# Load pretrained weights
+state_dict = torch.load("shallow_weights_all.pth", map_location=device)
+model.load_state_dict(state_dict)
+
+# === 6. Training ===
+criterion = nn.CrossEntropyLoss()
+optimizer = torch.optim.Adam(model.parameters(), lr=1e-3)
+
+for epoch in range(1, 21):
+    # Training
+    model.train()
+    correct, total = 0, 0
+    for xb, yb in train_loader:
+        xb, yb = xb.to(device), yb.to(device)
+        optimizer.zero_grad()
+        out = model(xb)
+        loss = criterion(out, yb)
+        loss.backward()
+        optimizer.step()
+
+        pred = out.argmax(dim=1)
+        correct += (pred == yb).sum().item()
+        total += yb.size(0)
+    train_acc = correct / total
+
+    # Validation
+    model.eval()
+    correct, total = 0, 0
+    with torch.no_grad():
+        for xb, yb in val_loader:
+            xb, yb = xb.to(device), yb.to(device)
+            out = model(xb)
+            pred = out.argmax(dim=1)
+            correct += (pred == yb).sum().item()
+            total += yb.size(0)
+    val_acc = correct / total
+
+    print(f"Epoch {epoch:02d} | Train acc: {train_acc:.3f} | Val acc: {val_acc:.3f}")

utils.py

@@ -0,0 +1,226 @@
+"""
+Utility functions for the EEG Motor Imagery Music Composer
+"""
+
+import numpy as np
+import logging
+import time
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+import json
+
+from config import LOG_LEVEL, LOG_FILE, CLASS_NAMES, CLASS_DESCRIPTIONS
+
+def setup_logging():
+    """Set up logging configuration."""
+    LOG_FILE.parent.mkdir(parents=True, exist_ok=True)
+    
+    logging.basicConfig(
+        level=getattr(logging, LOG_LEVEL),
+        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+        handlers=[
+            logging.FileHandler(LOG_FILE),
+            logging.StreamHandler()
+        ]
+    )
+    
+    return logging.getLogger(__name__)
+
+def validate_eeg_data(data: np.ndarray) -> bool:
+    """
+    Validate EEG data format and dimensions.
+    
+    Args:
+        data: EEG data array
+        
+    Returns:
+        bool: True if data is valid, False otherwise
+    """
+    if not isinstance(data, np.ndarray):
+        return False
+        
+    if data.ndim not in [2, 3]:
+        return False
+        
+    if data.ndim == 2 and data.shape[0] == 0:
+        return False
+        
+    if data.ndim == 3 and (data.shape[0] == 0 or data.shape[1] == 0):
+        return False
+        
+    return True
+
+def format_confidence(confidence: float) -> str:
+    """Format confidence score as percentage string."""
+    return f"{confidence * 100:.1f}%"
+
+def format_timestamp(timestamp: float) -> str:
+    """Format timestamp for display."""
+    return time.strftime("%H:%M:%S", time.localtime(timestamp))
+
+def get_class_emoji(class_name: str) -> str:
+    """Get emoji representation for motor imagery class."""
+    emoji_map = {
+        "left_hand": "🤚",
+        "right_hand": "🤚",
+        "neutral": "😐",
+        "left_leg": "🦵",
+        "tongue": "👅",
+        "right_leg": "🦵"
+    }
+    return emoji_map.get(class_name, "❓")
+
+def create_classification_summary(
+    predicted_class: str,
+    confidence: float,
+    probabilities: Dict[str, float],
+    timestamp: Optional[float] = None
+) -> Dict:
+    """
+    Create a formatted summary of classification results.
+    
+    Args:
+        predicted_class: Predicted motor imagery class
+        confidence: Confidence score (0-1)
+        probabilities: Dictionary of class probabilities
+        timestamp: Optional timestamp
+        
+    Returns:
+        Dict: Formatted classification summary
+    """
+    if timestamp is None:
+        timestamp = time.time()
+        
+    return {
+        "predicted_class": predicted_class,
+        "confidence": confidence,
+        "confidence_percent": format_confidence(confidence),
+        "probabilities": probabilities,
+        "timestamp": timestamp,
+        "formatted_time": format_timestamp(timestamp),
+        "emoji": get_class_emoji(predicted_class),
+        "description": CLASS_DESCRIPTIONS.get(predicted_class, predicted_class)
+    }
+
+def save_session_data(session_data: Dict, filepath: str) -> bool:
+    """
+    Save session data to JSON file.
+    
+    Args:
+        session_data: Dictionary containing session information
+        filepath: Path to save the file
+        
+    Returns:
+        bool: True if successful, False otherwise
+    """
+    try:
+        with open(filepath, 'w') as f:
+            json.dump(session_data, f, indent=2, default=str)
+        return True
+    except Exception as e:
+        logging.error(f"Error saving session data: {e}")
+        return False
+
+def load_session_data(filepath: str) -> Optional[Dict]:
+    """
+    Load session data from JSON file.
+    
+    Args:
+        filepath: Path to the JSON file
+        
+    Returns:
+        Dict or None: Session data if successful, None otherwise
+    """
+    try:
+        with open(filepath, 'r') as f:
+            return json.load(f)
+    except Exception as e:
+        logging.error(f"Error loading session data: {e}")
+        return None
+
+def calculate_classification_statistics(history: List[Dict]) -> Dict:
+    """
+    Calculate statistics from classification history.
+    
+    Args:
+        history: List of classification results
+        
+    Returns:
+        Dict: Statistics summary
+    """
+    if not history:
+        return {"total": 0, "class_counts": {}, "average_confidence": 0.0}
+    
+    class_counts = {}
+    total_confidence = 0.0
+    
+    for item in history:
+        class_name = item.get("predicted_class", "unknown")
+        confidence = item.get("confidence", 0.0)
+        
+        class_counts[class_name] = class_counts.get(class_name, 0) + 1
+        total_confidence += confidence
+    
+    return {
+        "total": len(history),
+        "class_counts": class_counts,
+        "average_confidence": total_confidence / len(history),
+        "most_common_class": max(class_counts, key=class_counts.get) if class_counts else None
+    }
+
+def create_progress_bar(value: float, max_value: float = 1.0, width: int = 20) -> str:
+    """
+    Create a text-based progress bar.
+    
+    Args:
+        value: Current value
+        max_value: Maximum value
+        width: Width of progress bar in characters
+        
+    Returns:
+        str: Progress bar string
+    """
+    percentage = min(value / max_value, 1.0)
+    filled = int(width * percentage)
+    bar = "█" * filled + "░" * (width - filled)
+    return f"[{bar}] {percentage * 100:.1f}%"
+
+def validate_audio_file(file_path: str) -> bool:
+    """
+    Validate if an audio file exists and is readable.
+    
+    Args:
+        file_path: Path to audio file
+        
+    Returns:
+        bool: True if file is valid, False otherwise
+    """
+    path = Path(file_path)
+    if not path.exists():
+        return False
+        
+    if not path.is_file():
+        return False
+        
+    # Check file extension
+    valid_extensions = ['.wav', '.mp3', '.flac', '.ogg']
+    if path.suffix.lower() not in valid_extensions:
+        return False
+        
+    return True
+
+def generate_composition_filename(prefix: str = "composition") -> str:
+    """
+    Generate a unique filename for composition exports.
+    
+    Args:
+        prefix: Filename prefix
+        
+    Returns:
+        str: Unique filename with timestamp
+    """
+    timestamp = time.strftime("%Y%m%d_%H%M%S")
+    return f"{prefix}_{timestamp}.wav"
+
+# Initialize logger when module is imported
+logger = setup_logging()