readeasy

Read any text file out loud, right from your terminal.

readeasy is a small command-line tool that opens a text file in a simple terminal window and reads it aloud using text-to-speech. You stay in the terminal — no browser, no GUI app. Press one key to start or stop the voice.

---

Features

• Open a text file (or piped input) in a clean terminal view.
• Read the text aloud with a single key press.
• Start and stop the speech whenever you like.
• Tiny, fast, and written in C.

---

Requirements

You need three things to build and run readeasy:

Tool	What it is	Needed for
A C compiler (cc / gcc / clang)	Turns the source code into a program	Building
ncursesw (wide-character ncurses)	A library for drawing terminal windows	Building & running
say	A text-to-speech command	Reading aloud
afplay	An audio-file player	Reading aloud

say and afplay both ship with macOS. readeasy synthesizes each sentence with say and plays it with afplay, preparing the next sentence while the current one is still playing so the audio doesn't stutter between sentences.

readeasy needs the wide-character build of ncurses (ncursesw), not the plain/narrow one. Without it, accented and non-ASCII characters — common in text copied from PDFs — show up as garbled symbols instead of the correct character.

Platform support

• macOS — the say command ships with macOS, but the system's built-in ncurses is the narrow build. Install the wide-character version with Homebrew before building:

  brew install ncurses

  make detects it automatically and links against it.
• Linux — the terminal view works, but speech does not work out of the box. macOS has say; Linux does not. To get speech on Linux you would need to install a speech tool such as espeak and change the program to call it instead of say (see docs/CONTRIBUTING.md). You also need the wide-character ncurses development package, e.g. sudo apt install libncursesw5-dev.
• Windows — not supported.

---

Installation

1. Clone the repository

git clone https://github.com/ItsJasonPierrot/readeasy

2. Go into the folder

cd readeasy

3. Build it

make

This creates a program called readeasy in the current folder.

Note: The old gcc -o readeasy readeasy.c command no longer works. The code is now split across several files, so always build with make.

---

Usage

Run the program with the name of the file you want to read:

./readeasy <filename>

For example:

./readeasy README.md

You can also pipe text into it instead of giving a filename:

cat notes.txt | ./readeasy

Controls

Once the file is open, use these keys:

Key	What it does
↑ / ↓	Move the highlighted cursor up or down one sentence.
Space	Start reading aloud from the cursor sentence. Press again to pause; press once more to resume from that same sentence.
Ctrl-L	Redraw the screen (useful if it looks stale after switching terminal tabs).
q	Quit the program.

readeasy re-flows the text to fill your terminal width and reads it one sentence at a time. The highlighted sentence is the cursor — it marks where reading starts and, while speech plays, it advances sentence by sentence so you can see what is being read. If you pause and then press Space again without moving the cursor, reading picks up from the same sentence.

A full reference — including every error message and limit — is in docs/USAGE.md.

---

Limits

• The program reads up to about 64 KB of text (roughly 10,000 words). Text beyond that is not loaded.
• It reads plain text. It does not interpret Markdown, HTML, or PDF formatting — symbols like # or * are read aloud as written.
• Stray control characters (such as the page-break form feeds left behind by PDF-to-text extraction) are converted to spaces so they don't show up as garbled symbols on screen.
• Text is re-flowed to your window width, so files that were hard-wrapped at a narrow column (common in text exported from PDFs) still fill the screen. Short lines such as headings are kept on their own; sentence boundaries are detected from ., !, and ?.

---

Contributing

Contributions are welcome. Please read docs/CONTRIBUTING.md to learn how to set up, build, and submit changes, and docs/CODE_OF_CONDUCT.md for our community guidelines.

---

License

readeasy is released under the MIT License. See the LICENSE file for details.