MurMur 🗣️

### Read Any Page Aloud MurMur works on virtually any webpage. Click the toolbar icon or press **Alt+Shift+R** and MurMur instantly extracts the article content, strips away ads and navigation clutter, and begins reading. It works on:

### Real-Time Word Highlighting Every word is highlighted as it's spoken. The current word gets a bright yellow highlight and the active paragraph is subtly marked, so you always know exactly where the reader is. Past paragraphs fade slightly to give you a clear sense of progress.

### Two Reading Modes

**Overlay Mode** — Opens a clean, distraction-free reader view on top of the page. The article is reformatted in a comfortable reading layout with generous margins, clean typography, and a dark background overlay. Perfect for focused reading sessions.

**Inline Mode** — Highlights words directly on the original page without changing the layout. The page stays exactly as it is and MurMur annotates words in place as they're spoken. Great for following along with the original formatting, images, and context.

Switch between modes instantly from the control panel — your preference is saved automatically.

### Google Docs Support MurMur is one of the few text-to-speech extensions that works with Google Docs. It uses the canvas annotation API to extract text directly from the document, including:

• Full document text extraction from SVG annotation layers
• Legacy HTML renderer support for older document formats
• Document title detection
• Automatic annotation layer initialization at page load

Just open any Google Doc and click MurMur — it handles the rest.

### Multiple Voices and Languages MurMur supports a wide range of voices and languages through two TTS engines:

**Chrome Built-in Voices**

• English (US and UK) — Google high-quality voices
• Spanish, French, German, Portuguese, Italian, Dutch
• Chinese (Mandarin, Cantonese), Japanese, Korean
• Hindi, Arabic, Russian, Polish, and many more
• All voices available through Chrome's native TTS engine

**Piper AI Voices (Local)**

• Hundreds of neural network voices powered by Piper TTS
• Runs entirely in your browser — no data sent to external servers
• Natural-sounding AI voices for dozens of languages
• Available in multiple quality levels (low, medium, high)
• Includes voices for less common languages like Bulgarian, Catalan, Czech, Danish, Finnish, Georgian, Greek, Hungarian, Icelandic, Kazakh, Luxembourgish, Nepali, Norwegian, Romanian, Serbian, Slovak, Slovenian, Swahili, Swedish, Ukrainian, Vietnamese, and more

**Automatic Language Detection** MurMur automatically detects the language of the page using: 1. The HTML `lang` attribute 2. Content-Language meta tags 3. Trigram-based text analysis for 8 languages (English, Spanish, French, German, Portuguese, Italian, Dutch, Bulgarian)

The voice selector automatically filters to show relevant voices for the detected language.

### Adjustable Speed Without Pitch Change Control the reading speed from 0.5x to 3x using the slider or keyboard shortcuts:

• **Arrow Up** — Increase speed by 0.25x
• **Arrow Down** — Decrease speed by 0.25x

For Chrome voices, the rate is applied directly to the TTS engine. For Piper AI voices, MurMur adjusts the `length_scale` parameter at synthesis time, which changes the speech duration without altering the pitch. This means faster playback sounds natural — not like a chipmunk.

### Sentence Chunking Long paragraphs are automatically split into sentence-sized chunks (up to 150 characters) before synthesis. This dramatically improves responsiveness — you hear the first sentence almost immediately while subsequent sentences are prepared in the background. The chunker:

• Splits on sentence boundaries (`.` `!` `?`)
• Protects abbreviations (Dr., Mr., Mrs., Prof., etc.) from false splits
• Preserves decimal numbers and ellipses
• Merges short sentences together for natural pacing
• Falls back to clause splitting (on `,` `;` `:` `—`) for very long sentences

### Custom Pronunciation Rules (See-Say) MurMur includes 18 built-in pronunciation rules and lets you add your own:

**Built-in rules include:**

• Dr. → Doctor, Mr. → Mister, Mrs. → Missus, Ms. → Miss
• Citation brackets [1], [2] etc. → skipped
• Common units: km/h, mph, kg, lbs, ft, oz, etc.
• Mathematical symbols and abbreviations

**Custom rules:**

• Add your own see → say substitutions from the Pronunciation panel
• Rules are synced across devices via Chrome storage
• Supports whole-word matching and regular expressions
• The original text is always displayed unchanged — only the spoken version is substituted
• Highlight positions are correctly remapped through an offset map so highlighting stays accurate even after text substitution

### Keyboard Shortcuts Full keyboard control without touching the mouse:

