Addressing GH merging technical debt

.github/FUNDING.yml

@@ -0,0 +1,3 @@
+# These are supported funding model platforms
+
+github: MAMware

.gitignore

@@ -1,5 +1,5 @@
 node_modules/
-future/test
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]
@@ -174,3 +174,4 @@ cython_debug/
 
 # PyPI configuration file
 .pypirc
+future/project-files.txt

README.md

@@ -1,22 +1,31 @@
-# AcoustSee
-
 **a photon to phonon code**
 
-
 ## [Introduction](#introduction)
 
-The content in this repository aims to transform a visual environment into a intuitive soundscape, in a synesthesic transform, empowering the user to experience the visual world by synthetic audio cues in real time.
+The content in this repository provides code and docs of an accessibility web app that aims to help visually impaired users by transforming visual environments into soundscapes in real time.
 
-> **Why?** We believe in solving real problems with open-source software in a fast, accessible, and impactful way. You are invited to join us to improve and make a difference!
+> We believe in enhancing humanity with open-source software. You are invited to join us improving this mission and make a difference!
 
 ### Project Vision
 
-The synesthesia at project is the translation from a photon to a phonon, with a tech stack that should be easy to get for a regular user, in this case a visually challenged one. 
-This repo holds code that when loaded into a mobile phone browser translates its camera imput into a stereo soundscape, where a sidewalk that the user is waling on could have a distintive spectrum signature that is being hear by both hears, a wall at the left with its should make its  distintive sound signature, a car, a hole... a light... and so on... 
+- Synesthetic Translation: Converting visual data such as a live camera feed into stereo audio cues, mapping colors, shapes and motions to distinct sound signatures.
+- Dynamic Soundscapes for Location-Aware Audio: Adjusts audio in real time based on object distance and motion, e.g., an object approaching shifts the sound in tone, volume and complexity as it moves.
+
+
+### Tech stack needed
+
+Development: Pure Vanilla JS with no external dependency
 
->Imagine a person that is unable to see, sitting at a park with headphones on and paired to a mobile phone. This phone is being weared like a necklage with the camera facing a quiet swing, as the seat of the swing gets back/further the sound generator makes a sound spectra that has a less broad harmonic content and a lower volume and wen it swings closer its spectra complexity raises, broader and louder. 
+Software: Runs in a web browser from 2020 and up (ES6+)
+Hardware: The design is tested with low settings on a mobile phone from 2020. 
+Input: Video camera for real-time visual data capture.
+Audio Output: Stereo headphones or speakers for spatial audio effects.
 
-This project aims to make this imagination into a reality, with its first milestones coded entirely by xAI Grok is now ready to welcome contributors from open source community to enhace in a afordable way, perception. 
+### BRIEF
+
+Entirely coded by xAI Grok 3 to Milestone 4 as per @MAMware prompts 
+Milestone 5 got help from OpenAI ChatGPT 4.1, 04-mini, Anthropic Claude 4 via @github copilot at codespaces and also Grok 4 wich is charge of the re-estructuring from v0.5.12
+Currently at Milestone 9 (26.02.09) the project is developed in private and near public annoucement. 
 
 ## Table of Contents
 
@@ -33,141 +42,150 @@ This project aims to make this imagination into a reality, with its first milest
 
 ### [Usage](docs/USAGE.md)
 
-The latest stable proof of concept can be run from 
-
-- https://mamware.github.io/acoustsee/present
-
-Previous versions and other approachs can be found at
-
-- https://mamware.github.io/acoustsee/past
+The webapp runs from a Internet browsers and mobile hardware from 2021.
 
