Skip to content

Home

Jump to bottom
poetaman edited this page May 15, 2023 · 97 revisions

Welcome to the arttime wiki!

Feed keystrokes from anywhere

Arttime can be controlled asynchronously by feeding keystrokes from various sources. Keystrokes can come from a string, file, pipe, fifo or remote process either at launch or during runtime. For instance, you can save the sequence of keys you intend to pass to arttime in a file, and point that file to arttime. Arttime will act as if you manually typed those keys in its window. If flow control is required, one can write a controller in programming language of choice, print and pipe keystrokes to arttime. All of this brings many benefits to the users, for instance:

  • save time and effort required to type long and repeatedly used key sequences
  • give expression to timers by associating them with a specific art, animation, message and color
  • completely reconfigure arttime at runtime, as many times as needed
  • quickly create innumerable storyboards from art in arttime's collection
  • extend arttime with more features

Following are few very simple examples, more will be added soon.

  1. Simple pipe:
printf 'cccg10s\nmHello World\nh' | arttime

This will start arttime in its SCRIPT mode. Keystroke c rotates color of main text area between 16 colors of terminal, so the three c's will change the color to your terminal's blue (it starts with red). Next g10s\n will start a 10 second timer (you will see a desktop notification if your Desktop environment is correctly setup). Then mHello World\n will change the message under art to Hello World, and finally h will toggle text area to displaying art (default is butterfly). All of this will happen quite fast, and then control will get transferred to your keyboard (start by pressing h to see the keybindings). While SCRIPT mode is active, arttime will show SCRIPT at the bottom right corner of the screen. Any keys pressed in SCRIPT mode will be ignored.

  1. Pipe with delays: arttime will remain in SCRIPT mode for around 22 seconds, enjoy the play!
(sleep 2; printf "a"; sleep 1; printf "b"; sleep 1; printf "a"; sleep 1; printf "t"; sleep 1; printf "s";  sleep 1; printf "\n"; sleep 1; printf "m"; sleep 1; printf "We"; sleep 1; printf " didn't"; sleep 1; printf " spread"; sleep 1; printf " covid";sleep 1; printf "..."; sleep 1; printf "\n"; sleep 1; printf "cccc"; sleep 2; printf 'g'; sleep 1; printf "1"; sleep 1; printf "0"; sleep 1; printf "s"; sleep 1; printf "\n") | arttime
  1. Heredoc/Herestring:
arttime <<<'cccg10s\nmHello World\nh'
#OR
arttime <<<$'cccg10s\nmHello World\nh'

or shells that don't support herestrings, use heredoc:

arttime << ARTKEYS
cccg10s\nmHello World\nh
ARTKEYS
  1. File: Let's say we have a file named mykeystrokes.txt that has the following contents:
cccg10s\nmHello World\nh

One can feed the keys in that file to arttime like this:

arttime <mykeystrokes.txt
#OR
arttime -k mykeystrokes.txt

More examples will be be added in future.

Keypoem file format

A file containing keystrokes for arttime is called "keypoem" in arttime's UI. The format of keypoem file is WYTIWYS (What you type is what you store), i.e. you would store the same characters in the file that you would have otherwise typed in arttime to create an effect (set timer, art, color, message etc). There are only couple of differences which we discuss below, but first here is the meaning of keys in arttime interface (which arttime displays upon launch by default):

c: change art color..............
h: toggle displaying help or art.
j: show random art to select.....
i: display time and art info.....
f: toggle between 12/24 hour time
z: set or reset timezone.........
g: set goals (ex:10s;1h20m;3PM)..
p: pause or un-pause goals.......
l: clear goals, show start time..
e: restart goals.................
r: reset start time & goals......
m: change title message..........
a: set a art using default method
b: set b art using default method
x: set a art using fzf...........
y: set b art using fzf...........
t: toggle theme..................
k: load keypoem, feed keystrokes.
q: quit arttime..................

The only exception to the meaning of keystrokes is that k is not interpreted as a keystroke that asks user for another keypoem file. Instead k from a keypoem file asks user a y/n question if they intend to close the file. This is not needed when reading from regular file, but is necessary when reading from a FIFO. The write end of FIFO must pass a k followed by y to signal arttime to stop reading keystrokes from the FIFO and start reading from keyboard. The user can also, at any given point of time, press Ctrl-c (or equivalent keybinding to signal interrupt) and arttime will cleanly transfer control from keypoem file to user's keyboard.

