CodeSound 🎧

Mechanical keyboard clicks, lo-fi beats, and ambient sounds that adapt to your typing speed and the file you're currently editing — now with themes, productivity alerts, a typing stats dashboard, a live equalizer, and a focus timer.

• ⚡ Speed-aware typing clicks — soft clicks while you think, sharper/ faster clicks when you're in a flow burst, with 3 randomized variants per tier so it doesn't sound robotic.
• 🌧️ Mood-aware ambience — calm rain while writing docs, intense synth-wave while editing config files, lo-fi beats for everyday code.
• 🎵 Bring your own sounds — add any mp3/wav/ogg file and assign it to a file type or typing-speed tier.
• 🎨 One-click themes — Cyberpunk Night, Cozy Cafe, Deep Focus Lo-fi, Rainy Library — each bundles ambience + click style + volumes.
• 🔔 Productivity alerts — a chime on save, a success/error sound when a build or test task finishes, and a quick mute shortcut (Ctrl+Alt+M).
• 📊 Stats dashboard — live session time, typing speed (WPM), keystroke counters, and milestone achievements (with their own little chime).
• 🎚️ Live equalizer — a real-time frequency visualizer reacting to whatever's actually playing.
• ⏱️ Focus timer — a simple in-panel countdown timer with a completion chime.

Install (from source)

git clone <this-repo>
cd codesound
npm install
npm run compile

Then press F5 in VS Code to launch an Extension Development Host with CodeSound loaded, or package it with vsce (see below).

Using it

CodeSound never opens anything automatically — typing or switching files won't pop up a tab. Everything lives in one control panel docked at the bottom panel area, next to Terminal/Output/Debug Console — not a split editor tab, so it doesn't push your code aside.

1. Click 🎧 CodeSound in the bottom status bar (or run "CodeSound: Open Control Panel" from the Command Palette, or click the "CodeSound" tab next to Terminal at the bottom).
2. The panel has every feature in one place:
   • On/off switches for the whole extension, typing clicks, and ambient sound
   • Volume sliders (master / typing / ambient)
   • A list of ambient tracks and click sounds with ▶ play/preview buttons
   • A "+ Add Song / Sound" button — pick any mp3/wav/ogg file, give it an id, and it shows up immediately with a ✕ remove button
   • A link to the full settings (file-type mapping, typing-speed tiers, etc.)
3. Sound keeps playing even if you switch away from the panel, hide the bottom panel entirely (Ctrl+/Cmd+), or click into Terminal/Output instead. Unlike a normal editor tab, this panel doesn't get destroyed when you stop looking at it — it only stops if you close the whole VS Code window or reload it. Opening it once per session is enough.

Default sounds (included)

CodeSound ships with default sounds out of the box — 3 keyboard click tiers and 4 ambient loops (lo-fi beats, calm rain, intense synth-wave, coffee shop). They're procedurally generated (synthesized from oscillators and filtered noise, not samples), so there's no licensing baggage. They're intentionally simple — meant to work immediately, not to be the best sound design ever. See assets/sounds/README.md for filenames if you want to swap any of them out.

Add your own sounds (dynamically, no rebuild needed)

Anytime, from the Command Palette:

CodeSound: Add Custom Sound File...

This opens a file picker, asks you for a sound id and label, and saves it to the codesound.customSounds setting. Reference that id in codesound.fileTypeMap or codesound.typingSpeedTiers to use it.

New in v0.6.0

More keyboard sound styles to choose from — beyond soft/normal/sharp, there are now 3 more distinct profiles: 🖨️ Typewriter Clack, 🫧 Membrane Bubble, and 🪵 Deep Thock. In the panel's new "Keyboard sound (by typing speed)" section, pick which style plays for slow/medium/fast typing independently — selecting one previews it instantly.

Real Save button. Toggles, volume sliders, and keyboard-sound selections are now staged — they preview live (volume sliders adjust the currently playing track immediately; sound dropdowns play a preview) but don't actually get written to your settings until you click 💾 Save at the top of the panel. An indicator shows "● Unsaved changes" while you're mid-edit and "✅ Saved" right after you commit. Themes, adding/removing sounds, and the focus timer remain instant — those already act as one-shot actions, not settings to batch up.

New in v0.5.0

Fixed: "Add Custom Sound" could throw an error and silently fail to save. Recent VS Code versions return a frozen (read-only) array from config.get(). The old code called .push() directly on that array, which throws instead of failing quietly. Adding a sound now builds a fresh array instead, and every settings-changing command has proper error handling so any future failure shows a real message instead of just not working.

