cleaned up

.gitignore

@@ -17,14 +17,10 @@ __pycache__/
 .DS_Store
 
 # Project specific
-*.wav
-*.mp3
 *.pth
-*.mat
+
 app.log
 
 # Data and generated folders
-data/
-sounds/
 otherfiles/
 source/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sofia Fregni
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,78 +1,68 @@
-# 🧠 EEG Motor Imagery Music Composer
+# 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.
+A user-friendly, accessible neuro-music studio for motor rehabilitation and creative exploration. Compose and remix music using EEG motor imagery signals—no musical experience required!
 
-## 🎯 Features
+## 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
+- **Automatic Composition:** Layer musical stems (bass, drums, instruments, vocals) by imagining left/right hand or leg movements. Each correct, high-confidence prediction adds a new sound.
+- **DJ Mode:** After all four layers are added, apply real-time audio effects (Echo, Low Pass, Compressor, Fade In/Out) to remix your composition using new brain commands.
+- **Seamless Playback:** All completed layers play continuously, with smooth transitions and effect toggling.
+- **Manual Classifier:** Test the classifier on individual movements and visualize EEG data, class probabilities, and confusion matrix.
+- **Accessible UI:** Built with Gradio for easy use in browser or on Hugging Face Spaces.
 
-## 🏗️ Architecture
+## How It Works
 
-### 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
+1. **Compose:**
+   - Click "Start Composing" and follow the on-screen prompts.
+   - Imagine the prompted movement (left hand, right hand, left leg, right leg) to add musical layers.
+   - Each correct, confident prediction adds a new instrument to the mix.
+2. **DJ Mode:**
+   - After all four layers are added, enter DJ mode.
+   - Imagine movements in a specific order to toggle effects on each stem.
+   - Effects are sticky and only toggle every 4th repetition for smoothness.
+3. **Manual Classifier:**
+   - Switch to the Manual Classifier tab to test the model on random epochs for each movement.
+   - Visualize predictions, probabilities, and confusion matrix.
 
-3. **SoundManager** (`sound_library.py`)
-   - Maps classifications to audio files
-   - Manages composition layers
-   - Handles audio file loading and playback
+## Project Structure
 
-4. **Gradio Interface** (`app.py`)
-   - Web-based user interface
-   - Real-time visualization
-   - Composition management tools
+```
+app.py                # Main Gradio app and UI logic
+sound_manager.py      # Audio processing and effect logic
+classifier.py         # EEG classifier
+config.py             # Configuration and constants
+data_processor.py     # EEG data loading and preprocessing
+requirements.txt      # Python dependencies
+.gitignore            # Files/folders to ignore in git
+SoundHelix-Song-6/    # Demo audio stems (bass, drums, instruments, vocals)
+```
 
-## 🚀 Quick Start
+## Quick Start
 
-### Requirements
 
-Python 3.9–3.11 recommended. Install dependencies:
+1. **Install dependencies:**
+   ```bash
+   pip install -r requirements.txt
+   ```
+2. **Add required data:**
+   - Ensure the `SoundHelix-Song-1/` folder with all audio stems (`bass.wav`, `drums.wav`, `instruments.wav` or `other.wav`, `vocals.wav`) is present and tracked in your repository.
+   - Include at least one demo EEG `.mat` file (as referenced in your `DEMO_DATA_PATHS` in `config.py`) for the app to run out-of-the-box. Place it in the correct location and ensure it is tracked by git.
+3. **Run the app:**
+   ```bash
+   python app.py
+   ```
+4. **Open in browser:**
+   - Go to `http://localhost:7867` (or the port shown in the terminal)
 
-```bash
-python -m pip install -r requirements.txt
-```
+## Deployment
 
-### How to run (Gradio)
+- Ready for Hugging Face Spaces or any Gradio-compatible cloud platform.
+- Minimal `.gitignore` and clean repo for easy deployment.
+- Make sure to include all required audio stems and at least two demo `.mat` EEG file in your deployment for full functionality.
 
-Local launch:
+## Credits
 
