Asciiville Documentation

Asciiville documentation is now available on Read the Docs

All Asciiville commands have manual pages. Execute man <command-name> to view the manual page for a command. The asciiville frontend is the primary user interface for Asciiville and the manual page for asciiville can be viewed with the command man asciiville. Most commands also have help/usage messages that can be viewed with the -u argument option, e.g. asciiville -u.

In interactive mode, the asciiville command presents a series of menus from which commands can be executed. Each of these menus provides an entry point for a ‘Help’ menu that can be displayed by typing ‘h’ at the prompt. The Asciiville Help menu contains a large number of menu entries providing access to manuals and man pages describing usage of the Asciiville components. Run the asciiville command with no arguments or the -i argument to bring up the interactive menu interface.

Aewan README

  • aewan, Introduction to the Aewan ascii art creation tool

Btop++ README

  • btop - Introduction to the btop system monitor

Cbftp README

  • cbftp - Introduction to the cbftp FTP client
  • Video on Cbftp - Video introduction to the cbftp FTP client

Ddgr README

  • ddgr, Introduction to the ddgr command line web search utility

Man Pages

Commands

Asciiville adds the following commands to your system:

Commands with man pages

asciiville
primary user interface, invokes terminal emulators, ascii animations, system monitor, mail client, file manager, web browser, and more
btop
character based system monitor
cbftp
character based FTP client
ascinit
one-time initializaton of a user’s Asciiville configuration
asciisplash
fun ascii art screens using ASCIImatics animations
asciiart
ASCIImatics animated art images
asciijulia
ASCIImatics animated zoom on a Julia Set
asciiplasma
ASCIImatics animated plasma graphic
asciimpplus
ASCIImatics animated Music Player Plus splash screen
show_ascii_art
display ascii art, convert images to ascii art
show_moon
display the phase of the Moon
show_weather
display a weather report
termprofset
set/restore default profile or font settings for the Gnome, Xfce4, and Tilix terminals

Commands without man pages

aewan/aecat/aemakeflic
Ascii Art creation tools
asciibrow
browse the web in character mode
datafilecat
decrypts the content of a cbftp data file
datafilewrite
encrypts the content of a cbftp plain text data file
ddgr
command line web search using DuckDuckGo
gameserver
multi-player game server
got
text based translation tool
gum
a tool for glamorous shell scripts
vhs
script a terminal session and save it as a GIF
any2a
any image format to ascii conversion utility
jp2a
jpg/png image to ascii conversion utility
make_ascii_art
generate ascii art from images
mapscii
character based zoomable map of the world
nethack
character based dungeon game
ninvaders
classic video game
rainbowstream
command line Twitter client
set_xfce_font
sets an xfce4-terminal window’s font and font size
set_xfce_trans
sets an xfce4-terminal window’s transparency level
show_endo
display a series of ascii fluid dynamics simulations
show_pokemon
display a Pokemon pocket monster
tdraw
ASCII drawing tool
term-image
Display and browse images in the terminal
tetris
classic video game

Commands from other projects

In addition to the above commands which reside in the Asciiville project, several commands may also be installed as dependencies. These include:

asciinema
ascii animation
bb
AAlib demo animation
cmatrix
display that screen from “The Matrix”
figlet
display Figlet Text
gnupg
pretty good privacy
ImageMagick
the ImageMagick suite of graphics command line tools
jq
json parsing and manipulation tool
khard
contact management for the console
mplayer
media player
neofetch
system info
neomutt
sophisticated text-based EMail and NNTP client
nvim
neovim, an extensible screen-based text editor
newsboat
text-based RSS feed reader
ranger
text-based file management
speedtest-cli
text-based command line network speed test
tmux
embed commands and terminal sessions in a terminal multiplexer
urlscan
scan for urls in a message
w3m
text-based web browser

The Kitty terminal emulator is installed during ascinit. Several other terminal emulators art optionally installed during ascinit unless initialization is performed with ascinit -c or ascinit -N. The optional terminal emulators are:

  • cool-retro-term
  • gnome-terminal
  • tilix :
  • xfce4-terminal

Usage