Extended key coverage — arrow keys, Home, End, and Page Up/Down now also trigger a click sound. VS Code has no API to observe raw keystrokes, so previously only keys that actually inserted/deleted text (which is most of them — Enter, Tab, Backspace, Delete, Space, letters) triggered a sound; pure cursor movement didn't. This adds explicit keybindings for just those navigation keys. Toggle via codesound.extendedKeyCoverage.enabled (default on) if it ever conflicts with another extension's keybindings (e.g. Vim emulation) — and remember VS Code always lets your own keybindings.json override an extension's, so you can always rebind around a conflict. Escape, Tab, and Enter are deliberately not covered — they're too overloaded by other VS Code features (autocomplete, popups, snippets) to safely take over.

New in v0.4.0

Themes — open the panel and click any card in the "Themes" section (🌃 Cyberpunk Night, ☕ Cozy Cafe, 🎧 Deep Focus Lo-fi, 🌧️ Rainy Library) to instantly apply a bundle of ambient mapping + click style + volumes.

Productivity alerts — a short chime on every file save, and a success or error sound whenever a build/test/run task finishes (hooked into VS Code's task system). Toggle both independently in the panel's "Productivity alerts" section. Quick mute: Ctrl+Alt+M (Cmd+Alt+M on Mac).

Stats dashboard — the panel's "Stats" section shows live session time, current typing speed (WPM, from a rolling window so it reflects your actual pace, not a slow session-average), keystroke/click counters, and lifetime totals persisted across restarts. Crossing keystroke/session milestones unlocks a small achievement (with its own chime).

Live equalizer — a real-time frequency-bar visualizer above "Now playing", driven by the actual Web Audio frequency data of whatever ambient track is active.

Focus timer — set a number of minutes, hit Start, and get a countdown plus a completion chime when it finishes. Independent of the typing/ambient system, so it works as a plain mini-Pomodoro even with sound off.

Commands

Themes, the focus timer, and live stats are panel-only (no standalone command) since they need the interactive UI.

Settings

All settings live under codesound.* in your VS Code settings (Ctrl+, / Cmd+,, search "CodeSound"):

• codesound.enabled — master on/off
• codesound.typingSounds.enabled, codesound.ambientSounds.enabled
• codesound.masterVolume, codesound.typingVolume, codesound.ambientVolume
• codesound.idleTimeoutSeconds — pause ambience after inactivity
• codesound.pauseOnFocusLoss — pause everything when VS Code isn't focused
• codesound.fileTypeMap — { "json": "synthwave_intense", "markdown": "rain_calm", ... }
• codesound.testFilePattern — regex used to detect test files
• codesound.typingSpeedTiers — { "slow": {"maxKps":2,"soundId":"click_soft"}, ... }
• codesound.customSounds — populated automatically by the "Add Custom Sound" command
• codesound.alerts.saveSound.enabled — chime on file save
• codesound.alerts.taskSounds.enabled — success/error sound on task completion
• codesound.alertsVolume — volume for save/build/test/achievement/timer sounds

Example settings.json snippet:

"codesound.fileTypeMap": {
  "default": "lofi_beats",
  "json": "synthwave_intense",
  "yaml": "synthwave_intense",
  "markdown": "rain_calm",
  "test": "coffee_shop_energetic"
},
"codesound.masterVolume": 0.5

How it works (architecture notes)

VS Code extensions run in a Node.js host process with no direct audio output API. To actually play sound, CodeSound registers a WebviewView docked in the Panel area (next to Terminal) containing an HTML <audio> player, and the extension talks to it via postMessage. A WebviewView is used instead of a WebviewPanel specifically because panels are editor tabs that get destroyed (and stop audio) the moment you close them — views in a container only hide when you switch away, and with retainContextWhenHidden they keep running in the background.

• src/typingTracker.ts — rolling-window keystroke-rate calculator
• src/fileTypeDetector.ts — maps the active document to a mood/sound id
• src/statsTracker.ts — session + lifetime stats, milestone achievements
• src/presets.ts — curated theme bundles (fileTypeMap + click style + volumes)
• src/audioManager.ts — implements WebviewViewProvider, crossfades ambient loops, pools <audio> elements so rapid clicks can overlap, runs the live equalizer, and renders the whole control panel UI
• src/extension.ts — wires it all together: view provider, commands, settings, save/task alert hooks, focus timer

Packaging for the Marketplace

npm install -g @vscode/vsce
vsce package

This produces a .vsix you can install via Extensions: Install from VSIX... or publish with vsce publish.

Roadmap ideas

• Per-workspace sound profiles
• Visualizer status-bar "now playing" ticker
• Sound packs shareable as JSON presets

License

MIT — see LICENSE. Every bundled sound under assets/sounds/ is procedurally synthesized from scratch (not samples), so it's covered by the same license and free to reuse or modify.