bbcat

Dependency-free terminal viewer for CP437 ANSI and ansimation, DarkDraw DDW, DIZ, ADF, RIPscrip, and XBin art. It writes colored UTF-8 by default, with optional Kitty graphics and PNG output.

Browse and download BBS art packs at 16colo.rs.

Install

cargo install bbcat

To build from source, run cargo build --release.

Usage

bbcat [OPTIONS] [FILE]...

Pass one or more files, use - for standard input, or omit the filename to read standard input. Use -- before a filename that begins with -.

bbcat art.ans FILE_ID.DIZ
bbcat < art.ans
bbcat --kitty scene.xb
bbcat --output preview.png art.adf
bbcat --output - art.ans > preview.png
bbcat --2x --kitty art.ans
bbcat --sauce art.ans
bbcat --baud 4x animation.ans

Output modes

Kitty mode requires terminal stdout and a terminal that answers bbcat's Kitty graphics protocol probe. Kitty and Ghostty are supported on Linux and macOS, along with iTerm2 on macOS. Long images are emitted in strips so they remain available in terminal scrollback. Add --fit to scale the complete image to the terminal width instead of cropping. If that would make the image shorter than one terminal row, bbcat reports the minimum required terminal width.

PNG mode requires exactly one input file. Use --output - to pipe or redirect the PNG from standard output. PNG mode cannot be combined with --kitty, --slow, --delay, or --baud.

UTF-8 output is intended for character art using the standard CP437 glyph set. Use Kitty or PNG output for RIPscrip, XBin 512-character fonts, or artwork whose embedded bitmap font must be reproduced exactly.

Animation

bbcat recognizes ansimation from repeated ANSI screen rewrites and DarkDraw DDW animation frames, then plays them automatically when standard output is a terminal. Playback defaults to 1X. Use --baud RATE to choose an animation frame rate or set the row-reveal speed for static ANSI and text:

bbcat --baud 2400 animation.ans
bbcat --baud 57600 animation.ans
bbcat --baud 2x animation.ans
bbcat --baud 4x animation.ans

2400, 9600, 14400, 28800, 38400, 57600, 115200 (1X), 2X (230400), and 4X (460800) are suggested familiar rates; run bbcat --baud to print the list. Any positive numeric rate is accepted, as is an Nx multiplier of 115200 (for example, 3X is 345600). Animated playback uses each frame's source byte count to determine how long it remains visible. DDW uses its source-defined per-frame duration at 1X, scaled proportionally by the selected rate. Static art uses the same smooth row reveal as --slow: 1X is 25 milliseconds per row, with lower rates slower and higher rates faster. Terminals with synchronized-output support reveal each redraw atomically to avoid visible row-by-row tearing. Animation playback preserves CP437 text and source-defined 16-color, 256-color, and true-color SGR sequences. An animation that explicitly homes to the terminal's top-left clears the canvas before playback; relative animations leave the terminal intact. Both retain their final frame and return the shell prompt below it.

Redirected UTF-8 output and Kitty or PNG output render the last visible state instead of replaying the animation. Supplying --baud explicitly replays an animation or uses the static row reveal even when UTF-8 output is redirected. --baud cannot be combined with Kitty, PNG, --slow, or --delay.

Slow mode

bbcat --slow art.ans
bbcat --delay 50 art.ans
bbcat --kitty --slow art.ans

--slow reveals one character row at a time with a 25 millisecond delay. --delay MS enables slow mode with a custom delay from 1 through 10,000 milliseconds. Both UTF-8 and Kitty modes flush each row before waiting; Kitty mode automatically uses one image strip per character row.

Slow mode is not supported with ANSI animation, PNG output, or RIPscrip raster graphics. Use --baud for baud-paced ANSI/text output. In Kitty slow mode, --chunk-lines has no effect.

SAUCE metadata

Use --sauce to show an artwork's available SAUCE title, author, group, and creation date as a compact gallery-style caption below the rendered art. Files without descriptive SAUCE metadata render without a caption. The option works with UTF-8 and Kitty output, including multiple input files, but cannot be combined with PNG output.

2x scaling

bbcat --2x --kitty scene.xb
bbcat --kitty --fit wide.ans
bbcat --2x --output large.png drawing.rip
bbcat --2x --kitty --slow art.ans

--2x doubles both graphical output dimensions. Kitty mode crops the doubled bitmap at the terminal width unless --fit is present; PNG mode writes an image with twice the width and height. It works with every supported input format and can be combined with Kitty slow mode. Slow-mode delays remain per original artwork row.

Scaling is intentionally unavailable in UTF-8 mode: repeating text characters would change strings and distort line art. Use --kitty or --output FILE with --2x.

When UTF-8 output goes directly to a terminal, rows wider than the terminal are cropped to its current column count. Redirected or piped UTF-8 output preserves the full artwork width. Kitty crops at terminal width by default; --fit scales the complete image down when at least one terminal row remains. PNG output always retains its full dimensions.

Formats

• ANSI and plain CP437 text, including .ANS, .DIZ, .ASC, .NFO, .MEM, and .TXT. ANSI cursor movement, erasing, standard and bright colors, inverse video, blink/iCE colors, wrapping, SAUCE dimensions, and baud-paced ansimation are handled. Ansimation playback also preserves 256-color and true-color SGR sequences.
• DarkDraw (.DDW) UTF-8 JSON Lines text art and animation. Base and frame-specific objects are painted in source order; reusable group references are expanded recursively at their positioned frame. Each DDW frame uses its declared duration. A Dimensions metadata record is used when present; otherwise bbcat infers the canvas from the positioned text. Terminal playback preserves Unicode glyphs and 16- and 256-color styles; Kitty and PNG output show the final frame with a CP437/VGA approximation where necessary.
• XBin (.XB) with embedded palettes, 8- or 16-color backgrounds, embedded fonts up to 32 pixels high, 256- and 512-character modes, and XBin RLE.
• ArtWorx Data Format (.ADF) version 1 with its embedded palette and 8x16 font. ADF is fixed at 80 columns.
• RIPscrip (.RIP) level-one vector graphics, including its bitmap and proportional BGI stroke fonts. RIPscrip is rendered to a 640x350 canvas and requires Kitty or PNG output.

SAUCE metadata is used for content length, canvas dimensions, iCE color mode, and named IBM VGA50, Amiga MicroKnight, Amiga Topaz 2+, and Empathy bitmap fonts when present. Kitty and PNG output reproduce their exact glyph shapes; UTF-8 output remains a terminal-font approximation. A DOS EOF marker terminates plain ANSI/text input.

Common raster image inputs such as PNG, GIF, JPEG, WebP, TIFF, ICO, BMP, and QOI are rejected by content with an explanatory error instead of being parsed as character art. Malformed, truncated, oversized, or unsupported BBS inputs also produce a non-zero exit status and a filename-scoped error. With multiple inputs, bbcat reports a rejected file and continues with the remaining files.

Options

bbcat has no runtime dependencies and does not require a particular Rust version beyond what is needed to compile the current Rust edition.