Runnable, task-focused examples for star — the accessible document reader and Markdown authoring tool with built-in text-to-speech. Each folder is one concrete task with its own README.
How to run any runnable example:
cd docs/examples/<category>/<name>
python run.py
Runnable examples need only star-reader installed (pip install star-reader).
The GUI entries are walkthroughs you follow inside the app — they have no
run.py.
star's CLI extracts and inspects without opening a window.
| I want to… | Example | Runs? |
|---|---|---|
| Get a document's plain text on stdout (pipe-friendly) | cli/extract-text |
✅ python run.py |
| Export a document to spoken audio (WAV/MP3) | cli/export-audio |
✅ python run.py |
| See every TTS voice available on my system | cli/list-voices |
✅ python run.py |
| See which optional features are installed | cli/check-dependencies |
✅ python run.py |
| List the pluggable voices, formats, and exporters | cli/list-plugins |
✅ python run.py |
More CLI: star --install-optional, star --check-update, and headless batch
conversion with star --watch DIR --output DIR — see the
Usage guide.
star's core is a library, not just an app.
| I want to… | Example | Runs? |
|---|---|---|
| Open any document and read its text/title/format in Python | library/load-a-document |
✅ python run.py |
| Translate a document to another language | library/translate-document |
✅ python run.py |
| Summarize a document to key sentences | library/summarize-document |
✅ python run.py |
| Share reading profiles between machines (JSON export/import) | library/profiles |
✅ python run.py |
More: the loaders, word map, and TTS pipeline are described in Architecture.
The primary experience — walkthroughs to follow in the app (star).
| I want to… | Walkthrough |
|---|---|
| Open a document and hear it read, word-by-word | gui/read-aloud |
| Use dyslexia / decoding aids (define, syllables, fonts, difficult words) | gui/reading-aids |
Depth: Features · Usage guide.
| I want to… | Walkthrough |
|---|---|
| Write a Markdown document, dictate, and export to PDF / audio / Braille | gui/write-and-export |
Depth: Usage guide ▸ authoring.
| I want to… | Example |
|---|---|
| Write my own TTS voice, format loader, or exporter | plugin-template |
| See what plugins are registered | cli/list-plugins |
Depth: Developing plugins.
Not every feature has a dedicated example folder yet — these are covered in the docs:
| Area | Where |
|---|---|
| Knowledge graph & Obsidian vault import | knowledge-graph · obsidian |
| Karaoke video export | video-export |
| Configuration & settings reference | configuration |
| Keyboard shortcuts (full audit) | KEYBOARD_AUDIT |
| Install, extras, native engines, per-platform notes | installation |
Every runnable example here is executed by the test suite
(tests/test_examples_smoke.py) so it can't rot silently.