cacaplay

cacaplay [options] file

-h
    Display a help message and exit.

-f
    Enable fullscreen mode for playback.

-r
    Output raw, unformatted frames without libcaca headers (useful for piping).

-x
    Disable playback and instead dump frames as C-arrays to standard output (developer-oriented).

-d
    Specify the display driver to use (e.g., 'ncurses', 'x11', 'sdl', 'raw'). Defaults to auto-detection.

-q
    Quiet mode; do not display anything (useful for benchmarking).

-b
    Do not display the background, drawing only the foreground elements.

-s x
    Set the output resolution or character grid size, e.g., '80x25'.

-S
    Set the font scaling factor for the output.

-c
    Set the character set to use for rendering (e.g., 'ascii', 'cp437', 'utf8').

-p
    Specify a particular playback plugin to use for decoding (e.g., 'ffmpeg', 'mplayer').

-v
    Enable verbose output, displaying more information during execution.

-V
    Display the version information for cacaplay and exit.

cacaplay is a command-line utility from the libcaca library, designed to play various multimedia files, including videos and animated GIFs, directly within your terminal as ASCII art. It leverages external decoding libraries like FFmpeg or MPlayer to interpret media formats, then renders the frames using characters, colors, and block elements supported by the terminal.

The primary purpose of cacaplay is to demonstrate the capabilities of libcaca in converting graphical content into a text-based representation. While not intended for high-fidelity playback, it offers a unique and nostalgic way to experience multimedia, turning your terminal into a retro display. It can handle a wide range of video and image formats, making it a versatile tool for both entertainment and showcasing the artistic potential of character-based graphics.

The performance and visual quality of cacaplay are highly dependent on the terminal emulator's capabilities, the input media's resolution, and the speed of your system. High-resolution videos or complex animations can lead to slow frame rates. It relies on external libraries (like FFmpeg or MPlayer) for decoding most common video formats; if these are not installed or libcaca was not compiled with their support, functionality may be limited. The output is inherently stylized and low-resolution, not suitable for detailed visual analysis.

cacaplay can play its native .caca animation files directly. For other multimedia formats (e.g., MP4, MKV, AVI, GIF, WebM), it typically relies on underlying video decoding libraries like FFmpeg or MPlayer. This means it can theoretically play any format that these robust libraries support, converting their visual content into ASCII or ANSI art for terminal display.

To play a video file named my_video.mp4 using cacaplay, you would simply execute:

cacaplay my_video.mp4

For a more controlled playback, you might specify the output size and character set:

cacaplay -s 120x40 -c utf8 my_video.mp4

cacaplay is a core utility of the libcaca library, which was primarily developed by Sam Hocevar starting around 2005. libcaca gained popularity for its whimsical yet technically impressive ability to render graphics, including video, as pure ASCII art in a terminal. It was conceived as an alternative to libaa (AAlib) and aimed to provide better color support and performance. cacaplay emerged as the main application demonstrating libcaca's video playback capabilities, showcasing the library's versatility in creative text-based graphical representations.

cacafire(1), cacademo(1), img2txt(1), mplayer(1), mpv(1)