Many of the Asciiville features and facilities work perfectly well with both fixed and variable width fonts. However, Ascii Art and graphics are best viewed using a Monospaced or “fixed-width” font such as “Courier”, “Lucida Console”, “Monaco”, “Consolas”, “Inconsolata”, or “Monospace Regular”. Variable width fonts can interfere with the intended display of Ascii Art.

The Asciiville package creates an “Asciiville” profile in the gnome-terminal and tilix terminal emulators to configure use of a Monospaced font as well as invoking kitty and xfce4-terminal with a Monospaced font. The asciiville command attempts to ensure the use of a Monospaced font where it is possible but options do exist for the Asciiville user to use whatever the current terminal window might be. In this case, “Use Current Terminal”, the Asciiville user may need to manually configure the terminal window for Monospaced font use.

When viewing Ascii Art in non-slideshow mode, for example if asciiville were invoked with ascii art filenames as arguments, the user can enter ‘z’ or ‘b’ followed by ‘Return’ to enter “zoom/browse” mode. In this mode the user can zoom in and out of the ascii art. Use the following key presses to navigate in zoom/browse mode:

  • ‘i’ zoom in
  • ‘j’ zoom in more
  • ‘n’ zoom in even more
  • ‘o’ zoom out
  • ‘k’ zoom out more
  • ‘m’ zoom out even more
  • ‘r’ restore to original
  • ‘h’ display a help message
  • ‘q’ or ‘x’ to exit zoom/browse mode

In addition, in non-slideshow mode the user can enter ‘s’ or ‘S’ followed by ‘Return’ to enter info “slideshow” mode. In slideshow mode the ascii art is displayed for a few seconds then the next file is displayed. No user interaction is possible during slideshow mode other than ‘Ctrl-c’ to exit.

Usage message for the asciiville command

The usage message for asciiville provides a brief summary of the command line options:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81

Usage: asciiville [-a] [-A] [-b] [-c command] [-C] [-d] [-D delay]
 [-E len] [-f] [-F] [-g] [-i] [-I] [-jJ] [-k] [-l] [-L level]
 [-m] [-M] [-N] [-n num] [-p] [-P script] [-r] [-R] [-s song]
 [-S] [-t] [-T] [-U] [-v] [-V show] [-w] [-W] [-x] [-X] [-y]
 [-Y] [-z] [-Z] [-u] [file1 [file2 ...]]

Terminal/Command options:
 -c 'command' indicates use 'command'
  If 'command' is keyword 'endo' then display ascii fluid simulation
  If 'command' is keyword 'maps' then display a map using mapscii
  If 'command' is keyword 'moon' then display the phase of the Moon
  If 'command' is keyword 'news' then display RSS news feeds
  If 'command' is keyword 'reddit' then display Reddit terminal UI
  If 'command' is keyword 'search' then a web search is performed
  If 'command' is keyword 'speed' then a speed test is performed
  If 'command' is keyword 'translate' then the translation tool is run
  If 'command' is keyword 'twitter' then a Twitter client is run
  If 'command' is keyword 'weather' then display a weather report
  Otherwise, 'command' will be executed in a terminal window
 -d indicates use disk usage analyzer as default command
 -f indicates use cbftp/ncftp as the default command
 -F indicates fullscreen display
 -g indicates use gnome terminal emulator
 -i indicates start asciiville in interactive mode
 -I indicates display system info
 -l indicates use lynx web browser as the default command
 -L 'level' lolcat coloring level
    'level' can be '0' (off), '1' (on), or '2' (animate)
 -r indicates use retro terminal emulator
 -t indicates use tilix terminal emulator
 -U indicates set command to Ninvaders
 -w indicates use w3m web browser as the default command
 -W indicates use cmatrix as the default command
 -x indicates use xfce4 terminal emulator
 -X indicates run commands in current terminal window
 -y indicates use ranger file manager as the default command
 -Y indicates use NetHack dungeon game as the default command
 -z indicates use neomutt email client as the default command
