I do a lot of doc-heavy and review-heavy work, and I kept losing time re-reading dense markdown and PRs instead of just listening to them. "Just use a screen reader" doesn't really work for code — it reads asterisks and pound signs literally instead of understanding markdown structure. So I built Markdown TTS, a VS Code extension that actually parses the content first, then speaks it.
What it does
Two distinct modes:
1. Literal reading — strips markdown syntax properly (headings become "Heading level 2: ...", tables read as CSV, code blocks skipped, links keep their text) and reads it aloud via your OS's built-in voice — SAPI on Windows, say on macOS. Fully offline, no API key, no account. There's also an optional Microsoft Edge neural voice mode if you want higher quality and don't mind the request leaving your machine.
2. AI narration (bring your own key) — instead of reading a file verbatim, an LLM explains what it does in plain English, then narrates that explanation. There's also a command that runs git diff locally and speaks an AI summary of your uncommitted changes or last commit, which I now use as a last check before committing instead of re-reading a wall of red and green text. Works with OpenAI, Anthropic, or Groq (free tier, no card needed). Only these two commands ever contact an API — literal reading stays completely offline.
It also does voice input into Copilot Chat, triggering your OS's native dictation (Win+H on Windows, Start Dictation on macOS) instead of implementing its own speech recognition.
A few implementation details
- Single-file extension, ~1100 lines, no framework
- Windows local TTS is done by spawning PowerShell running
System.Speech.Synthesis.SpeechSynthesizer. Pause/resume goes through a control file, since SAPI has no native pause primitive exposed from that surface - The Edge neural voice path splits text into ~1.5KB chunks and prefetches two chunks ahead over parallel WebSockets, so long files start speaking in seconds instead of blocking on a multi-minute synth job
- Voice input triggers OS-native dictation rather than doing speech recognition itself — much simpler, and it means dictation quality is whatever your OS already gives you
One decision I'm fairly happy with: the extension ships no default keybindings. The obvious choice, Ctrl+Alt+<letter>, collides with AltGr on a lot of non-US keyboard layouts (Indian, German, French, Spanish, Nordic, and others), where the OS types an accented character instead of running the command. Rather than hijack keys that silently break for a large share of users, you bind exactly the ones you want yourself.
A use case I didn't originally plan for: reading agent skill files
A lot of AI coding tools now configure their behavior entirely through markdown — Claude Code's SKILL.md files, CLAUDE.md project instructions, Cursor's .cursor/rules files, and similar formats elsewhere. These are exactly the kind of structured markdown — nested headings, bullet lists, embedded code blocks — that this extension already handles well for docs and PRs. Pointing it at an agent skill file works the same way as pointing it at any other doc. Given how much of a developer's actual working files are turning into agent-config markdown instead of prose these days, this has quietly become one of the more practical everyday uses of it.
Where it's useful beyond the obvious
A few people who've tried it mentioned it's genuinely helpful for dyslexia and general screen-reader-adjacent use cases — that wasn't the original motivation (I built it for my own PR-review workflow), but it's turned out to matter more than I expected.
Current state
Free, 121 installs so far with basically zero marketing push until this week. Linux only gets the Edge voice path for now — no local TTS binary to shell out to there yet.
If you try it, I'd genuinely like to hear what's missing, or where it feels like a gimmick instead of something you'd actually keep in your workflow.
Marketplace: https://marketplace.visualstudio.com/items?itemName=AbhishekShr.markdown-tts
Top comments (0)