To read from a file at a more human pace, the filename can end with some special suffixes: 1) _Xb or _Xbps, to read the file at X bytes/second; 2) _Xms or _Xmspb, to read the file at X milliseconds/byte; 3) _Xs or _Xspb, to read the file at X seconds/byte. The benefit of this rate limiting is that it allows creating visual effects which are otherwise not possible (given modern processor speeds). Wherever user wishes to add delay between prompts, they can enter - (ASCII dash). Each dash inserts delay of 1 byte, so if the file ends with _8b then 8 dashes -------- stand for 1 second delay. Note: the newline character between lines also adds 1 byte of delay.

All the keypoem files that come preinstalled in arttime are stored under share/arttime/keypoems. There they are arranged with descriptive prefixes. For instance, prefix timer denotes that the file sets some timer or time management program, prefix story denotes that file is a arttime storyboard, etc. Enjoy!

Some examples follow:

  1. A timer keypoem timer.helloworld_8b that sets "helloworld" art, message, and a 1 minute timer
----
aworldmap
----
mExperience joy of "Hello, World!" for 1 minute!
----
g1m

arttime_helloworldtimer

  1. A animation keypoem anim.winnepooh that sets animation to dancing winnie animation (pardon the spelling):
awinnepooh
bwinnepooh2

arttime_winnieanimation

  1. A storyboard keypoem story.batscovid_8b that runs a short (~2 minute) story about COVID and a fictitious company called "Fizzer". The first 30 seconds of the storyboard is attached here as a video:

arttime_storyboard

Modes and keybindings

Arttime can be in one of many modes at any given point in time and the meaning of keystrokes varies between these modes, the modes are:

  • NORMAL
  • GETLINE
  • GETCHAR
  • SCRIPT
  • PAUSED

When arttime is not being fed keystrokes from a special file, it interprets keystrokes from keyboard (tty to be more precise). This is the NORMAL mode of operation, and the default mode of arttime. The help page that arttime displays upon launch shows meaning of keys in this mode (also shown on this page in a listing of section Keypoem file format). While in NORMAL mode, pressing a key like r, e, l, p, can make arttime enter GETCHAR mode. This is mostly used for asking user for confirmation, and pressing y (yes) / n (no) makes arttime take appropriate action and exit GETCHAR mode. The meaning of all keys in GETCHAR mode is always shown while asking user to type a character. While in NORMAL mode, if a user presses any key (like keys g,m,z...) that asks user to enter a line, arttime enters GETLINE mode. Arttime remains in this mode till user presses Enter. While in GETLINE mode, the usual keyboard characters would help you construct a line. Below are some special key-bindings of GETLINE mode, the rest are same as default keybindings of zsh's line editor.

Arrow-up: Jump to old value in prompt history
Arrow-down: Jump to new value in prompt history
Arrow-left: Move cursor left
Arrow-right: Move cursor right
Ctrl-a: Jump to beginning of line
Ctrl-e: Jump to end of line
Ctrl-r: Incremental search backwards in prompt history
Ctrl-f: Incremental search forwards in prompt history
Ctrl-k: Pattern search forward in prompt history
Ctrl-j: Pattern search backward in prompt history
Ctrl-l: List prompt history items as a list (enter a number to select an item)

When arttime is being fed keystrokes from a source other than keyboard, it enters SCRIPT mode. Arttime remains in SCRIPT mode till either the file ends, or is sent a special sequence ky from the file, or user presses interrupt on keyboard (mostly bound to Ctrl-c). While in SCRIPT mode, a user can pause/unpause reading from the file by pressing p. Note: always unpause after a pause before sending Ctrl-c to end reading from file. While SCRIPT mode reading from file is paused, arttime will show PAUSED at the bottom right of the screen. After SCRIPT mode ends (for whatever reason), arttime enters NORMAL mode again to listen to user input.

Render art more accurately

The repository of arttime has different kinds of text art:

  1. ASCII
  2. ANSI (Unicode restricted to CP437 subset)
  3. PETSCII (Unicode restricted to Commodore 64 subset)
  4. Unicode (unrestricted)