Slideshow/ASCIImatics animation options:
 -A indicates use Asciiville scenes in ASCIImatics display
 -a indicates play audio during display
 -b indicates use backup audio during display
 -C indicates cycle slideshow endlessly (Ctrl-c to exit show)
 -D 'delay' specifies delay, in seconds, between art display (default 5)
 -E 'len' indicates random slideshow of length 'len' (0 infinite)
 -j indicates use Julia Set scenes in ASCIImatics display
 -J indicates Julia Set with several runs using different parameters
 -m indicates use MusicPlayerPlus scenes in ASCIImatics display
 -M indicates use MusicPlayerPlus MPD client as default command
 -n num specifies the number of times to cycle ASCIImatics scenes
 -N indicates use alternate comments in Plasma ASCIImatics scenes
 -p indicates use Plasma scenes in ASCIImatics display
 -P script specifies the ASCIImatics script to run
 -s 'song' specifies a song to accompany an ASCIImatics animation
    'song' can be the full pathname to an audio file or a relative
    pathname to an audio file in the MPD music library or ~/Music/
 -S indicates display ASCIImatics splash animation
 -V 'show' displays an ascii art slide show
    'show' can be one of 'Art', 'Doctorwhen', 'Dragonflies',
    'Fractals', 'Friends', 'Iterated', 'Lyapunov', 'Nature',
    'Owls', 'Space', 'Vintage', 'Wallpapers', 'Waterfalls',
    the name of a custom ascii art folder, the slideshow keyword
    'files' which indicates display a slideshow using the ascii
    art files provided on the command line, or the slideshow
    argument 'files=/path/to/file' which indicates read the list
    of slideshow files from the file '/path/to/file'
 -Z indicates do not play audio during slideshow/animation

General options:
 -k indicates kill Asciiville tmux sessions and ASCIImatics scripts
 -R indicates record tmux session with asciinema
 -T indicates use a tmux session for either ASCIImatics or command
 -v displays the Asciiville version and exits
 -u displays this usage message and exits

Remaining arguments are filenames of ascii art to display
 Ascii art filenames can be relative to the Ascii Art Gallery folder
 and need not specify the filename suffix. For example:
  asciiville -L 2 Friends/tux Doctorwhen/Capitola_Village_Vivid

Invoked without any arguments, 'asciiville' will display an interactive menu

Usage message for the show_ascii_art command

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66

Usage: show_ascii_art [-a art[,art2,...]] [-A art_dir] [-b] [-B] [-c] [-C]
 [-d font_dir] [-D seconds] [-e term] [-E] [-F large_font] [-f small_font]
 [-g] [-i image] [-I input_dir] [-O output_dir] [-K fifo_name] [-l level]
 [-L] [-n tabs] [-N depth] [-o] [-p palette] [-P] [-q] [-r] [-R len]
 [-s show] [-S song] [-t first_text] [-T second_text]
 [-h height] [-w width] [-W] [-v] [-z] [-Z] [-u]
Where:
 -a 'art' specifies ascii art file(s) to display
  multiple files are separated by a comma with no spaces
  (e.g. '-a Friends/tux,Doctorwhen/Capitola_Village_Vivid')
  'art' can be the relative path to a file in:
   /usr/share/asciiville/art
  or the path to a file, with or without file extension
 -A 'art_dir' specifies the path to the ascii art folder
 -b when generating ascii art use a border
 -B use backup song when playing audio in slideshows
 -c cycle slideshow endlessly (Ctrl-c to exit show)
 -C center ascii art on screen if border detected
 -d 'font_dir' specifies the path to the figlet fonts
 -D 'seconds' specifies the delay, in seconds, between screens
 -e 'term' specifies the terminal in which execution occurs
  'term' can be one of 'gnome', 'xfce4', or 'tilix'
 -E disables font size changing
 -g convert image to grayscale
 -i 'image' specifies an image file to convert to ascii art
 -I 'input_dir' generates ascii art from all images in 'input_dir'
  and saves them in the directory specified with '-O output_dir'
  (defaults to current directory if '-O output_dir' is specified)
 -K 'fifo_name' use a FIFO to communicate back to caller when done
 -l 'level' use lolcat coloring, 'level' can be '1' or '2' (animate)
 -L lists the ascii art in the 'art_dir' and exits
 -f 'small_font' specifies the figlet font to use for small text
 -F 'large_font' specifies the figlet font to use for large text
 -n 'tabs' specifies the number of tabs to indent image display
 -N 'depth' specifies the color depth
  'depth' can be '4' (for ANSI), '8' (for 256 color palette)
  or '24' (for truecolor or 24-bit color)
 -o indicates overwrite any existing ascii art when saving
 -O 'output_dir' generates ascii art from all images in the
  directory specified with '-I' and saves them in 'output_dir'
 -P indicates play audio during slideshow
 -p 'palette' specifies which character set to use for ascii art
  'palette' can be one of 'def', 'long', 'rev', 'longrev'
  'def' is the default set, 'long' a long set,
  'rev' reverses default, 'longrev' reverses long
  Any other argument to '-p' will be taken as the character set
 -q don't display text, just the ascii art
 -r indicates select random fonts
 -R 'len' indicates random slideshow of length 'len' (0 'len' infinite show)
 -s 'show' slide show of ascii art
  'show' can be:
   'Art', 'Doctorwhen', 'Dragonflies', 'Fractals', 'Friends', 'Iterated'
   'Lyapunov', 'Nature', 'Owls', 'Space', 'Wallpapers', 'Waterfalls'
  or a custom folder name (with '-A art_dir')
 -S 'song' use 'song' as audio track
 -t 'first_text' specifies the first text to display
 -T 'second_text' specifies the second text to display
 -u displays this usage message and exits
 -h 'height' specifies the height of the converted ascii art
 -w 'width' specifies the width of the converted ascii art
  If only one of 'width' and 'height' is provided,
  calculate the other from image aspect ratio
 -W indicates do not wait for input to continue viewing ascii art
 -v indicates view ascii art and prompt to continue
 -Z indicates no ANSI escape sequences used in ascii art
 -z indicates save converted image ascii art in art_dir

