Convert Video to ASCII Art Using FFmpeg CACA

This guide demonstrates how to convert and render standard video files into animated ASCII art using FFmpeg's integrated caca (Color AsCii Art) output device. You will learn the requirements for libcaca support, the exact commands needed to play ASCII video directly in your terminal, and how to export or adjust the ASCII visual presentation.

Prerequisites

To use the caca output device, your FFmpeg build must be compiled with libcaca support. You can verify that your FFmpeg installation includes the device by running:

ffmpeg -devices

Look for caca under the output devices list. If it is missing, you must install libcaca (e.g., sudo apt install libcaca-dev on Debian/Ubuntu) and compile FFmpeg with the --enable-libcaca configuration flag, or use a precompiled binary package that includes it.

Real-Time ASCII Playback in the Terminal

To play a video file as ASCII art directly in the terminal, specify caca as the output format using the -f flag and direct the output to standard output (-):

ffmpeg -i input.mp4 -pix_fmt rgb24 -f caca -

Explanation of Arguments:

  • -i input.mp4: Specifies the input video file.
  • -pix_fmt rgb24: Sets the pixel format to 24-bit RGB, which is the native color format required by libcaca.
  • -f caca: Selects the libcaca output device.
  • -: Routes the output stream to the terminal console.

Controlling Resolution and Aspect Ratio

Terminal dimensions often distort video aspect ratios if left unmanaged. You can constrain the resolution to fit standard terminal sizes using FFmpeg's scale filter:

ffmpeg -i input.mp4 -vf "scale=80:40" -pix_fmt rgb24 -f caca -

Adjust the 80:40 value to match the column and row dimensions of your terminal window.

Customizing CACA Output via Environment Variables

The libcaca library is configured primarily through environment variables rather than direct FFmpeg command-line flags.

1. Change the Display Driver

You can specify which backend driver libcaca uses by setting CACA_DRIVER. Available options include ncurses, slang, x11, raw, and default.

To force output inside an ncurses terminal:

CACA_DRIVER=ncurses ffmpeg -i input.mp4 -pix_fmt rgb24 -f caca -

2. Exporting to Formats like HTML

You can record or export the ASCII playback into animated HTML by setting the driver to html and redirecting output to a file:

CACA_DRIVER=html ffmpeg -i input.mp4 -pix_fmt rgb24 -f caca output.html

3. Adjusting Dithering

Change how color gradients are translated into ASCII characters by setting the CACA_DITHER variable:

CACA_DITHER=fser ffmpeg -i input.mp4 -pix_fmt rgb24 -f caca -

Common dithering algorithms include:

  • none: Disables dithering.
  • ordered2, ordered4, ordered8: Bayer ordered dithering matrices.
  • fser: Floyd-Steinberg error diffusion algorithm (best for smooth color transitions).