{"id":22509634,"url":"https://github.com/n-ivkovic/tspreed","last_synced_at":"2025-10-12T22:33:39.309Z","repository":{"id":44393051,"uuid":"242052498","full_name":"n-ivkovic/tspreed","owner":"n-ivkovic","description":"Terminal RSVP speed reader with Spritz-like functionality written in POSIX-compliant shell","archived":false,"fork":false,"pushed_at":"2024-01-31T13:49:53.000Z","size":262,"stargazers_count":86,"open_issues_count":0,"forks_count":6,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-07-02T02:01:49.470Z","etag":null,"topics":["posix","rsvp","shell","speed-reading","spritz","terminal","tui","unix"],"latest_commit_sha":null,"homepage":"https://gitlab.com/n-ivkovic/tspreed","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/n-ivkovic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2020-02-21T04:17:09.000Z","updated_at":"2025-06-08T12:59:31.000Z","dependencies_parsed_at":"2024-01-05T08:48:27.416Z","dependency_job_id":null,"html_url":"https://github.com/n-ivkovic/tspreed","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/n-ivkovic/tspreed","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n-ivkovic%2Ftspreed","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n-ivkovic%2Ftspreed/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n-ivkovic%2Ftspreed/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n-ivkovic%2Ftspreed/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/n-ivkovic","download_url":"https://codeload.github.com/n-ivkovic/tspreed/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n-ivkovic%2Ftspreed/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279013271,"owners_count":26085250,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-12T02:00:06.719Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["posix","rsvp","shell","speed-reading","spritz","terminal","tui","unix"],"created_at":"2024-12-07T01:29:56.350Z","updated_at":"2025-10-12T22:33:39.292Z","avatar_url":"https://github.com/n-ivkovic.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tspreed\n\ntspreed is a terminal RSVP speed reader with Spritz-like functionality written in POSIX-compliant shell. The script reads plain text piped into it and presents it one word at time.\n\n![tspreed demo gif](.img/tspreed.gif)\n\n## Installation\n\n### Packages\n\n| Distro | Package | Maintainer |\n| ---    | ---     | ---        |\n| Arch Linux | [tspreed (AUR)](https://aur.archlinux.org/packages/tspreed/) | Nicholas Ivkovic |\n\n### Manual\n\n#### Install\n\nReplace `github.com` with `gitlab.com` if using GitLab.\n```\n$ git clone https://github.com/n-ivkovic/tspreed\n$ cd tspreed\n# make install\n```\n\n#### Update\n\n```\n$ git pull origin\n# make update\n```\n\n#### Additional options\n\n```\n$ make help\n```\n\n## Usage\n\nTo begin a presentation, pipe plain text into tspreed.\n\nThe presentation starts with the first word displayed for a minimum of 1 second, then all subsequent words are presented at the given speed (WPM).\n\nIf tspreed is terminated before the presentation has finished, the progress of the presentation is passed to `stdout`.\n\n### Keyboard controls\n\nKeyboard controls can be enabled via the -k/keycontrols option. However, not all systems and shells are able to utilise keyboard controls, see the Portability section.\n\n| Key | Action |\n| --- | ---    |\n| `I` | Show/hide the presentation progress information. |\n| `P` | Pause/resume the presentation. After resuming, the word that was paused on is displayed for a minimum of 0.5 seconds. |\n| `Q` | Terminate the presentation. |\n\n### Examples\n\n```\n$ tspreed \u003c textfile\n```\n```\n$ tspreed --wpm 300 --hide-cursor \u003c textfile\n```\n```\t\n$ pdftotext document.pdf - | tspreed -w 300 -n 120 -s '\\r\\f' -lqihkfb -p line -c 1 -K /dev/tty\n```\n\n## Configuration\n\nThe values provided in the command options take precedence over the values provided in the local configuration file **`$XDG_CONFIG_HOME`/tspreed/tspreed.rc** (**~/.config/tspreed/tspreed.rc** if not defined), which takes precedence over the values provided in the global configuration file **/etc/tspreed/tspreed.rc**.\n\nThe default configuration is provided in [**./default.rc**](./default.rc), which is installed as the global configuration file.\n\n| Option                      | Configuration file   | Default config | Description |\n| ---                         | ---                  | ---            | ---         |\n| -w, --wpm `wpm`             | wpm=`wpm`            | 300            | Present words at the given speed in words per minute (WPM). Required to be set. Minimum value of 1, maximum value of 60000 |\n| -n, --num-start `num`       | numstart=`num`       |                | Start presenting from the given *n*th word. Minimum value of 1. |\n| -s, --separators `chars`    | separators=`chars`   | \\r\\f           | Use the given characters to separate words in addition to the characters set in `$IFS`. Backslash escapes are interpreted. |\n| -l, --length-vary           | lengthvary=`bool`    |                | Vary the speed words are presented at based on their length. |\n| -q, --quiet-exit            | quietexit=`bool`     |                | Do not output the presentation progress if tspreed is terminated before the presentation has finished. |\n| -h, --hide-cursor           | hidecursor=`bool`    | true           | Hide the cursor during the presentation. |\n| -i, --progress-info         | proginfo=`bool`      |                | Display progress information during the presentation. |\n| -k, --key-controls          | keycontrols=`bool`   |                | Enable keyboard controls. |\n| -f, --focus                 | focus=`bool`         |                | Highlight the focus letter (also known as the pivot or optimal recognition point) of the word being presented. |\n| -p, --focus-pointer `style` | focuspointer=`style` | line           | Display pointers in a given style pointing towards the focus letter. Only relevant if focus letter highlighting is enabled. Styles: `none`, `line`, `point`. |\n| -b, --focus-bold            | focusbold=`bool`     | true           | Display the focus letter in bold. Only relevant if focus letter highlighting is enabled. |\n| -c, --focus-color `color`   | focuscolor=`color`   | 1              | Display the focus letter in the given color. Only relevant if focus letter highlighting is enabled. Color values are [ANSI X3.64 8-bit color values](https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit), ranging from 0 to 255. |\n| -K, --dev-key-input `path`  | devkeyinput=`path`   |                | Device/path to read keyboard input from. Only relevant if keyboard controls are enabled. Defaults to **/dev/tty**. |\n| -v, -V, --version           |                      |                | Print tspreed version and exit. |\n\n## Portability\n\ntspreed 'officially' supports GNU-based, BSD-based, and BusyBox-based systems only due to POSIX-compliance issues described below. This does not mean the script is guaranteed to not work on other Unix-like systems or issues specific to those systems will not be addressed, merely it is unknown how well supported the script is on other Unix-like systems.\n\n### POSIX-compliance\n\ntspreed attempts to comply with [POSIX.1-2001](https://pubs.opengroup.org/onlinepubs/000095399/) through to [POSIX.1-2008](https://pubs.opengroup.org/onlinepubs/9699919799/) in order to maintain portability across Unix-like systems. However, the script must utilize non-compliant features and commands and will exit with an error if none are supported.\n\nIf keyboard controls are enabled (-k/keycontrols option), **both** of the below non-compliant features must be supported:\n\n* `date(1)` - Can return nanoseconds via the '%N' format.\n* `read(1)` - Supports the -s option for disabling output, the -n option for limiting the number of characters read, and the -t option for specifying a timeout in fractional seconds. Bash's `read` builtin is the only major `read(1)` implementation which supports all listed non-compliant options, hence the script will likely need to be run via the Bash shell.\n\nOtherwise, **at least one** of the below non-compliant features and commands must be supported:\n\n* `date(1)` - Can return nanoseconds via the '%N' format.\n* `sleep(1)` - Supports the use of fractional values for the time operand to represent units of time less than 1 second, e.g. 0.05.\n* `sleep(1)` - Supports the use of E notation for the time operand to represent units of time less than 1 second, e.g. 5e-2.\n* `usleep(1)`\n\n### Terminal I/O\n\nThe script utilizes terminal capabilities via `tput(1)`, but will fall back to the following where possible if those capabilities fail:\n\n* [ANSI X3.64](https://en.wikipedia.org/wiki/ANSI_escape_code) escape codes for terminal styling and cursor movement.\n* `$COLUMNS` and `$LINES` environment variables for determining terminal size. Will fall back to 80 columns and/or 24 lines if one or both of the environmental variables are not set.\n\nIf keyboard controls are enabled (-k/keycontrols option), keyboard input is read from **/dev/tty** by default. This can be changed via the -K/devkeyinput option.\n\n## Contributing\n\nPlease adhere to the following when creating a pull request:\n\n* Ensure changes do not cause [ShellCheck](https://www.shellcheck.net/) to return any errors or warnings. This can be checked by either running `make test` with ShellCheck installed, or by checking [**./tspreed**](./tspreed) (and [**./default.rc**](./default.rc) if changed) via the online checker. If changes include new warning suppressions please provide an explanation.\n* Ensure changes comply with [POSIX.1-2001](https://pubs.opengroup.org/onlinepubs/000095399/), but does not include any features that are removed from or marked as obsolete in [POSIX.1-2008](https://pubs.opengroup.org/onlinepubs/9699919799/). If non-compliant changes are required please provide an explanation.\n* Ensure changes match the general coding style of the project.\n* Ensure changes are branched from `develop` and the pull request merges back into `develop`.\n\n## License\n\nCopyright © 2020-2024 Nicholas Ivkovic.\n\nLicensed under the GNU General Public License version 3 or later. See [**./LICENSE**](./LICENSE), or [https://gnu.org/licenses/gpl.html](https://gnu.org/licenses/gpl.html) if more recent, for details.\n\nThis is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fn-ivkovic%2Ftspreed","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fn-ivkovic%2Ftspreed","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fn-ivkovic%2Ftspreed/lists"}