Each art type has different set of requirements to render well in a modern terminal. Though one can make a configuration change to their terminal to be able to render all text art from arttime's repository well, while also continuing to use terminal for what it is originally meant — getting work done. A description on what steps could be needed to achieve that result will be added here shortly.

What steps could be needed to do a best-effort render of text art in one's main terminal application depends on what all can come in the way of achieving an accurate render, these include: 1) colors and 2) fonts.

1) Colors

Art in arttime's collection can be divided in four types based on color information:

  1. Black-and-White
  2. 16 colors
  3. 256 colors
  4. 24-bit RGB ("truecolor")

Steps related to color are:

  • Contrast: Choose a color theme with big contrast between background and foreground, with background being dark. Most art in this repository was done with white on black background, though there are some which are reverse. Preferably you want to use a modern terminal application that allows switching color theme on the fly, recommendations will be added below.
  • Palette: Choose a theme whose lower 16 colors conform to hue relations which were originally intended from 16 color ANSI's inception (1:Red, 2:Green, etc...). This means not using base16 themes of chriskempson's framework for your terminals color theme as they don't respect hue relation for bright colors. While modern terminals allow mapping all of the 16 colors to the RGB values that a user is comfortable with, including users affected by color blindness (also check vim-dichromatic), earlier ANSI art was done assuming a more restricted medium. If you wish to see how ANSI art exactly looked like or is exactly intended by a text artist, then select a theme with default CGA 16 color palette .
  • Depth: Choose terminal that supports 24-bit RGB colors if possible, though most ASCII and ANSI art will display well even on 16 color terminals. Some modern unicode art requires at least 256 colors or full 24-bit RGB colors. Once you move to a terminal that supports 24-bit colors, colors in all art will display reasonably well.
  • Transparency: Most art will render well even if you turn on transparency in terminal. Though art which utilizes half-block technique of blending adjacent foreground and background colors to create shapes might not render best if background colors are made transparent while foreground colors aren't.

2) Fonts

Many things related to one's font can come in the way of getting a good reproduction of text art in terminal. Moreover, text artists who produce ANSI art might want the users to appreciate their art by viewing it in a certain font. They would definitely not appreciate users to post a screenshot of their work in thin courier font on social media, as it might not show their work in correct light. Here are the things that can go wrong with font while viewing art:

  • Missing characters: Each of ASCII, ANSI, and Unicode art has increasing requirement for glyphs. ASCII art requires just 128 characters, and is supported by all fonts worthy of use in terminal. ANSI art uses just 256 characters that are part of IBM-CP437. While PETSCII also uses just 256 characters, they are different (check Commodore 64 character set). Not many fonts provide all 256 characters of IBM-CP437 or Commodore 64 though. To display ANSI/PETSCII, a font must at least have Unicode block "Symbols for Legacy Computing" (link), among other blocks. Unicode has 149,186 characters as of v15.0 of Unicode standard. But unicode art in arttime repository uses a very small subset, one that is commonly found in fonts (braille characters, etc). An example modern font that has a good number of glyphs while also being usable for work in terminal is Pragmasevka. Here is a build of it that also has nerd font glyphs: PragmasevkaNerdFontV1p2.zip. If you are looking for something more wide, then IBM Plex Mono is a possibility. And if you are looking for a font that has the most unicode characters, then GNU Unifont is the way to go.

  • Shape: Monospace font shape can be broadly categorized as having: narrow vs broad aspect, thin vs thick stroke. Select a font somewhere in between for those parameters. Courier fonts are definitely not something you want even for a reasonable work environment in terminal. Some text art will carry metadata in future to inform you about the font used by artist to create their work.

  • Ligatures: If your font and terminal are fancy enough to support ligatures and if you wish to use the same terminal for work as well as displaying art, then turn off ligatures permanently. If you are motivated enough, ask your favorite terminal or terminal-multiplexer developers to support disabling ligatures on a per pane basis. Then you will be able to display art without ligatures in a pane while using ligatures in another pane for code. I have never been convinced with the idea of programming ligatures as they get in the way of explaining code to others who aren't used to them. It's like showing new math symbols to readers who aren't using them in their own math, it gets in the way of communication.

  • Mapping: For most modern terminal users mapping would not require any configuration change. All art in arttime project is unicode encoded, which is a standard mapping provided by all modern fonts. Old fonts or modern fonts intended to view older text files still use old character mapping. If a user still has fonts which use old mappings, they are recommended to use a unicode compliant font instead.