| Key | Action | |-----|--------| | **Space** | Play / Pause | | **Left Arrow** | Previous paragraph | | **Right Arrow** | Next paragraph | | **Up Arrow** | Increase speed | | **Down Arrow** | Decrease speed | | **Escape** | Close MurMur | | **Alt+Shift+R** | Toggle MurMur on/off |

Keyboard shortcuts are automatically disabled when you're typing in input fields, textareas, select dropdowns, or contentEditable elements.

### Smart Tab Management Only one instance of MurMur runs at a time across all your browser tabs:

• Opening MurMur in a new tab automatically stops reading in the previous tab
• Closing a tab that's actively reading stops playback and cleans up resources
• No orphaned audio or background processes

### Privacy First

• **No accounts required** — install and use immediately
• **No data collection** — MurMur doesn't track, store, or transmit any of your browsing data
• **Local AI processing** — Piper TTS voices run entirely in your browser using WebAssembly
• **Minimal permissions** — only requests `activeTab`, `scripting`, `storage`, `tts`, and `offscreen`
• **Open architecture** — all code runs client-side in the extension

## How It Works

### For Regular Webpages 1. Click the MurMur icon or press **Alt+Shift+R** 2. MurMur uses Mozilla's Readability library to extract the article content 3. The text is split into paragraphs and tokenized into words 4. A clean reader overlay appears (or inline annotations are applied) 5. Press play and listen as each word is highlighted in real time

### For Google Docs 1. MurMur injects a canvas annotation flag at page load (`document_start`) 2. This enables SVG text rendering in the Google Docs canvas 3. When activated, MurMur reads paragraph elements from the SVG annotation layer 4. Text is extracted, tokenized, and read aloud with the same highlighting experience

### For Pages Without Articles If Readability can't detect a structured article, MurMur falls back to: 1. Starting with the page title 2. Extracting all visible text blocks from the page body 3. Filtering out navigation, footer, header, and aside elements 4. Reading the remaining content in document order

## Supported Languages

MurMur supports text-to-speech in dozens of languages through Chrome's built-in voices and Piper's AI voice library:

| Language | Chrome Voices | Piper AI Voices | |----------|:---:|:---:| | English (US, UK) | Yes | Yes | | Spanish | Yes | Yes | | French | Yes | Yes | | German | Yes | Yes | | Portuguese | Yes | Yes | | Italian | Yes | Yes | | Dutch | Yes | Yes | | Bulgarian | — | Yes | | Catalan | — | Yes | | Chinese (Mandarin) | Yes | Yes | | Czech | — | Yes | | Danish | — | Yes | | Finnish | — | Yes | | Georgian | — | Yes | | Greek | Yes | Yes | | Hindi | Yes | Yes | | Hungarian | — | Yes | | Icelandic | — | Yes | | Japanese | Yes | Yes | | Kazakh | — | Yes | | Korean | Yes | Yes | | Nepali | — | Yes | | Norwegian | — | Yes | | Polish | Yes | Yes | | Romanian | — | Yes | | Russian | Yes | Yes | | Serbian | — | Yes | | Slovak | — | Yes | | Slovenian | — | Yes | | Swahili | — | Yes | | Swedish | — | Yes | | Turkish | Yes | Yes | | Ukrainian | — | Yes | | Vietnamese | — | Yes | | Arabic | Yes | Yes |

## Technical Architecture

MurMur is built as a Chrome Manifest V3 extension with the following components:

### Content Scripts

• **Article Extractor** — Uses Mozilla Readability for article parsing with fallback extraction for non-article pages. Includes Google Docs SVG and KIX renderer support.
• **TTS Engine** — Orchestrates speech synthesis with sentence chunking, see-say text substitution, and dual-backend support (Chrome TTS and Piper AI).
• **Highlight Manager** — Builds the reader DOM with word-level spans for precise highlighting in overlay mode.
• **Inline Highlight Manager** — Annotates the original page DOM using TreeWalker-based text node wrapping for inline mode.
• **Reader Overlay** — Shadow DOM-isolated full-screen reader view with clean typography.
• **Control Panel** — Shadow DOM-isolated floating panel with playback controls, speed slider, voice/language selectors, mode toggle, and pronunciation rule editor.
• **Keyboard Handler** — Global keyboard shortcut handler with smart focus detection.
• **Sentence Chunker** — Splits paragraphs into sentence-sized chunks with abbreviation protection.
• **See-Say Rules** — Text substitution engine with offset mapping for highlight remapping.
• **Reading State** — Tracks current paragraph position and calculates progress.

