✰ArtSCII✰

A workspace with the shared foundation crate, a reusable image-conversion crate and a video conversion crate, a CLI binary, and a web app built on WASM.

Table of Contents

• Features
• Workspace
• Using the crate
• Installation
  • cargo-binstall
  • Install script
  • Prebuilt binaries
  • Nix
  • Cargo
• Usage
  • Options
  • Example Commands
  • Dithering Algorithms
• Building from Source
  • Dependencies
• License

Features

• Multiple dithering algorithms: Floyd-Steinberg, Atkinson, and Riemersma
• Color support: ANSI colors for terminal and text output, RGB for HTML output
• Multiple output formats: Terminal, plain text, colorized text, styled HTML, GIF, and MP4
• Video to ASCII animation: Convert video to animated ASCII in terminal, GIF, or MP4
• Image adjustments: Resolution, contrast, and brightness controls
• Wide format support: PNG, JPG, GIF, BMP, WebP, and more
• Browser-based: Convert images to ASCII art entirely client-side via WebAssembly

Workspace

The project is organized as a Cargo workspace with the following crates:

The three library crates (core, img, video) are designed to be usable from other Rust projects. See each crate's README for details.

Using the crate

Use artscii-img from another Rust project as a local path dependency:

1cargo add --git https://github.com/4ster-light/artscii artscii-img2# If you want to lock it to a branch, tag or commit:3cargo add --git https://github.com/4ster-light/artscii --branch main artscii-img4cargo add --git https://github.com/4ster-light/artscii --tag v1.1.0 artscii-img5cargo add --git https://github.com/4ster-light/artscii --rev <commit-sha> artscii-img

Or, in Cargo.toml:

1[dependencies]2artscii-img = { git = "https://github.com/4ster-light/artscii", branch = "main" }

Same applies for artscii-core if you want to use the shared types and config, or artscii-video.

The CLI crate builds the artscii binary.

Installation

cargo-binstall

cargo-binstall installs a prebuilt binary from GitHub Releases. The crate is not published to crates.io, so point binstall at the repository:

1# Install cargo-binstall once (see its README for a prebuilt installer)2cargo install cargo-binstall34# Install ArtSCII5cargo binstall --git https://github.com/4ster-light/artscii artscii-cli

[!WARNING] On macOS and Windows this downloads the prebuilt binary. On Linux the release is a self-contained bundle (binary plus ffmpeg/alsa libraries) that binstall cannot unpack into place, so it falls back to building from source; use the install script if you want the bundled binary.

Install script

Linux and macOS, no Rust toolchain required:

1curl -fsSL https://raw.githubusercontent.com/4ster-light/artscii/main/install.sh | sh

Windows (PowerShell):

1irm https://raw.githubusercontent.com/4ster-light/artscii/main/install.ps1 | iex

The script installs into ~/.local/bin (%LOCALAPPDATA%\Programs\artscii on Windows). Override the destination with ARTSCII_INSTALL_DIR (or $env:ARTSCII_INSTALL_DIR), and select a specific release with ARTSCII_VERSION (for example v2.0.0).

Prebuilt binaries

Download the asset for your platform from the latest release:

Each asset ships with a matching .sha256 checksum, plus an aggregated SHA256SUMS file. After downloading:

1# Linux (tar.gz with bundled libraries)2tar xzf artscii-linux-x86_64.tar.gz3./artscii --help45# macOS / Windows6chmod +x artscii-macos-x86_647./artscii-macos-x86_64

[!NOTE] Linux tarballs bundle required ffmpeg/alsa libraries — no extra packages needed at runtime. macOS and Windows include video support natively.

Nix

Run without installing:

1nix run github:4ster-light/artscii -- image.jpg

Install into your profile:

1nix profile add github:4ster-light/artscii

The flake also exposes overlays.default, nixosModules.default, and homeManagerModules.default for declarative installs.

NixOS:

1{2  inputs.artscii.url = "github:4ster-light/artscii";34  outputs =5    { nixpkgs, artscii, ... }:6    {7      nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {8        modules = [9          artscii.nixosModules.default10          { programs.artscii.enable = true; }11        ];12      };13    };14}

home-manager:

1{2  inputs.artscii.url = "github:4ster-light/artscii";34  outputs =5    { home-manager, artscii, ... }:6    {7      homeConfigurations."user@host" = home-manager.lib.homeManagerConfiguration {8        modules = [9          artscii.homeManagerModules.default10          { programs.artscii.enable = true; }11        ];12      };13    };14}

Without the modules you can add the package (or the overlay) directly:

1home.packages = [ inputs.artscii.packages.${pkgs.system}.artscii ];23# ...or use the overlay:4# nixpkgs.overlays = [ inputs.artscii.overlays.default ];5# home.packages = [ pkgs.artscii ];

Cargo

Install the CLI from source (the crate builds the artscii binary):

1cargo install --locked --git https://github.com/4ster-light/artscii artscii-cli

The video feature is enabled by default. Pass --no-default-features to skip ffmpeg/audio when you only need image conversion:

1cargo install --locked --no-default-features \2  --git https://github.com/4ster-light/artscii artscii-cli

Usage

Options

Example Commands

1# Basic usage - display in terminal2artscii image.jpg34# With colors5artscii image.jpg -c67# Save as plain text8artscii image.jpg -o output.txt910# Save ANSI-colored text11artscii image.jpg -c -o output.txt1213# Save as styled HTML with colors14artscii image.jpg -o output.html -c1516# Higher resolution with Atkinson dithering17artscii image.jpg -r 0.5 -d atkinson1819# Adjust contrast and brightness20artscii image.jpg --contrast 1.5 -b 0.82122# Invert characters (for light backgrounds)23artscii image.jpg -i2425# Quiet mode (only output the art)26artscii image.jpg -q2728# Play video as ASCII animation in terminal29artscii video.mp4 --video3031# Play video in terminal with colors32artscii video.mp4 --video -c3334# Export video as animated GIF (colored, higher resolution)35artscii video.mp4 --video --video-format gif -c -r 0.5 -o output.gif3637# Export video as MP4 (colored, with original audio)38artscii video.mp4 --video --video-format mp4 -c --preserve-audio -o output.mp4

And what I think is the best result for the example image in this repo:

1artscii image.jpg -c -b 1.5 -r 0.26 -d atkinson -o img.html

Dithering Algorithms

• none: No dithering (default)
• floyd-steinberg: Classic error-diffusion dithering
• atkinson: Sharper dithering (preserves more contrast)
• riemersma: Space-filling curve dithering

Building from Source

Building from source requires system libraries for video and audio support.

Dependencies

1# CLI binary at ./result/bin/artscii2nix build .#artscii34# Static WASM site at ./result5nix build .#artscii-web67# Dev shell with the pinned Rust toolchain, trunk, ...8nix develop910# fmt + clippy + tests + docs + web checks11nix flake check1213# Nix file formatting14nix fmt -- --ci

The Rust toolchain is pinned in rust-toolchain.toml and shared by the dev shell, the Nix builds, and CI. CI (.github/workflows/ci.yml) runs the same nix flake check plus nix fmt -- --ci on every pull request, so the checks above are exactly what has to pass. If you are already inside nix develop, the usual cargo commands work as-is.

Without Nix, install the dependencies listed above, then:

1cargo build --release

License

MIT