Projects/typestoryProduction Verified

TypeStory // Touch Typing & Engineering Stories

An interactive touch-typing and software engineering vocabulary platform featuring mechanical switch audio synthesis via Web Audio API, native speech narration, and real-world system architecture literature.

#nextjs#react#typescript#tailwindcss#web-audio-api#open-source#education
Live DemoView Source

The Latency Problem in Keyboard Audio Feedback

Most web-based typing tools simulate mechanical switch sounds by playing pre-recorded .mp3 or .wav sample files triggered on window.keydown.

At fast typing speeds (80–120+ WPM), this approach breaks down completely:

  1. Audio Latency Jitter: Instantiating or rewinding HTML5 <audio> elements incurs a 20–60 ms execution delay, causing acoustic feedback to desynchronize from tactile finger impact.
  2. Polyphony Clipping: Rapid multi-key bursts (e.g. typing "the" in 80ms) create audio channel collisions, leading to audio buffer starvation and unpleasant popping artifacts.
  3. Network Overhead: Bundling high-fidelity switch sound packs adds hundreds of kilobytes to megabytes of static asset bandwidth.

TypeStory eliminates all static audio files by synthesizing mechanical switch clicks procedurally in real time using the browser-native HTML5 Web Audio API.

TypeStory Touch Typing & Engineering Architecture

Procedural Audio Synthesis Engine

┌────────────────────────────────────────────────────────────────────────┐
│                   Web Audio API Procedural Pipeline                    │
├────────────────────────────────────────────────────────────────────────┤
│ [Keydown Event]                                                        │
│       │                                                                │
│       ▼                                                                │
│ [AudioContext]                                                         │
│       ├──> [OscillatorNode] (Base Pulse: Sine / Square)                │
│       │          │                                                     │
│       │          ▼                                                     │
│       ├──> [BiquadFilterNode] (High-Pass / Resonance Shaper)           │
│       │          │                                                     │
│       │          ▼                                                     │
│       └──> [GainNode Envelope] (Exponential Decay Curve: 8-25ms)       │
│                  │                                                     │
│                  ▼                                                     │
│       [AudioDestinationNode (Hardware Output)]                         │
└────────────────────────────────────────────────────────────────────────┘

Acoustic Switch Modeling

  • Cherry MX Blue (Clicky):
    • Generates a dual-impulse transient: an initial high-frequency click (f = 3,200\text{ Hz}, t = 6\text{ms}) combined with a lower tactile bottom-out report (f = 950\text{ Hz}).
    • Shaped by a steep exponential gain decay curve to replicate mechanical leaf spring release.
  • Cherry MX Brown (Tactile):
    • Generates a rounded tactile bump using a low-frequency square wave passed through a 450 Hz low-pass filter with heavy resonance dampening.
  • Bubble Pop:
    • Fast sine wave frequency sweep (400\text{ Hz} \to 1,200\text{ Hz} in 15\text{ms}) with a soft parabolic amplitude envelope.

Zero Audio Asset Footprint: The entire audio synthesizer is executed in pure mathematical JavaScript code with 0 KB external audio downloads.

Technical Architecture & Core Subsystems

1. Contextual Literature Engine

  • Unlike conventional typing tutors that cycle through randomized character permutations ("asdf jkl;"), TypeStory trains muscle memory directly on production software engineering literature:
    • Distributed Systems (Raft consensus algorithm, Paxos, split-brain mitigation).
    • High-throughput Backends (Docker BuildKit caching, Redis event loops, Python memory profiling).
    • Classic Literature & Speeches (Steve Jobs Stanford address, Aesop's fables).
  • Trilingual English-Vietnamese glossary tooltips with phonetics, parts of speech, and CEFR level classification.

2. Client-Side SpeechSynthesis Narration

  • Utilizes the browser's native window.speechSynthesis API with variable playback rates (0.75\text{x} to 1.5\text{x}).
  • Enables engineers to hear native pronunciation of technical terms before or during typing drills with zero server API costs and zero cloud latency.

3. Touch-Typing Virtual Ergonomic Map

  • Dynamic on-screen QWERTY map highlighting active target keys, Shift modifiers, and tactile home-row bumps (F and J).
  • Five color-coded ergonomic finger zones (Pinky, Ring, Middle, Index, Thumb) providing real-time finger placement recommendations.

4. Local Performance Analytics & CSV Export

  • Automatic localStorage session recording tracking WPM velocity, error rates, and consecutive daily streak milestones (🔥 X Days).
  • Visual Speed Trend SVG sparkline with non-zero calibrated axes.
  • RFC 4180-Compliant CSV Export: Implements UTF-8 Byte Order Mark (BOM) for compatibility with Excel and escapes formula-leading characters (=, +, -, @) to neutralize CSV injection vectors.

Tech Stack

  • Framework: Next.js 16 (App Router)
  • Language & Primitives: TypeScript 5, React 19, Tailwind CSS 4
  • Audio Synthesis: HTML5 Web Audio API (OscillatorNode, BiquadFilterNode, GainNode)
  • Speech Engine: Native Web Speech API (SpeechSynthesisUtterance)
  • State Management: Zustand with local persistence
  • Deployment: Vercel Edge Network

Links & Live Demo

Dev Kits & DataToolsTagsRSSPrivacy PolicyTerms