Metadata-Version: 2.4
Name: star-reader
Version: 0.1.28
Summary: star — Speaking Terminal Access Reader: accessible study tools for reading and writing, with built-in text-to-speech
Author: Jon Pielaet
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/leavesofgrass/star
Project-URL: Repository, https://github.com/leavesofgrass/star
Project-URL: Changelog, https://github.com/leavesofgrass/star/blob/main/star/CHANGELOG.md
Project-URL: Issues, https://github.com/leavesofgrass/star/issues
Keywords: accessibility,text-to-speech,tts,screen-reader,document-reader,braille
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console :: Curses
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Adaptive Technologies
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyQt6
Requires-Dist: pyttsx3
Requires-Dist: pdfminer.six
Requires-Dist: python-docx
Requires-Dist: python-pptx
Requires-Dist: pyobjc; sys_platform == "darwin"
Requires-Dist: windows-curses; sys_platform == "win32"
Provides-Extra: ocr
Requires-Dist: pytesseract; extra == "ocr"
Requires-Dist: pymupdf; extra == "ocr"
Requires-Dist: Pillow; extra == "ocr"
Provides-Extra: formats
Requires-Dist: odfpy; extra == "formats"
Requires-Dist: openpyxl; extra == "formats"
Provides-Extra: markup
Requires-Dist: pypandoc; extra == "markup"
Provides-Extra: braille
Requires-Dist: louis; extra == "braille"
Provides-Extra: audio
Requires-Dist: pydub; extra == "audio"
Provides-Extra: transcribe
Requires-Dist: faster-whisper; extra == "transcribe"
Requires-Dist: sounddevice; extra == "transcribe"
Requires-Dist: numpy; extra == "transcribe"
Provides-Extra: summarize
Requires-Dist: sumy; extra == "summarize"
Provides-Extra: syllables
Requires-Dist: pyphen; extra == "syllables"
Provides-Extra: flashcards
Requires-Dist: genanki; extra == "flashcards"
Provides-Extra: spellcheck
Requires-Dist: pyspellchecker; extra == "spellcheck"
Provides-Extra: translate
Requires-Dist: deep-translator; extra == "translate"
Provides-Extra: feeds
Requires-Dist: feedparser; extra == "feeds"
Provides-Extra: vocab
Requires-Dist: wordfreq; extra == "vocab"
Provides-Extra: dictionary
Requires-Dist: nltk; extra == "dictionary"
Provides-Extra: watch
Requires-Dist: watchdog; extra == "watch"
Provides-Extra: clipboard
Requires-Dist: pyperclip; extra == "clipboard"
Provides-Extra: graph
Requires-Dist: graphviz; extra == "graph"
Requires-Dist: plantuml; extra == "graph"
Requires-Dist: pyyaml; extra == "graph"
Provides-Extra: ner
Requires-Dist: spacy; extra == "ner"
Requires-Dist: nltk; extra == "ner"
Provides-Extra: archive
Requires-Dist: py7zr; extra == "archive"
Requires-Dist: rarfile; extra == "archive"
Provides-Extra: video
Requires-Dist: Pillow; extra == "video"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: pytest-qt; extra == "test"
Requires-Dist: pytest-xdist; extra == "test"
Requires-Dist: hypothesis; extra == "test"
Provides-Extra: all
Requires-Dist: pytesseract; extra == "all"
Requires-Dist: pymupdf; extra == "all"
Requires-Dist: Pillow; extra == "all"
Requires-Dist: odfpy; extra == "all"
Requires-Dist: openpyxl; extra == "all"
Requires-Dist: pypandoc; extra == "all"
Requires-Dist: louis; extra == "all"
Requires-Dist: pydub; extra == "all"
Requires-Dist: watchdog; extra == "all"
Requires-Dist: pyperclip; extra == "all"
Requires-Dist: sumy; extra == "all"
Requires-Dist: pyphen; extra == "all"
Requires-Dist: genanki; extra == "all"
Requires-Dist: pyspellchecker; extra == "all"
Requires-Dist: deep-translator; extra == "all"
Requires-Dist: feedparser; extra == "all"
Requires-Dist: wordfreq; extra == "all"
Requires-Dist: nltk; extra == "all"
Requires-Dist: graphviz; extra == "all"
Requires-Dist: plantuml; extra == "all"
Requires-Dist: pyyaml; extra == "all"
Requires-Dist: py7zr; extra == "all"
Requires-Dist: rarfile; extra == "all"
Requires-Dist: faster-whisper; extra == "all"
Requires-Dist: sounddevice; extra == "all"
Requires-Dist: numpy; extra == "all"
Dynamic: license-file

