Skip to content

Home

Jump to bottom
poetaman edited this page Feb 6, 2023 · 104 revisions

Welcome to the arttime wiki!

Scriptable

Arttime can be scripted, orchestrated, and 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. All you need to do is: save the sequence of keys you intend to pass to arttime in a file, and point the file to arttime. Arttime will act as if you manually typed those keys in its window. Following are few of 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

More examples will be be added in future.

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 (un-tested)
  • ?? to get timer sounds (un-tested)
  • ??? to get desktop notifications (un-tested)
  • less to navigate help pages, though arttime would fallback on more which should be preinstalled on every unix system

arttime needs volunteer to test it under WSL on Windows, I do not have access to a system on which WSL would run. Feel free to drop a note in Windows WSL support.

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