Awesome

tspreed

tspreed 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.

Installation

Packages

Manual

Install

Replace github.com with gitlab.com if using GitLab.

$ git clone https://github.com/n-ivkovic/tspreed
$ cd tspreed
# make install

Update

$ git pull origin
# make update

Additional options

$ make help

Usage

To begin a presentation, pipe plain text into tspreed.

The presentation starts with the first word displayed for a minimum of 1 second, then all subsequent words are presented at the given speed (WPM).

If tspreed is terminated before the presentation has finished, the progress of the presentation is passed to stdout.

Keyboard controls

Keyboard 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.

Examples

$ tspreed < textfile

$ tspreed --wpm 300 --hide-cursor < textfile

$ pdftotext document.pdf - | tspreed -w 300 -n 120 -s '\r\f' -lqihkfb -p line -c 1 -K /dev/tty

Configuration

The 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.

The default configuration is provided in ./default.rc, which is installed as the global configuration file.

Portability

tspreed '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.

POSIX-compliance

tspreed attempts to comply with POSIX.1-2001 through to POSIX.1-2008 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.

If keyboard controls are enabled (-k/keycontrols option), both of the below non-compliant features must be supported:

• date(1) - Can return nanoseconds via the '%N' format.
• 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.

Otherwise, at least one of the below non-compliant features and commands must be supported:

• date(1) - Can return nanoseconds via the '%N' format.
• 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.
• 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.
• usleep(1)

Terminal I/O

The script utilizes terminal capabilities via tput(1), but will fall back to the following where possible if those capabilities fail:

• ANSI X3.64 escape codes for terminal styling and cursor movement.
• $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.

If 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.

Contributing

Please adhere to the following when creating a pull request:

• Ensure changes do not cause ShellCheck to return any errors or warnings. This can be checked by either running make test with ShellCheck installed, or by checking ./tspreed (and ./default.rc if changed) via the online checker. If changes include new warning suppressions please provide an explanation.
• Ensure changes comply with POSIX.1-2001, but does not include any features that are removed from or marked as obsolete in POSIX.1-2008. If non-compliant changes are required please provide an explanation.
• Ensure changes match the general coding style of the project.
• Ensure changes are branched from develop and the pull request merges back into develop.

License

Copyright © 2020-2024 Nicholas Ivkovic.

Licensed under the GNU General Public License version 3 or later. See ./LICENSE, or https://gnu.org/licenses/gpl.html if more recent, for details.

This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.