<p align="center"><img src="public/icon.svg" width="112" alt="Earful icon: a page with one highlighted line, giving off sound waves"></p>

<h1 align="center">Earful</h1>

<p align="center">Listen to any PDF, book or web page in a natural voice. Free, offline, open source.</p>

<p align="center"><b><a href="https://earful-app.github.io/earful/">Try it in your browser</a></b></p>

<p align="center"><img src="media/hero.gif" width="800" alt="Earful reading Pride and Prejudice aloud, with a yellow marker on each word as it is spoken"></p>

<p align="center"><a href="https://earful-app.github.io/earful/demo.mp4">Watch the demo with sound</a> (24 seconds)</p>

Earful reads documents aloud with [Kokoro](https://huggingface.co/hexgrad/Kokoro-82M), an open speech model by hexgrad, running entirely on your own computer. Nothing you open is uploaded.

## What it does

- Opens PDFs, EPUB books, Word documents (.docx), saved web pages and plain text. Scanned PDFs go through text recognition first.
- Highlights each word as it is spoken. Click any sentence to start reading from there.
- Skips what you wouldn't read aloud yourself: page numbers, running headers and footers, footnotes, citation markers like [12], links and the reference list.
- Lets you jump between chapters and sections, using the headings in the file.
- Remembers where you stopped in each document.
- Plays at 0.75× to 3×. The voice is made at normal speed and sped up without raising its pitch, so a new speed takes effect straight away.
- Has 13 voices, American and British English. Kokoro's other languages need a different pronunciation engine and aren't supported yet.
- Works offline after the first visit. The page, the voice and the speech engine are all saved in your browser.

## Speed

Pressing play starts the voice right away, because the first sentence is prepared as soon as a document opens. After that the voice stays ahead of playback. On a MacBook with an Apple M5 in Chrome, one second of speech takes 0.15 seconds to generate.

That speed needs WebGPU, which Chrome, Edge and Safari 26 support. Other browsers fall back to WebAssembly, which works but is slower. The first visit downloads the voice once (326 MB), and after that it is cached and works offline.

## In your terminal and your coding agent

The `earful` command runs the same voice natively, which is faster than the browser.

```
earful say "The build finished."
earful read paper.pdf
earful read https://example.com/article --out article.mp3
```

Install it from npm:

```
npm install -g earful-cli
```

### MCP server

Add Earful to Claude Code, or any other MCP client, and your agent can speak and read documents aloud on your computer:

```
claude mcp add earful -- earful mcp
```

It has four tools: `speak`, `read_aloud`, `stop_reading` and `save_audio`.

### Hear when Claude Code is done

Add a Stop hook to `~/.claude/settings.json`:

```json
{
  "hooks": {
    "Stop": [{ "hooks": [{ "type": "command", "command": "earful hook" }] }]
  }
}
```

When Claude Code finishes, Earful says the first sentence or two of its reply, without the code and formatting.

## What's next

- A desktop app with a shortcut that reads selected text in any app
- A browser extension that reads the page you're on

## Run it locally

```
npm install
npm run dev
```

`npm test` checks the sentence splitter. `npm run pdf` prints what Earful would read for each PDF you put in `fixtures/`. The command line tool lives in `cli/`.

## Built with

- [Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M) by hexgrad (Apache-2.0), run through [kokoro-js](https://github.com/hexgrad/kokoro/tree/main/kokoro.js) and [Transformers.js](https://github.com/huggingface/transformers.js) on ONNX Runtime Web
- [pdf.js](https://github.com/mozilla/pdf.js), [Readability](https://github.com/mozilla/readability) and [tesseract.js](https://github.com/naptha/tesseract.js) for getting the text out of files
- [eSpeak NG](https://github.com/espeak-ng/espeak-ng) for pronunciation

The demo video reads the abstract of [Chain-of-Thought Prompting Elicits Reasoning in Large Language Models](https://arxiv.org/abs/2201.11903) by Wei et al., licensed CC BY 4.0. The animation reads Pride and Prejudice from [Project Gutenberg](https://www.gutenberg.org/ebooks/1342).

## License

GPL-3.0-or-later. Earful gets its pronunciation from eSpeak NG, which is GPL-3.0.