Turn images into text better than caca/aalib


hiptext Build Status

hiptext is command line tool for rendering images and videos inside terminals.

Last Supper in Macterm

Happy Cat in Macterm

Obama in Macterm


You need clang or gcc >=4.7. You also need to install:

sudo apt-get install build-essential libpng12-dev libjpeg-dev \
    libfreetype6-dev libavformat-dev libavcodec-dev \
    libswscale-dev libgflags-dev libgoogle-glog-dev ragel


wget https://github.com/jart/hiptext/releases/download/0.2/hiptext-0.2.tar.gz
tar xvzf hiptext-0.2.tar.gz
cd hiptext-0.2

make -j4
sudo make install



Most image types, e.g. JPEG, PNG, GIF, etc. are supported.

hiptext balls.png


You can play videos in your terminal using hiptext. Yes, really.

youtube-dl -o gangnam-style.mp4 https://www.youtube.com/watch?v=9bZkp7q19f0
hiptext gangnam-style.mp4


hiptext --spectrum
hiptext --nocolor balls.png
hiptext --nocolor --chars=" .oO0" balls.png

Rendering Modes


By default, hiptext assumes you're using an xterm256 compatible terminal, e.g. gnome-terminal, without bothering to check the TERMINAL environment variable.

hiptext --xterm256 balls.png

To double the number of pixels using Unicode half blocks, consider using the following option, which may become the default in the future:

hiptext --xterm256unicode balls.png


The most beautiful terminal for hiptext is the one built into Mac OS X called Terminal.app. This terminal uses xterm256 but it's implemented using a custom color palette that was chosen by designers rather than engineers.

But the interesting thing about this palette is that it uses slightly different colors for foreground and background. By using Unicode half blocks, this allows us to simulate something closer to 512 colors!

hiptext --macterm balls.png

However to use this, you must be using the black color scheme. After all, why would you use anything else?


If you want to render an image without the ANSI color escape codes, you can use the --nocolor flag. This will render the image using shaded unicode block characters.

hiptext --nocolor balls.png


The no-color mode supports a very simple character quantiser that can convert images to ASCII. Please understand that if this is what you want, there are much better tools for the job, like cacalib.

hiptext --nocolor --chars=" .oO0" balls.png


If you use a SIXEL terminal, e.g. mlterm >=v3.1.3, then the following flags can provide much more minute rendering:

hiptext --sixel256 balls.png           # For 256-color SIXEL terminal such as mlterm (>=v3.1.3)
hiptext --sixel16 balls.png            # For 16-color SIXEL terminal such as xterm(patch level >= #294) with "-ti vt340 option"
hiptext --sixel2 balls.png             # For monochrome SIXEL terminals



By default, hiptext assumes that your terminal background is black. If this is not the case, you can specify your background color using a CSS or X11 color string.