-```bash
-python app.py
-```
+- Developed by Sofia Fregni. Model training by Kasia. Deployment by Hamed Koochaki Kelardeh.
+- Audio stems: [SoundHelix](https://www.soundhelix.com/)
 
-This starts a server on `http://127.0.0.1:7860` by default.
 
-#

app.py

@@ -97,21 +97,18 @@ def get_movement_sounds() -> Dict[str, str]:
                             # Save to temp file (persistent for this effect state)
                             tmp = tempfile.NamedTemporaryFile(delete=False, suffix=f'_{movement}_effect.wav')
                             sf.write(tmp.name, processed, sr)
-                            print(f"DEBUG: Playing PROCESSED audio for {movement}: {tmp.name}")
                             get_movement_sounds.audio_cache[movement][True] = tmp.name
                             sounds[movement] = tmp.name
                         else:
-                            print(f"DEBUG: Playing ORIGINAL audio for {movement}: {sound_path.resolve()}")
                             get_movement_sounds.audio_cache[movement][False] = str(sound_path.resolve())
                             sounds[movement] = str(sound_path.resolve())
                         get_movement_sounds.last_effect_state[movement] = effect_on
                     get_movement_sounds.play_counter[movement] += 1
+
     get_movement_sounds.total_calls += 1
-    # Print summary every 20 calls
-    if get_movement_sounds.total_calls % 20 == 0:
-        print("AUDIO PLAY COUNTS (DJ mode):", dict(get_movement_sounds.play_counter))
     return sounds
 
+
 def create_eeg_plot(eeg_data: np.ndarray, target_movement: str, predicted_name: str, confidence: float, sound_added: bool, ch_names=None) -> plt.Figure:
     '''Create a plot of EEG data with annotations. Plots C3 and C4 channels by name.'''
     if ch_names is None:
@@ -159,7 +156,6 @@ def start_composition():
     if not app_state['composition_active']:
         app_state['composition_active'] = True
         sound_manager.start_new_cycle()
-    print(f"DEBUG: [start_composition] current_phase={sound_manager.current_phase}, movements_completed={sound_manager.movements_completed}")
     if app_state['demo_data'] is None:
         return "❌ No data", "❌ No data", "❌ No data", None, None, None, None, None, None, "No EEG data available"
     # Force first trial to always be left_hand/instrumental
@@ -177,11 +173,9 @@ def start_composition():
         true_label_name = classifier.class_names[true_label]
         next_movement = sound_manager.get_current_target_movement()
     if next_movement == "cycle_complete":
-        print("DEBUG: [start_composition] Transitioning to DJ mode!")
         return continue_dj_phase()
     predicted_class, confidence, probabilities = classifier.predict(epoch_data)
     predicted_name = classifier.class_names[predicted_class]
-    print(f"TRIAL: true_label={true_label_name}, presented_target={next_movement}, predicted={predicted_name}")
     # Only add sound if confidence > threshold, predicted == true label, and true label matches the prompt
     if confidence > CONFIDENCE_THRESHOLD and predicted_name == true_label_name:
         result = sound_manager.process_classification(predicted_name, confidence, CONFIDENCE_THRESHOLD, force_add=True)
@@ -251,7 +245,6 @@ def continue_dj_phase():
     ''' Continue in DJ phase, applying effects and always playing all layered sounds.
     '''
     global app_state
-    print(f"DEBUG: [continue_dj_phase] Entered DJ mode. current_phase={sound_manager.current_phase}")
     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:
@@ -441,13 +434,10 @@ def create_interface():
                         if len(result) == 8:
                             # Pre-DJ mode: add timer and button updates
                             if any(isinstance(x, str) and "DJ Mode" in x for x in result):
-                                print("DEBUG: [timer_tick] DJ mode detected in outputs, stopping timer and showing continue button.")
                                 return (*result, gr.update(active=False), gr.update(visible=True))
                             else:
-                                print("DEBUG: [timer_tick] Not in DJ mode, continuing trials.")
                                 return (*result, gr.update(active=True), gr.update(visible=False))
                         elif len(result) == 10:
-                            print("DEBUG: [timer_tick] Already in DJ mode, returning result as is.")
                             return tuple(result)
                         else:
                             raise ValueError(f"Unexpected result length in timer_tick: {len(result)}")

classifier.py

@@ -71,19 +71,12 @@ class MotorImageryClassifier:
                     #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...")
+                except Exception:
                     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...")
+        except Exception:
             self.is_loaded = False
     
     def get_model_status(self) -> str:
@@ -135,8 +128,6 @@ class MotorImageryClassifier:
         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()
@@ -181,20 +172,16 @@ class MotorImageryClassifier:
                 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}")
     
     

data/HaLTSubjectA1602236StLRHandLegTongue.mat

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fc8647c55ddcb9854de234a35e4261576ecca957a8381d3ef6554aa209f89231
+size 39673990

data/HaLTSubjectA1603086StLRHandLegTongue.mat

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:76c9f2eb53f2c1e6192f1bd7082e24c8c5b7c4c362089d3bac6320e340970bb7
+size 40401694

data/HaLTSubjectA1603106StLRHandLegTongue.mat

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0f2f0d913e29ff150c2929b163e0151e8b2d4f469de2b11985e13114938cb2df
+size 49162097

sound_manager.py

