piper-reader

Read any text or markdown file aloud using piper-tts - a fast, local, offline text-to-speech engine. Available as a VSCodium/VS Code extension and a standalone CLI script.

Features

• Reads plain text and markdown files aloud via piper-tts (own installation, called via wrapper)
• Strips markdown syntax before speaking (no asterisks, hashes, or bracket noise)
• Paragraph-by-paragraph generation with progress display
• Pitch-preserving speed control via sox tempo (settings)
• Pause and resume playback at the exact audio position
• Save output to WAV file
• Download voice models directly from Hugging Face
• VSCodium/VS Code extension with context-aware tab menu (no keyboard shortcuts for now, sorry!)

Platform Compatibility

Why?

This project started out of frustration - I just wanted a simple way to listen to long Markdown files, technical documentation, notes, and personal write-ups while doing something else. I assumed there would already be a lightweight extension for VSCodium that worked offline with Piper TTS - but there wasn't.

Most text-to-speech extensions I found depended on cloud services, browser APIs, subscriptions, API keys, or online accounts. Others were difficult to configure, weren't available in the Open VSX marketplace, or simply didn't fit the workflow I wanted. While offline and local-first TTS tools are becoming more common, many solutions still focus on web services or broader platforms rather than a simple editor integration.

So I stopped searching, and started building. Piper Reader is the tool I wanted to install (I think lol):

• Read Markdown and text files directly from the editor.
• Completely offline.
• No API keys.
• No subscriptions.
• No accounts.
• Uses your own local Piper voice models (download it yourself).
• Simple enough to set up once and forget about.

If it saves someone else from spending an evening searching through extension marketplaces like I did, then building it was worth it.

This isn't trying to be the most feature-rich TTS extension. It's trying to be the one that gets out of your way and lets you listen to your documents.

VSCodium / VS Code Extension

Installation

Install from VSIX:

codium --install-extension piper-reader-0.0.x.vsix

Or via the UI: Extensions panel -> ... -> "Install from VSIX..."

Requirements

• piper-tts -- pip install piper-tts
• sox -- sudo dnf install sox (Linux) / brew install sox (macOS)
• At least one piper voice model (.onnx + .onnx.json)

Windows: not supported. The extension relies on a bash script and sox for audio playback. WSL is not officially supported either.

Setup

Open Settings (Ctrl+,) and search for Piper Reader. Set at minimum:

Usage

Right-click any open editor tab. The menu adapts to the current playback state:

Click the status bar item (shown while reading) to stop playback at any time. The status bar shows per-paragraph progress ([1/5] playing...) while active, and Paused [N/M] when frozen.

Selection mode: highlight any text in the active editor before invoking Piper Read and only the selected text will be spoken. If nothing is selected, the whole file is read.

All Settings

CLI Usage

Requirements

Windows: not supported. The script requires bash and sox. Windows users would need WSL, but audio routing via WSL is not officially supported.

Install

git clone https://github.com/linellazatin/piper-tts-reader.git
cd piper-tts-reader
chmod +x piper-reader

Optionally symlink to PATH:

ln -s "$PWD/piper-reader" ~/.local/bin/piper-reader

Configuration

VOICES_DIR has no baked-in default. You must set it before using --list, --download, or reading any file, or you will get an error. Do this in one of three ways:

Option A -- conf file beside the script (recommended for CLI use):

# piper-reader.conf
MODEL=en_US-amy-medium
VOICES_DIR=/path/to/your/voices

Option B -- env var pointing to any config file:

export PIPER_READER_CONFIG=/path/to/my-piper.conf

Option C -- CLI flag per invocation:

./piper-reader --voices-dir /path/to/your/voices notes.md

Full config reference:

MODEL=en_US-amy-medium
VOICES_DIR=/path/to/voices
LENGTH_SCALE=1.0
NOISE_SCALE=0.9
NOISE_W_SCALE=0.85
SENTENCE_SILENCE=0.4
VOLUME=0.75
SOX_GAIN=-1
TEMPO=1.1
SAMPLE_RATE=22050

Config resolution order:

1. PIPER_READER_CONFIG env var (if set, path to a config file)
2. piper-reader.conf beside the script (if present)
3. Baked-in defaults (no VOICES_DIR -- must be set explicitly)

All values can be overridden per-invocation via CLI flags.

Examples

# Read a file aloud
./piper-reader notes.md

# Read from stdin
echo "Hello world" | ./piper-reader
cat article.txt | ./piper-reader

# Tune voice on the fly
./piper-reader --noise-scale 0.9 --tempo 0.95 notes.md

# Save to WAV instead of playing
./piper-reader --output speech.wav notes.md

# Use a specific model
./piper-reader --model en_US-lessac-high notes.md

# Multi-speaker model
./piper-reader --model en_US-libritts-high --speaker 5 notes.md

# List downloaded models
./piper-reader --list

# Download a model
./piper-reader --download en_US-amy-medium

Flag Reference

Markdown Stripping

The following is stripped before text reaches piper:

• Fenced code blocks
• Inline code backticks (content kept)
• Headers
• Bold (**text**, __text__)
• Images (removed entirely)
• Links (link text kept)
• HTML tags
• Horizontal rules

Voice Models

Browse and audition voices at rhasspy.github.io/piper-samples.

Download via CLI (requires VOICES_DIR to be set in your config, or pass --voices-dir):

./piper-reader --download en_US-amy-medium
./piper-reader --download en_US-ryan-high

# or without a config file:
./piper-reader --voices-dir ~/voices --download en_US-amy-medium

Or browse the full list at huggingface.co/rhasspy/piper-voices.

License

MIT