# ⭐ star — Speaking Terminal Access Reader

[![CI](https://github.com/leavesofgrass/star/actions/workflows/ci.yml/badge.svg)](https://github.com/leavesofgrass/star/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/star-reader.svg)](https://pypi.org/project/star-reader/)
[![Python](https://img.shields.io/pypi/pyversions/star-reader.svg)](https://pypi.org/project/star-reader/)
[![License: GPL-3.0-or-later](https://img.shields.io/badge/License-GPLv3-blue.svg)](LICENSE)

> **star** is an accessible, **GUI-first** document reader and Markdown
> authoring tool with built-in text-to-speech. It opens PDFs,
> Word/EPUB/PowerPoint, web pages, spreadsheets, and more, reads them aloud, and
> **highlights each word as it is spoken** — with no cloud account and no
> internet required. You can also **write** in it: create documents from
> scratch, format Markdown, and dictate straight into the text.

`star` is built for students with print disabilities — people who work with
dense, heavily formatted documents and need a reading tool that gets out of the
way. The **Qt GUI is the primary interface** (it launches by default and is where
development is focused), with a keyboard shortcut for every command; a
full-featured, keyboard-driven curses **terminal UI** remains available with
`--tui` for headless or text-only environments.

It draws design inspiration from [Emacspeak](https://emacspeak.sourceforge.net/),
[Kurzweil 1000](https://www.kurzweiledu.com/),
[Natural Reader](https://www.naturalreaders.com/), and
[Central Access Reader](https://www.readingmadeeasy.com/).

---

## 🚀 Quick start

**Install** on any platform with **Python 3.11+**:

```bash
pipx install star-reader        # isolated app install (recommended)
# or:  pip install star-reader  # into the current environment
```

star **grows on demand** — it fetches optional features the first time you use
them, so you don't need to pick extras up front. Want everything available
offline right away? `pipx install "star-reader[all]"`.

**Run it:**

```bash
star                 # launch the Qt GUI (the primary interface)
star document.pdf    # open a document
star --tui           # force the terminal UI (headless / text-only)
```

**Your first 60 seconds** (in the GUI):

- Press **`Ctrl+O`** to open a document — or just read the welcome page it opens on.
- Press **`Space`** to hear it read aloud, with **each word highlighted** as it's spoken.
- Put the caret on a word and press **`Ctrl+D`** for an offline definition.
- Press **`Ctrl+N`** to start writing your own document; **`Ctrl+E`** toggles edit mode.

**Where next:**

- Worked examples: **[`docs/examples/`](docs/examples/)** — extract text on the CLI, load
  documents from Python, and read-aloud / authoring walkthroughs.
- Full docs: **[Usage guide](docs/usage_guide.md)** ·
  **[Features](docs/features.md)** · **[Installation](docs/installation.md)**.

### Optional features

**star runs out of the box** on nothing but the Python standard library, and
**grows on demand — no `pip install` step anywhere.** Whenever you reach for a
feature that needs an add-on (OCR, offline dictionary, summarize, translate,
knowledge-graph extras, dictation, …), star offers to **download it in the
background** and the feature then works **in the same session** — no restart. On
first launch the GUI also shows a short **optional-features chooser**: pick the
**Thin** or **All** preset, or tick exactly the capabilities you want. Re-open it
any time from **Tools → Install Optional Features…**. **"All" now means literally
everything** (including the large speech-to-text and named-entity packs); the
download size is shown upfront.

Prefer the command line? `star --deps` shows what's installed,
`star --install-optional` fetches features, `star --plugins list` lists the
pluggable backends/formats/exporters, and `star --check-update` checks PyPI.

Prefer the command line or a scripted setup? `star --install-optional` installs
the `all` preset; `star --install-optional thin` or
`star --install-optional ocr,dictionary` install a preset or a comma-separated
list of features; run it with no value to list every feature with its size.
`star --plugins list` and `star --check-update` round out the CLI. Advanced users
can still install extras the classic way — `pip install "star-reader[all]"`, or
groups like `star-reader[translate,vocab]` — but the normal path is one click,
in-app.

Full instructions (wheel, single-file `star.pyz`, native engines, per-platform
notes) are in the **[Installation guide](docs/installation.md)**.

---

## ✨ Highlights

- **Reads aloud with live word highlighting** in both the Qt GUI and the terminal
  TUI — including in-process eSpeak-NG with true audio-position sync.
- **Many TTS engines + Voice Manager:** pyttsx3
  (SAPI5 / NSSpeechSynthesizer), macOS `say`, eSpeak-NG, Festival, **Piper**
  (neural, offline, free), Coqui, DECtalk, and opt-in **ElevenLabs cloud neural
  voices** (text leaves your machine only after you set a key *and* choose the
  cloud voice; any failure falls back to a local engine) — browse, filter,
  preview, and favorite voices in the **Voice Manager (F4)**, with one-click
  download of offline Piper neural voices.
- **Opens almost anything:** PDF (incl. OCR), DOCX, PPTX, EPUB, HTML, Markdown,
  spreadsheets, DAISY/DTBook, and dozens more formats.
- **Write, don't just read:** create a document from scratch (**File ▸ New**,
  **Ctrl+N**), format Markdown from an edit-mode toolbar and a **Format** menu
  (Bold **Ctrl+B**, Italic **Ctrl+I**, Underline **Ctrl+U**, headings, lists,
  quotes, links **Ctrl+K**, inline code, rules) with full **Undo/Redo**, and
  **dictate straight into the text** with **Voice Typing** (**Tools ▸ Voice
  Typing**, **Ctrl+Alt+K**).
- **Find, bookmark, and search:** incremental **find in document (Ctrl+F)**, named
  **bookmarks (Ctrl+M)** with back/forward history (**Alt+←/→**), and **full-text
  search inside every document** in your library.
- **Study & spaced repetition:** turn highlights and notes into a review deck
  (FSRS scheduler), review due cards in-app (**Study ▸ Review Due Cards…**,
  Ctrl+Shift+F5), auto-generate cloze cards, and optionally two-way sync with Anki.
- **Study tools:** notes & annotations, a citation manager, summarization, Anki
  flashcard export, document translation (15 languages, no API key), RSS/Atom
  feed reading, and a difficult-word overlay.
- **Richer documents:** inline LaTeX math rendered as readable Unicode, accessible
  tables that keep their header structure, clickable footnotes (with a ↩ backlink),
  and image captions / alt text.
- **Knowledge graph:** link annotations across documents with typed relations
  (`CONFLICTS_WITH`, `SUPPORTS`, `CITES`, …), extract concepts, view the graph
  interactively, and export to SVG/PlantUML/DOT/JSON.
- **Export:** Markdown, HTML, EPUB, PDF (with highlights), BRF braille, TTS
  audio (WAV/MP3/OGG/MP4), **chaptered M4B audiobooks** (chapters from headings;
  needs ffmpeg), karaoke video (MP4), Anki decks, and synchronized SRT/VTT
  subtitles.
- **Extensible:** TTS engines, document formats, and export targets are
  discovered through `importlib.metadata` entry-points — installing a
  third-party plugin package adds backends, loaders, or exporters with no
  changes to star itself.
- **Accessibility-first:** NVDA/JAWS/Orca/VoiceOver compatible, screen-reader
  announcements for playback / load / theme / find results, a **high-contrast
  (AAA) theme** with automatic light / dark / high-contrast following your OS, a
  **Reading Font chooser** (**OpenDyslexic**, **Atkinson Hyperlegible**, **Lexend**
  — auto-fetched and applied across the whole UI), **syllable splitting**
  (display-only decoding aid), a caret-tracking **reading ruler**, four
  colorblind-friendly themes + custom CSS themes, bionic reading, adjustable
  spacing (WCAG 1.4.12), and high-DPI support.
- **Guided tour & translations:** a skippable first-run walkthrough (replay any
  time from **Help ▸ Guided Tour**, Shift+F1), Help ▸ Check for Updates, and a
  translated interface — terminal UI included — in Spanish, French, German, and
  Portuguese, with a first-run language picker in the Qt GUI (the TUI honors the
  `ui_language` setting). **Right-to-left interface languages mirror the whole
  app** — Arabic is included as a first catalog.
- **Fast on huge documents:** opt-in pagination renders only a window of a very
  large document at a time, dropping first paint on a ~500-page file from seconds
  to well under one (off by default).
- **Sync without losing work:** reading progress and annotations from two machines
  now *merge* instead of last-write-wins — position resolves by a policy you pick
  (newest / furthest / manual) and notes union by id.
- **Graceful degradation:** every third-party dependency is optional and guarded,
  so the core runs on the Python standard library alone.
- **One-click optional features:** when a capability needs an add-on, star
  downloads it in the background — **no `pip install` step anywhere** — and it
  works right away (only the large speech-to-text pack needs a restart). Driven by
  a first-run chooser or `star --install-optional`.
- **One tabbed Preferences dialog:** every reader setting — Reading, Reading
  Aids, Voice, Display, Fonts, General — in **Edit ▸ Preferences…**
  (**Ctrl+,**), with Apply and **Restore Defaults**.
- **Clear, consistent UI:** an all-icon toolbar with descriptive tooltips (vector
  glyphs drawn programmatically and tinted to your theme — no image files); a
  **readable welcome page** that reads aloud like any document; and **F1** opens
  the bundled README as a document on every install.

See the **[full feature reference](docs/features.md)** for everything.

---

## 📚 Documentation

| Guide | What's in it |
|---|---|
| **[Examples](docs/examples/)** | Runnable, task-focused examples (CLI text extraction, the Python library, read-aloud & authoring walkthroughs) with a catalog mapping every area |
| **[Installation](docs/installation.md)** | PyPI / wheel / zipapp install, optional packages, native engines, platform notes |
| **[Usage Guide](docs/usage_guide.md)** | Running star, the **quick command reference**, full keyboard map, M-x commands, CLI options |
| **[Features](docs/features.md)** | The complete feature reference |
| **[Knowledge Graph](docs/knowledge-graph.md)** | Typed relations between annotations, concept extraction, graph view, and export |
| **[Configuration](docs/configuration.md)** | Every `settings.json` key |
| **[Architecture & Contributing](docs/architecture.md)** | Package layout, distribution artifacts, contributing, tests |
| [Changelog](star/CHANGELOG.md) | Full record of changes |
| [Build guide](star/BUILD.md) | Building the cross-platform wheel and the self-contained Windows `star.exe` / macOS `.app` |

➡️ Browse all docs in the **[`docs/`](docs/)** directory.

---

## 📦 Distribution

The pure-Python **wheel** (`pip install star-reader`) is star's primary, stable
distribution; it works on macOS, Linux, and Windows alike. For anyone who can't
install Python, every GitHub Release also attaches double-click binaries for all
three desktops — a self-contained **Windows `star-<version>-windows-x64.exe`**
(Python, the GUI, and all loaders baked in; DECtalk excluded from the public
exe), a **macOS `star-<version>-macos-arm64.dmg`** (Apple-Silicon; uses the
built-in Apple voices), and a **Linux AppImage**. A single-file
[`star.pyz`](docs/installation.md#single-file-build-starpyz) zipapp is
build-it-yourself. See [Installation](docs/installation.md) and
[`BUILD.md`](star/BUILD.md).

---

## 🤝 Contributing

Contributions are welcome — please open an issue before a PR for anything beyond
small fixes. Keep every third-party dependency optional and guarded, target
Python 3.11, and document new keybindings and `M-x` commands. See
**[Architecture & Contributing](docs/architecture.md#contributing)** for the full
guidelines and how to run the test suite.

---

## 📜 License

`star` — Speaking Terminal Access Reader
Copyright 2026 Jon Pielaet

Free software under the **GNU General Public License version 3 or later**. This
program is distributed in the hope that it will be useful, but **without any
warranty**. See the [LICENSE](LICENSE) file, or run `M-x license` in the app, for
the full text.
