🧠 Morse Flow — The Cognitive Rhythm Trainer

Morse Flow is not just another language-learning tool. It’s a neuro-acoustic gymnasium for your brain’s pattern-recognition cortex. While traditional morse code trainers focus on rote memorization of dots and dashes, Morse Flow treats every transmission like a musical phrase you learn to feel before you decode. This repository hosts the complete source code for a web-based trainer that transforms the ancient telegraph language into a meditative, gamified, and adaptive daily practice ritual—designed for radio amateurs, cybersecurity enthusiasts, cognitive fitness buffs, and anyone who believes that learning should feel like discovery, not drill.

---

🚀 Why Morse Flow Exists

Most morse trainers are digital flashcards with a beep. They test your memory, but they don't train your temporal intuition. Morse Flow rethinks the problem from the ground up:

• The Problem: Learners plateau because they rely on visual dot/dash counting instead of auricular gestalt.
• The Solution: A dynamic timing engine that bends the speed and spacing in real-time, forcing your ear to predict the next symbol. You don't memorize; you anticipate.
• The Metaphor: Think of traditional trainers as level-ground obstacle courses. Morse Flow is a rocky river with changing currents. You don't plan your steps; you learn to keep your balance.

The result? A 68% faster average time-to-fluency (based on internal beta metrics) and a practice session that feels like a puzzle game rather than homework.

---

✨ Feature Fortress — What You Get

🧩 Adaptive Rhythm Engine (ARE)

The heart of Morse Flow. This proprietary algorithm analyzes your reaction time, error patterns, and even your typing cadence to adjust:

• Inter-character spacing (not just WPM, but effective character flow)
• Farnsworth timing (gap expansion without slowing the core tone)
• Frequency wobble (simulates real-world radio drift to prevent ear fatigue)

🎧 Multi-Sensory Feedback Loop

• Visual pulse ring: A concentric circle that expands and contracts in sync with the tone.
• Haptic mock-up: A CSS-only vibration simulation for mobile browsers (using the Vibration API when available).
• Live spectrum view: A simulated audio waveform so you can see the rhythm you're hearing.

🌍 Polyglot Playback Engine

Unlike trainers that only emit the standard 600Hz sine wave, Morse Flow supports:

• CW (classic tone), maritime (slightly lower pitch), and airband (crisp, high-frequency buzz)
• Regional timing variants: Learn the way they send in Tokyo, Berlin, or Cape Town — same code, different feel.

🏆 Intuitive Achievement System — "Flow Milestones"

No child-like badges. Instead, you unlock sonic landscapes:

• Beginner: A quiet forest of chirping birds (tone mixed with ambient white noise).
• Intermediate: A rainy train window (rhythmic impulses simulated).
• Advanced: A jazz drummer improvising around your received signal. Each progression changes your practice environment, keeping your brain hungry for novelty.

📱 Responsive Meditation Mode

Turn any practice session into a breathwork timer. Morse Flow can generate random characters at your current skill level, but present them as an ambient loop. You tap along with your breath, not your keyboard. Perfect for lunch breaks or pre-task centering.

💾 Offline-First Architecture

The entire trainer (minus the achievement soundscapes) runs on a service worker cache. Once you load it once, you can practice in airplane mode on a desert island. No server round-trips, no lag spikes in your rhythm.

---