### Background Service Worker

• Tab lifecycle management (single-instance enforcement)
• Chrome TTS API proxy (speak, pause, resume, stop, getVoices)
• Piper voice list fetching from HuggingFace
• Offscreen document management for Piper WASM execution
• Script injection orchestration

### Offscreen Document

• Piper TTS WebAssembly runtime
• ONNX neural network inference for voice synthesis
• eSpeak-ng phonemizer for text-to-phoneme conversion
• Speed control via `length_scale` parameter manipulation

### TTS Backend Race Pattern MurMur includes infrastructure for racing the primary TTS backend against a timeout with automatic fallback to a secondary backend. Currently configured as a transparent pass-through, this architecture is ready for future enhancements like automatic local/cloud failover.

## Installation

### From the Chrome Web Store 1. Visit the MurMur page on the Chrome Web Store 2. Click "Add to Chrome" 3. Click the MurMur icon on any webpage to start listening

### For Development 1. Clone the repository 2. Open `chrome://extensions` in Chrome 3. Enable "Developer mode" 4. Click "Load unpacked" and select the project directory 5. The MurMur icon appears in your toolbar

## Keyboard Reference

| Shortcut | Action | |----------|--------| | `Alt+Shift+R` | Toggle MurMur on any page | | `Space` | Play or pause reading | | `←` | Skip to previous paragraph | | `→` | Skip to next paragraph | | `↑` | Increase reading speed | | `↓` | Decrease reading speed | | `Esc` | Close MurMur |

## Permissions Explained

| Permission | Why | |------------|-----| | `activeTab` | Access the current page to extract article text | | `scripting` | Inject content scripts for text extraction and highlighting | | `storage` | Save your preferences (speed, voice, mode, pronunciation rules) | | `tts` | Access Chrome's built-in text-to-speech engine | | `offscreen` | Run Piper TTS WebAssembly in a background document |

**Host permission:** `https://huggingface.co/*` — Used to download Piper voice models from HuggingFace's open model repository.

## FAQ

**Q: Does MurMur work on all websites?** A: MurMur works on most websites with text content. It uses Mozilla's Readability library (the same technology behind Firefox Reader View) to extract articles. For pages that Readability can't parse, it falls back to reading visible text blocks from the page.

**Q: Does MurMur send my data anywhere?** A: No. All text processing happens locally in your browser. Chrome's built-in voices are provided by the browser itself. Piper AI voices run entirely via WebAssembly in your browser. The only network request MurMur makes is to download Piper voice model files from HuggingFace when you first use a Piper voice.

**Q: Why doesn't MurMur work on some pages?** A: Some pages use complex JavaScript rendering that makes text extraction difficult. Chrome's built-in pages (`chrome://`, `chrome-extension://`) and the Chrome Web Store also restrict extension content scripts for security reasons.

**Q: Can I use MurMur with Google Docs?** A: Yes. MurMur has built-in support for Google Docs. It automatically enables the canvas annotation layer and extracts text from the document. Just open a Google Doc and click the MurMur icon.

**Q: How do I change the voice?** A: Use the Language and Voice dropdowns in the MurMur control panel. Select a language first to filter available voices, then choose your preferred voice. Your selection is saved automatically.

**Q: What's the difference between Chrome and Piper voices?** A: Chrome voices are provided by the browser and require an internet connection for some voices. Piper voices are AI-generated neural network voices that run entirely in your browser using WebAssembly — they work offline after the initial model download.

**Q: Can I adjust the speed?** A: Yes. Use the speed slider (0.5x to 3x) or press Arrow Up / Arrow Down. For Piper voices, speed changes are applied at the synthesis level so pitch stays natural at any speed.

**Q: What's the difference between Overlay and Inline mode?** A: Overlay mode opens a clean reader view on top of the page — ideal for distraction-free listening. Inline mode highlights words directly on the original page without changing the layout — great for following along with the original design and images.

**Q: Does MurMur work offline?** A: Chrome's built-in voices may require an internet connection depending on the voice. Piper AI voices work fully offline after the initial voice model download.

## About Regulus Labs

MurMur is developed by **Regulus Labs**, focused on building accessible, privacy-first tools that enhance the way people consume content on the web. We believe that listening should be as effortless as reading — and that your data should stay yours.

## License

Copyright (c) Regulus Labs. All rights reserved.