-Unstable versions currently being developed adn tested can be found at
+- Current version [RUN](https://mamware.github.io/acoustsee/present/)
+- Previous versions [RUN](https://mamware.github.io/acoustsee/past/old_versions/preview)
+- Testing developments [RUN](https://mamware.github.io/acoustsee/future/web)
 
-- https://mamware.github.io/acoustsee/future
+### Check [Usage](docs/USAGE.md) for further details
 
-To use it, having the most up to date version of mobile web browsers is diserable yet most mobile internet browsers from 2021 should work.
+### [Current Status](#status) **OUTDATED**
 
-For a complete mobile browser compability list check the doc [Usage](docs/USAGE.md) there you also find instruccions to run the first command line PoC made with Python
-
-### Hardware needed:
-
-A mobile phone/cellphone from 2021 and up, with a front facing camera and stereo headphones with mic.
-
-### Steps to initialize
-
-- The webapp is designed to be used with a mobile phone where its front camera (and screen) are facing the desired objetive to be transformed in to sound, wearing the mobile phone like a necklage is its first use case in mind.
-
-- Enter https://mamware.github.io/acoustsee/present  (or your version of preference from [Usage](docs/USAGE.md))
-
-- The User Interface of the webapp is split into five regions,
-  - Center rectangle: Audio enabler, a touchplace holder that enables the webpage to produce sound. 
-  - Top border rectangle: Settings SHIFTer button 
-  - Bottom rectangle: Start and Stop button 
-  - Left rectangle: Day and night switch for light logic inversion
-  - Right rectangle: Languaje switcher
-  - SHIFTed left rectangle (settings enabled): Grid selector, changes how the camera frames or "grids" the environment
-  - SHIFTed right rectangle (settings enabled): Audio engine selector, changes how the sound synthetizer reacts to the selected grid.   
+Working at **Milestone 5 (Current)** 
+- Haptic feedback via Vibration API **Developing in Progress 85%** 
+- Console log on device screen and mail to feature for debuggin. **Developing in Progress 85%**
+- New languajes agnostic architecture ready to provide multilingual support for the speech sinthetizer and UI  **Developing in Progress 95%**
+- Mermaid diagrams to reflect current Modular Single Responsability Principle **To do**
+
+### [Changelog](docs/CHANGELOG.md)
 
-IMPORTANT: The processing of the camera is done privately on your device and not a single frame is sent outside your device processor. A permision to access the camera by the browser will be requested in order to do this local processing and thus generate the audio for the navigation.
+- Current "stable" version from "present" is v0.4.7, link above logs the history and details past milestones achieved.
+- Current "future" version in development starts from v0.5 
 
-### [Status](#status)
+### [Project structure](#project_structure)
+WARN: this is alpha stage and is only meant for testing purposing using the Sinewave synth, some synths like Strings cause VERY HIGH NOISE that could damage hearing and speakers. 
 
-**Milestone 4 (Current)**: **Developing in Progress**  at /future folder from developing branch
+- Current version [RUN](https://mamware.github.io/acoustsee/present/)
+- Previous versions [RUN](https://mamware.github.io/acoustsee/past/old_versions/preview)
+- Test version in development [RUN](https://mamware.github.io/acoustsee/future/web)
 
-- Current effort is at setting the repository with the most confortable structure for developers, with niche experts in mind, to have a fast way to understand how we do what we do and be able to contribute in a fast and simple way.
-- We should refactor dependencies, isolate the audio pipeline and decouple UI and logic.
-- Make WCAG contrast UI.
-- Code should be educational purpose ready (JSDoc)
-
-### [Changelog](docs/CHANGELOG.md)
+### [Current Status](#status) 
 
-- Current version is v0.4.7, follow link above for a the history change log, details and past milestones achieved.
+- Milestone 0 to 4: reached by vibecoding with xAI Grok 3 
+- Milestone 5:  reached byv ibecoded with SuperGrok 4. some assistance from Gemini 2.5 Pro (Preview), ChatGPT 4.1 & o4-mini agents + small reviews from Claude 4.
+- Milestone 6:  restructered with Gemini 2.5 Pro and ChatGPT 4.1 & 04-mini agents 
+- Milestone 6.5: (WIP) robust architectural improvements and integration work by GPT-5 mini (Preview)
+- Milestone 7 to 9: mayor redesign with a foundational Command pattern and Hexagonal architecture while still in plain vanilla JS, not merged to developing branch becouse this actually a complete rebase. 
 
-### [Project structure](#project_structure)
+### [v0.6 Project structure, (in construction)](#project_structure)
 
 ```
 
-acoustsee/
-
-├── present/                      # Current Stable Modular Webapp
-│   ├── index.html
-│   ├── styles.css
-│   ├── main.js
-│   ├── state.js
-│   ├── audio-processor.js
-│   ├── grid-selector.js
-│   ├── ui/
-│   │   ├── rectangle-handlers.js # Handles settingsToggle, modeBtn, languageBtn, startStopBtn
-│   │   ├── settings-handlers.js  # Manages gridSelect, synthesisSelect, languageSelect, fpsSelect
-│   │   ├── frame-processor.js    # Processes video frames (processFrame)
-│   │   └── event-dispatcher.js   # Routes events to handlers
-│   └── synthesis-methods/
-│       ├── grids/
-│       │   ├── hex-tonnetz.js
-│       │   └── circle-of-fifths.js
-│       └── engines/
-│           ├── sine-wave.js
-│           └── fm-synthesis.js
-│   
-├── tests/                     # Unit tests (TO_DO)
-│   ├── ui-handlers.test.js
-│   ├── trapezoid-handlers.test.js
-│   ├── settings-handlers.test.js
-│   └── frame-processor.test.js
-├── docs/                      # Documentation
-│   ├── USAGE.md
-│   ├── CHANGELOG.md
-│   ├── CONTRIBUTING.md
-│   ├── TO_DO.md
-│   ├── DIAGRAMS.md
-│   ├── LICENSE.md
-│   └── FAQ.md
-├── past/                     # Historic folder for older versions.
-├── future/                   # Meant to be used for fast, live testing of new features and improvements
-└── README.md
+web/
+├── audio/                    # Audio synthesis/processing (notes-to-sound, HRTF, mic)
+│   ├── audio-controls.js     # PowerOn/AudioContext init
+│   ├── audio-manager.js      # AudioContext management
+│   ├── audio-processor.js    # Core audio (oscillators, playAudio, cleanup; integrates HRTF/ML depth)
+│   ├── hrtf-processor.js     # HRTF logic (PannerNode, positional filtering)
+│   └── synths/               # Synth methods (extend with HRTF)
+│       ├── sine-wave.js
+│       ├── fm-synthesis.js
+│       └── available-engines.json
+├── video/                    # Video capture/mapping (camera-to-notes/positions; includes ML depth)
+│   ├── video-capture.js      # Stream setup/cleanup
+│   ├── frame-processor.js    # Frame analysis (emits notes/positions; calls ML if enabled)
+│   ├── ml-depth-processor.js # New: Monocular depth estimation 
+│   └── grids/                # Visual mappings 
+│       ├── hex-tonnetz.js
+│       ├── circle-of-fifths.js
+│       └── available-grids.json
+├── core/                     # Orchestration (events, state)
+│   ├── dispatcher.js         # Event handling 
+│   ├── state.js              # Settings/configs 
+│   └── context.js            # Shared refs
+├── ui/                       # Presentation (buttons, DOM; optional ML/HRTF toggles)
+│   ├── ui-controller.js      # UI setup
+│   ├── ui-settings.js        # Button bindings 
+│   ├── cleanup-manager.js    # Teardown listeners
+│   └── dom.js                # DOM init
+├── utils/                    # Cross-cutting tools (TTS, haptics, logs)
+│   ├── async.js              # Error wrappers
+│   ├── idb-logger.js         # Persistent logs
+│   ├── logging.js            # Structured logs
+│   └── utils.js              # Helpers (getText, ...)
+├── languages/                # Localization (add ML/HRTF strings)
+│   ├── es-ES.json
+│   ├── en-US.json
+│   └── available-languages.json
+├── test/                     # Tests (grouped by category)
+│   ├── audio/                # Audio/HRTF tests
+│   │   ├── audio-processor.test.js
+│   │   └── hrtf-processor.test.js
+│   ├── video/                # Video/grid/ML tests
+│   │   ├── frame-processor.test.js
+│   │   └── ml-depth-processor.test.js  # New: Test depth estimation
+│   ├── core/                 # Dispatcher/state tests (if added)
+│   ├── ui/                   # UI tests
+│   │   ├── ui-settings.test.js
+│   │   └── video-capture.test.js
+│   └── utils/                # Utils tests (if added)
+├── .eslintrc.json            # Linting
+├── index.html                # HTML entry
+├── main.js                   # Bootstrap (update imports for moves/ML init)
+├── README.md                 # Docs (update structure/ML/HRTF)
+└── styles.css                # Styles
 
 ```
 
 ### [Contributing](docs/CONTRIBUTING.md)
 
-- Please follow the link above for the detailed contributing guidelines, branching strategy and examples.
-
-### [To-Do List](docs/TO_DO.md)
-
-- At this document linked above, you will find the list for current TO TO list, we are now at milestone 4 (v0.4.X)
+>We welcome contributors! 
 
-Resume of TO_DO:
-
-- Haptic feedback via Vibration API 
-- Console log on device screen and mail to feature for debuggin. 
-- New languajes for the speech sinthetizer
-- Audio imput from camera into the headphones among the synthetized sound from camera.
-- Further Modularity: e.g., modularize audio-processor.js
-- Optimizations aiming the use less resources and achieve better performance, ie: implementing Web Workers and using WebAssembly.
-- Reintroducing Hilbert curves.
-- Gabor filters for motion detection.
-- New grid types and synth engines
-- Voting system for grid and synth engines.
-- Consider making User selectable synth engine version.
-- Consider adding support for VST like plugins.
-- Testing true HRTF, loading CIPIC HRIR data.
-- New capabilities like screen/video capture to sound engine.
-- Android/iOS app developtment if considerable performance gain can be achieved.
-- Mermaid diagrams to reflect current Modular Single Responsability Principle
+- At this document linked above, you will find the list for our current TO TO list, now from milestone 5 (v0.5.2)
 
 ### [Code flow diagrams](docs/DIAGRAMS.md) 
 
-Diagrams covering the Turnk Based Development approach. 
+Diagrams covering the Turnk Based Development approach (v0.2). 
 
-Reflecting:  
   - Process Frame Flow
   - Audio Generation Flow
   - Motion Detection such as oscillator logic.
+```mermaid
+
+graph TD
+        A[dispatcher.js] -->|routes| B[core/handlers/]
+        B --> C[video-handlers.js]
+        B --> D[audio-handlers.js]
+        B --> E[ui-handlers.js]
+        B --> F[settings-handlers.js]
+        B --> G[grid-handlers.js]
+        B --> H[debug-handlers.js]
+        C -->|calls| I[video/frame-processor.js]
+        D -->|calls| J[audio/audio-processor.js]
+        E -->|updates| K[ui/ui-settings.js]
+        F -->|uses| L[utils/utils.js]
+        A -->|state| M[state.js]
+        A -->|logs| N[utils/logging.js]
+        B -->|future| O[ml-handlers.js]
+```
+
+### [Changelog](docs/CHANGELOG.md)
+
+- Current "stable" version from "present" is v0.4.7, the link above logs the history and details past milestones achieved.
+- Current "future" version in development starts from v0.6 
+
+### [FAQ](docs/FAQ.md)
+
+- Follow the link for list of the Frecuently Asqued Questions.
 
 ### [License](docs/LICENSE.md)
 
 - GPL-3.0 license details
 
-### [FAQ](docs/FAQ.md)
+Peace
+Love
+Union
+Respect
+
 
-- Follow the link for list of the Frecuently Asqued Questions.