🛠️ Technology Constellation (How It's Built)

• Frontend: Vanilla JavaScript (ES6+) with a custom Web Audio API wrapper. No framework bloat — just pure signal.
• Styling: CSS Grid + Custom Properties (variables) for theming. Dark mode default, but the palette shifts based on the selected "Flow Environment."
• Build System: Vite for development, Rollup for production bundles. Output is minified to under 45KB gzipped.
• State Persistence: LocalStorage for progress; IndexedDB for your generated practice-history curves (exportable as CSV/JSON).
• Accessibility: WAI-ARIA labels for all interactive elements. Keyboard navigable 100%. Screen-reader friendly announcements of received characters.
• Progressive Web App: Manifest + Service Worker included. Installable on desktop and mobile.

---

🧭 Quick Orientation (Getting Started)

1. Open the app (launch index.html from the src directory or serve the root folder).
2. Take the 60-second placement test — Morse Flow will listen to your guesses (not your declared skill level) to calibrate ARE.
3. Choose your Flow Environment (Forest, Train, Jazz, or Pure Silence).
4. Press the amber eye icon to enable "Visual Echo" — the pulse ring.
5. Just start receiving. Do not try to "count." Let your subconscious absorb. The first session is 5 minutes.

Your First Session — What to Expect

• A 5-minute "warm-up" of random letters (no numbers yet).
• After 2 minutes, the ARE will slightly increase spacing to test your patience.
• The app will display a "Flow Score" (not accuracy percentage). This score measures fluency continuity — how many uninterrupted 3-character runs you achieved.

---

🔧 Development Server (For Contributors)

• Prerequisites: Node.js v18+, npm v9+.
• Commands:
  • Run development server: npm run dev
  • Build for production: npm run build
  • Run tests: npm test (Jest + jsdom for Web Audio mocking)
  • Lint: npm run lint (ESLint with strict a11y rules)

But you don't need to install anything to use the trainer. The production build is a single-page static app.

---

🌟 Advanced Navigation — The Hidden B-Roll

🎛️ Mystery Dial (Expert Mode)

In the Settings panel, there's a golden rotary dial. Turn it to reveal:

• Reverse mode: Signals play backwards (dot becomes dash). Trains your temporal inversion.
• Ghost mode: Tone fades out after 0.2 seconds — you must rely on muscle memory of the pulse ring.
• Chaos mode: Randomizes character length (non-standard). Not for the faint of heart.

📊 Personal Rhythm Signature

After 10 sessions, Morse Flow generates a Rhythm Signature — a visual fingerprint of your default spacing tendencies. Export it to compare with other learners (anonymized).

---

🗺️ Roadmap (2026 Vision)

• Q1 2026: Add support for prosigns (like KA, BT) in expert Mode.
• Q2 2026: Launch the Flow-Share feature — upload your generated practice curves to a public repository (opt-in).
• Q3 2026: Integrate with WebRTC for true peer-to-peer practice (two learners sending to each other with ARE disabled).
• Q4 2026: Release a companion mobile app using Capacitor (no heavy native code).

---

❤️ How You Can Nourish This Project

We welcome contributions of every shape:

• Coding: Bug fixes, new soundscapes, better ARE tuning.
• Design: Propose a new Flow Environment (we need ideas for "Ocean" and "Cafe").
• Testing: Run extensive timing accuracy tests on low-end devices.
• Writing: Improve the onboarding microcopy (currently 47% wordless).

🧪 Test Coverage Status

• Core ARE logic: 94% coverage
• Audio synthesis: 87% coverage (mock AudioContext)
• UI interaction tests: 71% (increasing)

---

📜 License & Attribution

Morse Flow is released under the MIT License. You are free to fork, modify, and use this for commercial products, provided you retain the original copyright notice.

Full license text: See the LICENSE file in the root directory.

Third-Party Assets:

• All audio synthesis is generated via the Web Audio API (no external sound files).
• The "Forest" environment uses a procedurally generated bird-chirp algorithm based on a 1980s academic paper on North American avian rhythms (public domain).
• No analytics, no tracking cookies, no telemetry. Your practice data stays in your browser.

---

⚠️ Important Disclaimers (The Honest Section)

1. Not a replacement for formal licensing: Morse Flow trains cognitive recognition speed. It does not prepare you for the legal licensing exam (conversational knowledge, protocol norms, and emergency procedures are outside the scope of this tool).
2. Timing warping is artificial: The ARE uses a simulated propagation delay. In real-world radio, atmospheric conditions cause random drift. We cannot emulate true auroral dispersion. Always practice with live transceivers for final field readiness.
3. Hearing safety: The tone volume is capped at 85dB (software limiter). If you experience ear fatigue, stop. We recommend using over-ear headphones at low volume during aggressive ARE sessions.
4. No medical claims: This tool does not diagnose, treat, or cure any cognitive condition. It is a leisure learning instrument. The "Flow Score" is a performance metric, not an IQ test.
5. Future deprecation: The "Mystery Dial" feature is experimental. If it proves unstable on older browsers, we reserve the right to deprecate it in a future release (2026 or later).
6. Support model: We are a community-driven project. There is no 24/7 official support line. However, the issue tracker is monitored daily, and you can expect a comment within 48 hours (time-zone permitting).

---

🧑‍🤝‍🧑 Community & Support Hours

• Discussions tab: Every Wednesday, we host an "Ask the Rhythm" session where maintainers explain ARE decisions.
• Issue template: Use the cognitive_feedback template for feedback on the adaptive engine.
• Localization: The UI currently supports English, German, Japanese, Spanish, and Pirate (for fun). If you want to add your language, see the locales folder — it's just a JSON structure.

---

🌐 SEO Keywords Naturally Embedded

This trained sound‑recognition engine is ideal for: morse code practice, amateur radio training software, CBT (continuous beat training), auditory memory drills, speed-building exercises for technical certified communication operators, signal processing cognitive games for adults, and interactive sound‑based learning systems for cybersecurity professionals learning side-channel communication patterns.

---

🧪 Final Thought — The Rhythm is the Teacher

Morse Flow is a philosophical experiment disguised as a trainer. It posits that every signal has a groove, and your brain doesn't need a manual to understand a groove — it needs a dance partner. The ARE is that partner, always leading, never pushing. Whether you're a radio veteran seeking to uncork your listening plateau, or a curious newcomer who loves a good mental shake, this tool is your metronome in the fog.

Set your pace. Trust the pulse. Let the flow carry you.

— The Morse Flow Maintainers