Usage message for the asciisplash command

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

Usage: asciisplash [-A] [-a] [-b] [-C] [-c num] [-d] [-jJ] [-m] [-p] [-s song] [-u]
Where:
 -A indicates use all effects
 -a indicates play audio during ASCIImatics display
 -b indicates use backup audio during ASCIImatics display
 -C indicates use alternate comments in Plasma effect
 -c num specifies the number of times to cycle
 -d indicates enable debug mode
 -j indicates use Julia Set effect
 -J indicates Julia Set with several runs using different parameters
 -m indicates use Asciiville effect
 -p indicates use Plasma effect
 -s song specifies the audio file to play as accompaniment
  'song' can be the full pathname to an audio file or a relative
  pathname to an audio file in the MPD music library or
  $HOME/Music/
 -u displays this usage message and exits

Example invocations

The asciiville command is intended to serve as the primary interface to invoke commands. The asciiville command utilizes several different terminal emulators and can also be used to invoke any specified command. Some example invocations of asciiville follow.

Run asciiville in interactive menu mode:

asciiville

Display a random slideshow of 25 ascii art images selected from all galleries in the default terminal window

asciiville -E 25

Display a random slideshow of 30 ascii art images selected from the Vintage art gallery with a delay of 10 seconds between images in a Tilix terminal window

asciiville -E 30 -V Vintage -D 10 -t

Run asciiville in interactive mode with Ranger File Manager selected as command:

asciiville -i -y

Open the default client in fullscreen mode:

asciiville -F

Open the default client in fullscreen mode using the Tilix terminal emulator:

asciiville -F -t

Open the default client in the cool-retro-term terminal:

asciiville -r

Run ranger file manager in cool-retro-term terminal emulator:

asciiville -r -y

Run mpcplus music player in Tilix terminal emulator:

asciiville -M -t

Display a zoomable map of the world using mapscii:

asciiville -c maps

Display the Phase of the Moon using wttr.in:

asciiville -c moon

Display a random Pokemon:

asciiville -c pokemon

Run the ddgr command line web search in the current terminal window:

asciiville -c search

Run the rainbowstream command line Twitter client in the current terminal window:

asciiville -c twitter

Display a weather report for your IP address location using wttr.in:

asciiville -c weather

Run the cmus music player client in a gnome-terminal emulator window:

asciiville -c cmus -g

Run neomutt mail client in fullscreen mode in a tilix terminal emulator window:

asciiville -f -t -z

Run lynx web browser in a tmux session in an xfce4-terminal window:

asciiville -l -T -x

Creates an asciinema recording of btop system monitor in a tmux session:

asciiville -R -T

Run asciisplash displaying the Julia Set asciimatics animation with audio:

asciiville -S -j -a

Asciiville Wiki

Additional detail and info can be found in the Asciiville Wiki.