@@ -126,12 +126,11 @@ class SoundManager:
         # Fixed movement order and mapping
         self.current_movement_sequence = ["left_hand", "right_hand", "left_leg", "right_leg"]
         self.current_sound_mapping = {
-            "left_hand": "SoundHelix-Song-4_instruments.wav",
-            "right_hand": "SoundHelix-Song-4_bass.wav",
-            "left_leg": "SoundHelix-Song-4_drums.wav",
-            "right_leg": "SoundHelix-Song-4_vocals.wav"
+            "left_hand": "SoundHelix-Song-6_instruments.wav",
+            "right_hand": "SoundHelix-Song-6_bass.wav",
+            "left_leg": "SoundHelix-Song-6_drums.wav",
+            "right_leg": "SoundHelix-Song-6_vocals.wav"
         }
-        print(f"DEBUG: Fixed sound mapping for this cycle: {self.current_sound_mapping}")
         self.movements_completed = set()
         self.current_step = 0
         self._load_sound_files()
@@ -140,7 +139,6 @@ class SoundManager:
         # Always process left_hand last in DJ mode
         incomplete = [m for m in self.active_movements if m not in self.movements_completed]
         if not incomplete:
-            print("DEBUG: All movements completed, cycle complete.")
             return "cycle_complete"
         # If in DJ mode, left_hand should be last
         if getattr(self, 'current_phase', None) == 'dj_effects':
@@ -149,7 +147,6 @@ class SoundManager:
                 incomplete = [m for m in incomplete if m != 'left_hand']
         import random
         movement = random.choice(incomplete)
-        print(f"DEBUG: Next target is {movement}, completed: {self.movements_completed}")
         return movement
 
 
@@ -162,31 +159,28 @@ class SoundManager:
                 predicted_class in self.loaded_sounds and
                 predicted_class not in self.composition_layers
             ):
-                print(f"DEBUG: [FORCE] Adding sound for {predicted_class}")
                 sound_info = dict(self.loaded_sounds[predicted_class])
                 sound_info['confidence'] = confidence
                 self.composition_layers[predicted_class] = sound_info
                 self.movements_completed.add(predicted_class)
                 result['sound_added'] = True
             else:
-                print("DEBUG: [FORCE] Not adding sound. Condition failed.")
+                pass
         else:
             current_target = self.get_current_target_movement()
-            print(f"DEBUG: process_classification: predicted={predicted_class}, target={current_target}, confidence={confidence}, completed={self.movements_completed}")
             if (
                 predicted_class == current_target and
                 confidence >= threshold and
                 predicted_class in self.loaded_sounds and
                 predicted_class not in self.composition_layers
             ):
-                print(f"DEBUG: Adding sound for {predicted_class} (target={current_target})")
                 sound_info = dict(self.loaded_sounds[predicted_class])
                 sound_info['confidence'] = confidence
                 self.composition_layers[predicted_class] = sound_info
                 self.movements_completed.add(predicted_class)
                 result['sound_added'] = True
             else:
-                print("DEBUG: Not adding sound. Condition failed.")
+                pass
         if len(self.movements_completed) >= len(self.active_movements):
             result['cycle_complete'] = True
             self.current_phase = "dj_effects"
@@ -219,16 +213,13 @@ class SoundManager:
         self.dj_effect_counters[movement] += 1
         count = self.dj_effect_counters[movement]
         if count != 1 and (count - 1) % 4 != 0:
-            print(f"🎛️ {movement}: Skipped effect toggle (count={count})")
             return {"effect_applied": False, "message": f"Effect for {movement} only toggled at 1, 4, 8, ... (count={count})"}
         # Toggle effect ON
         self.active_effects[movement] = True
         effect_status = "ON"
-        print(f"🎛️ {movement}: {effect_status} (brief={brief}) [count={count}]")
         # Schedule effect OFF after duration if brief
         def turn_off_effect():
             self.active_effects[movement] = False
-            print(f"🎛️ {movement}: OFF (auto)")
         if brief:
             timer = threading.Timer(duration, turn_off_effect)
             timer.daemon = True

sounds/SoundHelix-Song-6_bass.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6877ac76aacfdb672ac665e96fc1a70bba38ac0625d3259f275a072d53fa0abc
+size 98657548

sounds/SoundHelix-Song-6_drums.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:37e78d23c940663297b32eec80ec3db0788b8e3d230241d33a244f68c64633fd
+size 98657548

sounds/SoundHelix-Song-6_instruments.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5c441fb96c015ca02768d76262d4de5379567eba6d79897e8f3b8d1952b206e8
+size 98657548

sounds/SoundHelix-Song-6_vocals.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fdd13cd7f4e3a9c87aecb03aa5e1278c1b41317f6f99a52549f2781db19fb930
+size 98657548