rsvpreader

A Spritz-style rapid serial visual presentation reader for plain-text books. It shows one chunk of one to three words at a time with a fixed pivot letter pinned to the center of the screen, or one full sentence at a time, and remembers where you stopped in every book.

Install and run

Requires Python 3.10 or newer with Tk. On macOS, Homebrew's Python ships without Tk; uv installs a Python that has it.

From PyPI:

uv tool install rsvpreader   # or: pipx install rsvpreader, pip install rsvpreader
rsvpreader                   # fullscreen, reads ./book
rsvpreader --windowed        # normal window
rsvpreader ~/Books           # a different book folder

From a checkout:

uv sync
uv run rsvpreader --windowed

python rsvpreader.py works as a launcher from a checkout without installing.

Put .txt files, in any folder structure, under book/ next to where you run the command, or point RSVPREADER_BOOK_ROOT or the positional argument at another folder.

Controls

Autoplay speed is true words per minute: a three-word chunk is shown three times as long as a single word, and a sentence for as long as its word count implies.

Settings

Chunk size (1, 2 or 3 words), max autoplay WPM, font family and size, brightness, text color (native color picker) and sentence mode. Changes apply live, rebuild the current book without losing your place, and persist to settings.json in the user config directory:

Override with --config-dir or RSVPREADER_CONFIG_DIR. On first run, settings and reading positions are imported from the directory the 1.0.x releases used (RSVP_READER_CONFIG_DIR if set, otherwise rsvp-reader in the same locations), then from a legacy rsvp_settings.json in the working directory. Reading positions live in progress.json in the same directory, keyed by the book's absolute path.

How text is chunked

1. Regular punctuation (comma, semicolon, colon, apostrophe, dashes) attaches to its word and never forces a break.
2. A sentence terminator (. ! ?) closes the chunk on the word carrying it.
3. An opening double quote (straight or curly) closes the previous chunk, so the quoted word starts a new one.
4. A closing double quote closes the chunk on the word carrying it.

Text pasted without spaces is repaired first: forth,The becomes forth, The and it."Believe becomes it. "Believe, while 0.99365, 1,000, e.g. and 7.25p.m. stay intact. Straight double quotes alternate open and close by parity. A token with no letters or digits, such as a spaced en dash, glues to the previous word so it never occupies a chunk of its own.

The pivot word is the middle word of a three-word chunk, the word with more letters in a two-word chunk (tie goes to the first), or the only word. The pivot letter is the middle letter counting letters only, rounding left for an even count (Bull highlights u); a word with no letters falls back to its digits.

To inspect the units for any file without opening the GUI:

uv run rsvpreader --dump-chunks "book/selfhelp/some book.txt" --chunk-size 3
uv run rsvpreader --dump-chunks "book/selfhelp/some book.txt" --sentences

Development

uv sync
uv run pytest            # unit tests plus Tk smoke tests (skipped without a display)
uv run ruff check src tests
uv run ruff format src tests
uv build                 # sdist and wheel under dist/

CI runs lint and tests on Linux, macOS and Windows for every push and pull request, and builds the wheel on Linux.

Releasing

The package version lives only in __version__ in src/rsvpreader/__init__.py. To release: bump it, merge, then publish a GitHub release whose tag is v<version> (for example v1.0.1). The publish workflow builds the distributions, checks that the tag matches the version, and uploads to PyPI through trusted publishing; no API token is stored anywhere.

Layout under src/rsvpreader/:

Everything outside the Tk modules is pure and unit tested; the Tk smoke tests drive a real window and assert the rendered pivot geometry from Tk's own bounding boxes.