Terminals

Most modern terminal emulators support 24-bit RGB ("truecolor"), and other modern features like changing colors/fonts on the fly. In case the terminal you have been using does not support such features, here are some suggested terminals. Easiest one for macOS: iTerm2, for multiple OSes: Alacritty, WezTerm, Kitty etc. Check the list maintained here to know more terminals that support 24-bit RGB colors.

Note: there is a bug in a terminal library called vte used by some terminals like gnome. It makes some ANSI characters not render well, the recommendation is to use non-vte terminals like xterm, konsole, urxvt, etc till that bug (check the link here) is resolved.

Dependencies

arttime is meant to work with "zero dependencies", or approximately so. All one needs is zsh (>=5.7) to start using arttime. Some features like desktop notifications and sounds work out of the box on macOS, and well-configured Desktop Environment (DE) of Linux and BSD Unixes. For Linux or BSD Unix DEs that are not fully setup yet, users would need 1-2 additional packages installed on their system.

How to test if you have a dependency? Open terminal, and run which <dependency_name>. So, you would run which zsh to see if it returns path to zsh. zsh --version to check if version is equal to or greater than 5.7. which paplay to see if it returns path to Pulse Audio's paplay, which pw-play to check if pipewire is installed or which ogg123 to check if vorbis-tools is installed. which notify-send to check if libnotify's notify-send binary is installed. which less to check if less is installed. If you don't find your OS-specific commands to install dependencies on this page, check arttime discussions: Linux dependency installation, Unix dependency installation, or Windows WSL support.

You could also first try installing and running arttime, check arttime installation steps.

macOS

Zero dependencies, works out of the box.

Linuxes

  • zsh (>=5.7) to get arttime running
  • vorbis-tools to get sounds (needed only if pulseaudio or pipewire are not installed, though recommend as a fallback to have anyway)
  • notify-send to get desktop notifications
  • less to navigate help pages, though arttime would fallback on more which should be preinstalled on every unix system

Note to all Linux package maintainer: If you are drafting an arttime package for Linux, add only 3 dependencies for it: 1) zsh (to get it up and running), 2) vorbis-tools (provides ogg123 to play sounds irrespective of sound server), and 3) libnotify-bin (or equivalent that provides command notify-send to get desktop notifications). The reason to not add sound servers like pulseaudio or pipewire is dependency is that a user might switch sound servers over time, and that shouldn't conflict with arttime.

To contribute your Linux's distribution-specific installation instructions, please comment on Linux dependency installation

Debian

  • zsh: apt install zsh
  • vorbis-tools: apt install vorbis-tools (not strictly needed as pulseaudio is preinstalled, though recommend as a fallback to have anyway)
  • notify-send: apt install libnotify-bin
  • less: apt install less

Kali

Zero dependencies, works out of the box.

Unixes

  • zsh (>=5.7) to get arttime running
  • vorbis-tools to get sounds (needed only if pulseaudio or pipewire are not installed, though recommend as a fallback to have anyway)
  • notify-send to get desktop notifications
  • less to navigate help pages, though arttime would fallback on more which should be preinstalled on every unix system

Note to all Unix package maintainer: If you are drafting an arttime package for Unix, add only 3 dependencies for it: 1) zsh (to get it up and running), 2) vorbis-tools (provides ogg123 to play sounds irrespective of sound server), and 3) libnotify-bin (or equivalent that provides command notify-send to get desktop notifications). The reason to not add sound servers like pulseaudio or pipewire is dependency is that a user might switch sound servers over time, and that shouldn't conflict with arttime.

To contribute your Unix flavor-specific installation instructions, please comment on Unix dependency installation

Windows WSL

  • zsh (>=5.7) to get arttime running
  • wsl-notify-send.exe to get desktop notifications and sounds. Get it from here: wsl-notify-send
  • less to navigate help pages, though arttime would fallback on more which should be preinstalled on every unix system

The following zip will have a collection of test files for arttime, users don't need to download. arttime_test.zip

Clone this wiki locally