Skip to content

textweaver documentation

textweaver logo: the letters t and w woven on a loom

textweaver is a document reader and writer that speaks. It reads aloud with a highlight that follows the spoken word, is fully operable from the keyboard in both a terminal and a graphical app, and converts, exports, and edits documents. It is an independent project descended from star, the Python reader that preceded it.

This is the index of every textweaver document, grouped by audience:

If you are new, begin with the quick start.

There are also interactive pages that explain textweaver with diagrams operable from the keyboard. They work offline in any browser.

Start here

For users

Getting started

Reading

  • Reading and moving around: opening files, reading aloud, moving by unit, Speech Cursor, find, go to, and history.
  • Keyboard reference: every key in the terminal and the GUI, generated from the keymap.
  • The textweaver app (graphical version): starting it, what is on screen, the menus, buttons and panels, its keys, announcements, and the reading aids it draws.
  • The app in pictures: eight pictures of the graphical version, each with a text description of what it shows.
  • Bookmarks, notes, and highlights: marking your place and your thoughts; the named highlight palette; links between notes and graph exports; and study cards, the self-test, and recall prompts.
  • Reading aids: RSVP, bionic reading, the reading ruler, text spacing, fonts, and reading level.
  • Themes: the 24 built-in color themes, following your system, and writing your own.
  • Math: hearing math read aloud, and writing it in Markdown.

Writing

  • Writing and editing: edit mode, typing echo, Markdown commands, undo, saving, the outline, spell check, clipboard and Markdown paste, templates, find and replace with regular expressions, the preview pane, and tracked changes in Word files.
  • Citations: inserting citations while writing, tw cite, the reference library, DOI and ISBN lookup, and citation styles.
  • Dictation: tw dictate, turning speech in an audio file into text.

Speech

Files, the library, and settings

  • Converting documents: tw convert to HTML, EPUB, Word, braille, PDF, and more, including DAISY and BRF reading and the formats carta handles; exporting and previewing from inside the reader.
  • The library: library folders, recent files, sync between computers, and importing from star.
  • Optional components: the models, fonts, and voices textweaver downloads only when you agree; Manage optional components, the first-run list, tw components, installing from a file, and a mirror.
  • Updates: the daily check and Help, Check for updates; the question before downloading; how a download is checked and installed; and tw update.
  • Syncing between computers: notes, highlights, bookmarks, places, statistics, and settings through a folder you choose; what never syncs, setting it up, what you hear, and privacy.
  • The Obsidian vault: exporting notes and highlights to a vault, and importing them back.
  • Settings: where settings live, every setting, and export, import, and reset.
  • Settings reference: every setting with its default, label, help, and values, generated from the settings schema.
  • The command line: the rules every tw command follows: --out, --to, --json, --home, questions and --yes, exit codes, and error lines.
  • Scripts: install, update, speech check, doctor, and folder conversion.

For contributors

The developer documents are in dev/, and the decision records in adr/.

Building and working on textweaver

  • CONTRIBUTING.md: what textweaver is for, setting up, the checks, accessibility expectations, commit style, and how to propose a change.
  • Good first issues: small, well-scoped tasks for a first contribution, each with where to look and how to check it.
  • Writing messages: the style guide for everything textweaver says and shows, and the tests that keep it.
  • Building: Rust, Python, what each system needs, Docker, the GUI, the lean reader, the helper scripts, and the repository layout.
  • Testing: the checks every change must pass, the tests, and the benchmarks.
  • The polish checklist and its tests: each row of the consistency, accessibility, visual, and documentation checklist, with the test that holds it or the owner's session that covers it.
  • Architecture: the crates, the dependency rules, the threads, and the path from a file to a highlighted word.
  • The eSpeak NG helper: how eSpeak NG runs in its own helper program, how textweaver chooses between it and the in-process backend, and the measurement behind the choice.
  • The crates: what each of the 39 crates does, with its ADRs.
  • CI: the workflows and what they check.
  • Docker development container: building and testing Linux features on any machine, and Voxin.
  • Fuzzing: the 35 cargo-fuzz targets, run by the nightly workflow when started by hand: the document loaders (RTF, ODT, Word revisions, LaTeX, Obsidian, JSON, SVG, and email among them), PDF annotations, the math and citation parsers, themes, the lexicon, vault import, JSON-RPC, the settings and state files, the sync folder's records and group files, and the engine-host protocol.
  • Releasing: making a release, the Linux AppImage, and what the packages hold.
  • Third-party data: the bundled pronunciation dictionaries, fonts, and word lists, and their licenses.
  • JSON-RPC: driving textweaver from an editor or another program with tw serve --stdio.
  • Roadmap: what works today, what is being built next, and what is planned.
  • Research for the next waves: the research reports and the wave plans for alpha.8 through beta 1 and later: performance, speech engines, use cases, design, and law and standards.
  • star features not yet planned: star features with their status in textweaver.
  • Documentation coverage: each feature, the guide that covers it, and whether the guide passes.
  • CHANGELOG.md: what changed in each release.

Decisions

Each ADR records one decision: the context, the choice, and its consequences. A dated status update under the date says what changed later. The ADR index lists them with their statuses.

Interactive pages

The pages in docs/site/ explain textweaver with diagrams and demonstrations. Each diagram has a full text version next to it, every control works from the keyboard, and changes are announced to screen readers. Open docs/site/index.html in any browser; nothing is downloaded.

  • Overview: what textweaver is, and a map of the other pages.
  • Architecture: choose a crate to hear its job, its ADRs, and what it depends on.
  • Speech pipeline: step from a key press to a highlighted word, with a worked offset map.
  • Keyboard: search and filter every key by category, layer, frontend, and platform.
  • Features: everything textweaver does, with its status.
  • Reading aids: try RSVP, bionic reading, and the reading ruler.
  • About the pages: how they are made and regenerated.

See also

  • README: what textweaver is, and how to build it.
  • Quick start: the shortest route to a first reading.