hiptext --bg=white balls.png
  • Dependencies on a Mac...

    Dependencies on a Mac...

    Disclaimer: It's been ages since I've compiled a darn thing... Feel free to tell me to RTFM... just point me in the right direction first :)

    I'm having a hell of a time getting hiptext compiled... Looking to do this from OS X and I've been using MacPorts, since it seemed like the easiest way to grab most of the dependencies you'd listed (grabbed ffmpeg, wget for your install-g*.sh scripts, and ragel). I believe I'm using gcc4.8 — at least the MacPorts version.

    At this point when I make I'm getting an output of:

    c++ -g -O3 -std=c++11 -Wall -Wextra -Werror -fno-exceptions -fno-rtti -MD -march=native -c -o hiptext.o hiptext.cc /var/folders/m_/6p8v1kgj1_n_56hr05k8f_z40000gn/T//ccDk5vz7.s:3204:no such instruction: vmovsd 504(%rsp), %xmm0' c++ -g -O3 -std=c++11 -Wall -Wextra -Werror -fno-exceptions -fno-rtti -MD -march=native -c -o hiptext.o hiptext.cc /var/folders/m_/6p8v1kgj1_n_56hr05k8f_z40000gn/T//ccDk5vz7.s:3204:no such instruction:vmovsd 504(%rsp), %xmm0' /var/folders/m_/6p8v1kgj1_n_56hr05k8f_z40000gn/T//ccDk5vz7.s:3205:no such instruction: vucomisd 8(%rdx), %xmm0' /var/folders/m_/6p8v1kgj1_n_56hr05k8f_z40000gn/T//ccDk5vz7.s:3209:no such instruction:vmovsd 512(%rsp), %xmm0' /var/folders/m_/6p8v1kgj1_n_56hr05k8f_z40000gn/T//ccDk5vz7.s:3210:no such instruction: vucomisd 16(%rdx), %xmm0' /var/folders/m_/6p8v1kgj1_n_56hr05k8f_z40000gn/T//ccDk5vz7.s:3214:no such instruction:vmovsd 520(%rsp), %xmm0' /var/folders/m_/6p8v1kgj1_n_56hr05k8f_z40000gn/T//ccDk5vz7.s:3215:no such instruction: vucomisd 24(%rdx), %xmm0' /var/folders/m_/6p8v1kgj1_n_56hr05k8f_z40000gn/T//ccDk5vz7.s:3223:no such instruction:vmovsd (%rax), %xmm0' /var/folders/m_/6p8v1kgj1_n_56hr05k8f_z40000gn/T//ccDk5vz7.s:3233:no such instruction: vaddsd 8(%rax), %xmm0,%xmm0' /var/folders/m_/6p8v1kgj1_n_56hr05k8f_z40000gn/T//ccDk5vz7.s:3234:no such instruction:vaddsd 16(%rax), %xmm0,%xmm0' /var/folders/m_/6p8v1kgj1_n_56hr05k8f_z40000gn/T//ccDk5vz7.s:3235:no such instruction: vdivsd LC49(%rip), %xmm0,%xmm0' /var/folders/m_/6p8v1kgj1_n_56hr05k8f_z40000gn/T//ccDk5vz7.s:3236:no such instruction:vmulsd 24(%rax), %xmm0,%xmm0' /var/folders/m_/6p8v1kgj1_n_56hr05k8f_z40000gn/T//ccDk5vz7.s:3240:no such instruction: vmulsd LC50(%rip), %xmm0,%xmm0' /var/folders/m_/6p8v1kgj1_n_56hr05k8f_z40000gn/T//ccDk5vz7.s:3241:no such instruction:vcvttsd2si %xmm0, %eax' /var/folders/m_/6p8v1kgj1_n_56hr05k8f_z40000gn/T//ccDk5vz7.s:3355:no such instruction: vmovsd 496(%rsp), %xmm0' /var/folders/m_/6p8v1kgj1_n_56hr05k8f_z40000gn/T//ccDk5vz7.s:3379:no such instruction:vucomisd (%rdx), %xmm0' /var/folders/m_/6p8v1kgj1_n_56hr05k8f_z40000gn/T//ccDk5vz7.s:3387:no such instruction: vmovsd (%rax), %xmm0' /var/folders/m_/6p8v1kgj1_n_56hr05k8f_z40000gn/T//ccDk5vz7.s:3390:no such instruction:vaddsd 8(%rax), %xmm0,%xmm0' /var/folders/m_/6p8v1kgj1_n_56hr05k8f_z40000gn/T//ccDk5vz7.s:3391:no such instruction: vaddsd 16(%rax), %xmm0,%xmm0' /var/folders/m_/6p8v1kgj1_n_56hr05k8f_z40000gn/T//ccDk5vz7.s:3392:no such instruction:vdivsd LC49(%rip), %xmm0,%xmm0' /var/folders/m_/6p8v1kgj1_n_56hr05k8f_z40000gn/T//ccDk5vz7.s:3393:no such instruction: vmulsd 24(%rax), %xmm0,%xmm0' /var/folders/m_/6p8v1kgj1_n_56hr05k8f_z40000gn/T//ccDk5vz7.s:3397:no such instruction:vmulsd LC50(%rip), %xmm0,%xmm0' /var/folders/m_/6p8v1kgj1_n_56hr05k8f_z40000gn/T//ccDk5vz7.s:3398:no such instruction: `vcvttsd2si %xmm0, %ecx'

    At this point I haven't the foggiest as to what I should try next. :/ Any suggestions, are hugely appreciated.

    opened by dsteele7 16
  • Compile Error

    Compile Error

    $ make g++ -g -O3 -std=c++11 -Wall -Wextra -Werror -fno-exceptions -fno-rtti -MD -march=native -c -o hiptext.o hiptext.cc g++ -g -O3 -std=c++11 -Wall -Wextra -Werror -fno-exceptions -fno-rtti -MD -march=native -c -o artiste.o artiste.cc g++ -g -O3 -std=c++11 -Wall -Wextra -Werror -fno-exceptions -fno-rtti -MD -march=native -c -o charquantizer.o charquantizer.cc g++ -g -O3 -std=c++11 -Wall -Wextra -Werror -fno-exceptions -fno-rtti -MD -I/usr/include/freetype2 -march=native -c -o font.o font.cc g++ -g -O3 -std=c++11 -Wall -Wextra -Werror -fno-exceptions -fno-rtti -MD -march=native -c -o graphic.o graphic.cc g++ -g -O3 -std=c++11 -Wall -Wextra -Werror -fno-exceptions -fno-rtti -MD -march=native -c -o jpeg.o jpeg.cc g++ -g -O3 -std=c++11 -Wall -Wextra -Werror -fno-exceptions -fno-rtti -MD -march=native -c -o macterm.o macterm.cc g++ -g -O3 -std=c++11 -Wall -Wextra -Werror -fno-exceptions -fno-rtti -MD -march=native -c -o movie.o movie.cc movie.cc: In destructor ‘Movie::~Movie()’: movie.cc:42:48: error: ‘avformat_close_input’ was not declared in this scope if (format_) avformat_close_input(&format_); ^ make: *** [movie.o] Error 1

    opened by whit2333 13
  • Issue #16 Sixel support

    Issue #16 Sixel support

    This PR is a quick implementation of SIXEL graphics(Issue #16).

    It introduces the following new options.

    -sixel2 : emit monochrome sixel
    -sixel16 : emit 16-color sixel
    -sixel256 : emit 256-color sixel

    Note that we can get more beautiful picture using palette re-definition sequence If this software can do dynamic-palette quantization method(such as median-cut), but I didn't know how to do it.


    • mlterm (it works with X11 / frame buffer / win32 version, http://mlterm.sourceforge.net) mlterm
    • xterm with "-ti vt340" option (color palette is limited up to 16) xterm-ti340
    • RLogin (Japanese high spec terminal emulator. it also implements ReGIS. see http://nanno.dip.jp/softlib/man/rlogin/#REGWIND) rlogin
    • tanasinn (A firefox extension, see http://zuse.jp/tanasinn/) tanasinn

    I tested this patch on above 4 terminals.

    opened by saitoha 5
  • Sixel support?

    Sixel support?

    I was wondering whether xterm's support for sixel graphics might offer higher-quality output. (Dunno if any other terminal emulators support sixels. I'd be surprised.)

    opened by rrthomas 3
  • Errors on each run after make install

    Errors on each run after make install

    If i run hiptext from the directory I compiled it from it works fine. After running make install I get an error on the same images that it previously displayed without errors.

    F0325 13:59:22.764736   601 font.cc:32] Check failed: 0 == FT_New_Face( g_library, FLAGS_font.c_str(), FLAGS_font_index, &g_face) (0 vs. 1) 
    *** Check failure stack trace: ***
        @     0x7f09022d096a  (unknown)
        @     0x7f09022d08a5  (unknown)
        @     0x7f09022d0299  (unknown)
        @     0x7f09022d3297  (unknown)
        @           0x40d7e4  InitFont()
        @           0x403fe2  main
        @     0x7f08ff68aead  (unknown)
        @           0x40adbd  (unknown)
    [1]    601 abort      hiptext 2012-08-23_19-10-52_570.jpg
    opened by ghost 3
  • Compilation Errors

    Compilation Errors

    I keep on receiving a compilation error.

    g@cloudshell:~/hiptext-0.2 (removed-for-privacy)$ ./configure
    checking for a BSD-compatible install... /usr/bin/install -c
    checking whether build environment is sane... yes
    checking for a thread-safe mkdir -p... /bin/mkdir -p
    checking for gawk... no
    checking for mawk... mawk
    checking whether make sets $(MAKE)... yes
    checking whether make supports nested variables... yes
    checking build system type... x86_64-unknown-linux-gnu
    checking host system type... x86_64-unknown-linux-gnu
    checking for pkg-config... /usr/bin/pkg-config
    checking pkg-config is at least version 0.22... yes
    checking for g++... g++
    checking whether the C++ compiler works... yes
    checking for C++ compiler default output file name... a.out
    checking for suffix of executables...
    checking whether we are cross compiling... no
    checking for suffix of object files... o
    checking whether we are using the GNU C++ compiler... yes
    checking whether g++ accepts -g... yes
    checking for style of include used by make... GNU
    checking dependency style of g++... gcc3
    checking whether g++ supports C++11 features by default... yes
    checking for ranlib... ranlib
    checking for gcc... gcc
    checking whether we are using the GNU C compiler... yes
    checking whether gcc accepts -g... yes
    checking for gcc option to accept ISO C89... none needed
    checking whether gcc understands -c and -o together... yes
    checking dependency style of gcc... gcc3
    checking for a sed that does not truncate output... /bin/sed
    checking how to run the C preprocessor... gcc -E
    checking for grep that handles long lines and -e... /bin/grep
    checking for egrep... /bin/grep -E
    checking whether gcc is Clang... no
    checking whether pthreads work with -pthread... yes
    checking for joinable pthread attribute... PTHREAD_CREATE_JOINABLE
    checking whether more special flags are required for pthreads... no
    checking for PTHREAD_PRIO_INHERIT... yes
    checking for jpeg_set_defaults in -ljpeg... yes
    checking for LIBAVCODEC... yes
    checking for LIBAVFORMAT... yes
    checking for LIBAVUTIL... yes
    checking for LIBGFLAGS... no
    configure: error: Package requirements (libgflags) were not met:
    No package 'libgflags' found
    Consider adjusting the PKG_CONFIG_PATH environment variable if you
    installed software in a non-standard prefix.
    Alternatively, you may set the environment variables LIBGFLAGS_CFLAGS
    and LIBGFLAGS_LIBS to avoid the need to call pkg-config.
    See the pkg-config man page for more details.
    g@cloudshell:~/hiptext-0.2 (removed-for-privacy)$ make -j4
    make: *** No targets specified and no makefile found.  Stop.
    g@cloudshell:~/hiptext-0.2 (removed-for-privacy)$ sudo make install
    make: *** No rule to make target 'install'.  Stop.
    opened by viveksh1 2
  • Where is pixel_parser.cc?

    Where is pixel_parser.cc?

    When I use make -j4 to compile the program , a source code called 'pixel_parser.cc' has missed. I wonder where could I find this file, or wasI just did something wrong ?

    opened by fCorleone 2
  • Missing libgflags.pc on ubuntu 1604

    Missing libgflags.pc on ubuntu 1604

    To build this on ubuntu 1604 the configure will fail to find libgflags.pc which was missing from ubuntu. I added it manually to /usr/lib/x86_64-linux-gnu/pkgconfig/libgflags.pc with content like:

    Name: gflags
    Version: 2.0
    Description: A commandline flags library that allows for distributed flags
    URL: http://code.google.com/p/gflags
    Libs: -L${libdir} -lgflags
    Libs.private: -pthread -lpthread
    Cflags: -I${includedir}`
    opened by laoshaw 2
  • could not find  ft2build.h

    could not find ft2build.h

    On ubuntu 16.04 x86 I got : src/font.cc:6:22: fatal error: ft2build.h: No such file or directory

    I manually added -I /usr/include/freetype2 to get it compiled, something configure script did not get the include path right.

    opened by laoshaw 2
  • Alias the `sig_t` type to `sighandler_t` on Macs

    Alias the `sig_t` type to `sighandler_t` on Macs

    … apparently the Apple/BSD signal.h interface is exactly the same as what’s on Linux, except for this. The codebase as it stands, on master at HEAD, errors out during make like so:

    asio-otus:hiptext[master]$ make
    c++ -g -O3 -std=c++11 -Wall -Wextra -fno-exceptions -fno-rtti -MD  -march=native -c -o hiptext.o hiptext.cc
    c++ -g -O3 -std=c++11 -Wall -Wextra -fno-exceptions -fno-rtti -MD  -march=native -c -o artiste.o artiste.cc
    artiste.cc:165:3: error: unknown type name 'sighandler_t'
      sighandler_t old_handler = signal(SIGINT, OnCtrlC);
    1 error generated.
    make: *** [artiste.o] Error 1

    … but if I include the one alias per the PR, hiptext builds OK (with both Apple Clang 6.2 something and also LLVM Clang, somewhat recent HEAD from the 3.7 branch) and but then everything runs completely as advertised in every way thereafter:

    screen shot 2015-08-08 at 12 19 33 pm


    opened by fish2000 2
  • Fix signal handler

    Fix signal handler

    opened by elfring 2
  • korean chinese

    korean chinese

    Thank you for the resources I would like to ask how are they based on our de based on the English or are they converting the letters into English characters or ask characters I have tried to run it and I didn't understand which comments that I should look on it seems that you have committed something four months ago is it related with four years ago as well thank you so much

    opened by esthicodes 0
  • Update this please

    Update this please

    Hi there, there are some changes in ffmpeg and so the interface call signatures have been changed. Update this please, so we can all enjoy the ascii goodness

    opened by muziker 10
  • fails if not called from terminal

    fails if not called from terminal

    Even if you specify -width and -height, it tries calling ioctl TIOCGWINSZ, fails and crashes. ┐(´д`)┌

    Ran into this trying to use hiptext as an image preview in ranger.

    opened by Rouji 0
  • Why pixel_parse.cc is only in the archive ?

    Why pixel_parse.cc is only in the archive ?

    Hi, pixel_parse.cc is not in the repo. And it's very weird :

    $ wc pixel_parse.cc -l 17970

    $ grep goto pixel_parse.cc | wc -l 7592

    7592 GOTO !!! It's just insane ^^.

    opened by trent30 1
  • build error in ffmpeg 4.0

    build error in ffmpeg 4.0

    error occur in ffmpeg 4.0

    src/movie.cc:70:38: error: use of undeclared identifier 'PIX_FMT_RGB24'; did you mean 'AV_PIX_FMT_RGB24'
    src/movie.cc:94:5: warning: 'av_free_packet' is deprecated
    src/movie.cc:65:22: error: use of undeclared identifier 'avcodec_alloc_frame'

    send pull requests https://github.com/jart/hiptext/pull/52 but Travis CI refused because of using the earlier ffmpeg

    opened by citrus-lemon 1
Justine Tunney
Justine Tunney
Phan Sang 17 Dec 29, 2022
An optimized "RTOS" (more than HAL but less than RTOS) for ROV controling and getting sensor data

Nitori-ROV-OS 一个专门为水下机器人(ROV、AUV)进行优化的实时操作系统,暂命名为 Nitori,中文名 荷取 可以通过修改硬件兼容层(Port)进行移植 预计最初版本支持stm32f407和stm32h750,并在实验室目前的水下机器人中进行部署 系统分为四层,六个主要组件: 硬件

Doublues_G 2 Jan 10, 2022
Raw HID keyboard forwarder to turn the Pi 400 into a USB keyboard

Raspberry Pi 400 as a USB HID Keyboard Hook your Pi 400 up to your PC somehow, using a USB Type-C cable into the power port. Anker make good ones- I u

Philip Howard 182 Dec 12, 2022
Turn 2 esp32 boards into pixhawk telemetry for use with Ardupilot/Ardurover Mission Planner.

RoverLink Turn 2 esp32 boards into pixhawk telemetry for use with Ardupilot/Ardurover Mission Planner I used to use these cheap Chinese 900mhz Pixhawk

Jeffrey Berezin 3 Dec 9, 2022
Turn your ESP32 into a easy to use micro web-server allowing to interact with any GPIO by simple http(s) calls.

WebhooksTriggeredESP32WiFi Turn your ESP32 into an easy to use and manage wireless micro web-server allowing it to process reliably and asynchronouly

JayDeLux 3 Nov 24, 2022
To turn on and off the pump, most people use a manual switch.

To turn on and off the pump, most people use a manual switch. As a result, people forget to switch off the pump from time to time, resulting in water overflow. They may forget to switch on the motor at times, resulting in a water problem later on. It also wastes a lot of electricity. To solve this problem, we need a smart device to control the pump.

Md. Asad Chowdhury Dipu 1 Aug 20, 2022
Typewriter Effect with Rich Text + *Correct* Text Wrapping

Typewriter Effect with Rich Text + Correct Text Wrapping I've spent way too long getting this right. This is meant as a base class for a UMG dialogue

Sam Bloomberg 30 Nov 29, 2022
Text - A spicy text library for C++ that has the explicit goal of enabling the entire ecosystem to share in proper forward progress towards a bright Unicode future.

ztd.text Because if text works well in two of the most popular systems programming languages, the entire world over can start to benefit properly. Thi

Shepherd's Oasis 228 Dec 25, 2022
A better hexdump

huxdemp (aka hxd) huxdemp is an advanced version of the venerable hexdump that uses colors, bolding, and other terminal formatting to distinguish betw

LPTSTR 59 Dec 17, 2022
Quick fix to iphone usb tethering with ios14 or higher for Linux kernel lower than 5.10.4

Quick fix to Linux Iphone USB tethering with IOS 14 or higher (Tested with ubuntu 18.04, kernel 5.4.0-65, if you fail in the build, please download yo

null 24 Sep 18, 2022
The Pizza Compass will determine your location and direct you to the nearest pizza place. It’s like a regular compass, but better!

Pizza_Compass A Particle project named Pizza_Compass Welcome to your project! Every new Particle project is composed of 3 important elements that you'

Joe Grand 68 Aug 16, 2022
A Minimal Web Browser with Built-in Adblocker in Less Than 100 Lines of Code

A Minimal QtWebEngine Web Browser with Adblocker How Does It Work This is a minimal network filter implementation using QWebEngineUrlRequestIntercepto

Penk Chen 19 Jul 23, 2022
Thread Stack Spoofing - PoC for an advanced In-Memory evasion technique allowing to better hide injected shellcode's memory allocation from scanners and analysts.

Thread Stack Spoofing PoC A PoC implementation for an advanced in-memory evasion technique that spoofs Thread Call Stack. This technique allows to byp

Mariusz B. 761 Jan 9, 2023
Small and dirty header-only library that supports user input with some more advanced features than in the standard lib.

dirty-term Small and dirty header-only library that supports user input with some more advanced features than in the standard lib. This small, lightwe

null 3 Apr 24, 2022
T-HYDRA is a modified version of original thc-hydra for better use inside Termux .

T-HYDRA is a modified version of original thc-hydra for better use inside Termux . Earlier , hydra pakage had been with Termux repositories. Then afte

Devil Master 55 Jan 7, 2023
Stock exchange simulator made in Swing using Java with logic backend in C++ giving it faster load time and better data control

StockSimulator Stock exchange simulator made in Swing using Java with logic backend in C++ giving it faster load time and better data control Features

Dušan Todorović 0 Mar 1, 2022
This is an upgrade to the initial TerminalOS source, supporting real hardware other than just QEMU, using GRUB as a bootloader instead of the crappy one i wrote

Terminal OS Author: Maheswaran Date: 20th Nov 2021 PROGRESS Multiboot compilance achieved VGA driver from complete with print_hex, print_dec, printf f

Maheswaran Parameswaran 1 Nov 28, 2021
Visual-inertial-wheel fusion odometry, better performance in scenes with drastic changes in light

VIW-Fusion An visual-inertial-wheel fusion odometry VIW-Fusion is an optimization-based viusla-inertial-wheel fusion odometry, which is developed as a

庄庭达 261 Dec 30, 2022
Arbitrary Precision provides C++ long integer types that behave as basic integer types. This library aims to be intuitive and versatile in usage, rather than fast.

Arbitrary Precision (AP) Cross-platform and cross-standard header-only arbitrary precision arithmetic library. Currently it offers integer types that

null 17 Sep 28, 2022