Chafa Digital ASCII Converter

A web application for converting images to ANSI/ASCII art using Chafa, with a modern Material Design 3 interface. Supports color modes, symbol sets, font scaling, and more.

---

Features

• Image Upload: Convert images to ANSI/ASCII art in your browser.
• Chafa Integration: Uses the powerful Chafa CLI for conversion.
• Material Design 3 UI: Responsive, accessible, and themed with Material Web Components.
• Customizable Output:
  • Select character sets (ASCII, Unicode, Braille, etc.)
  • Choose color modes (full color, 256, 16, grayscale, monochrome, none)
  • Set output size (common terminal sizes)
  • Foreground-only mode
  • Font scaling for output preview
• Client & Server File Size Limits: Prevents large uploads (default 2MB).
• Robust Error Handling: Detects offline/server issues and invalid inputs.

---

Demo

---

Installation

Prerequisites

• Python 3.7+ The backend is a simple Flask server.
• Chafa CLI The Chafa binary must be installed and available in your system PATH.
• pip For installing Python dependencies.

1. Clone the Repository

git clone https://github.com/boomboompower/chafa-frontend.git
cd chafa-frontend

2. Install Python Dependencies

pip install flask

3. Install Chafa

On Ubuntu/Debian

sudo apt-get install chafa

On macOS (Homebrew)

brew install chafa

Or build from source

---

Usage

1. Start the Server

python server.py

By default, the server runs on http://0.0.0.0:5000.

2. Open the Web App

Visit http://localhost:5000 in your browser.

---

How it Works

• The frontend is a single-page app using Material Web Components for a modern look and feel.
• When you select an image and click Convert, the image and your chosen options are sent to the Flask backend.
• The backend validates all inputs, saves the image temporarily, and runs the Chafa CLI with your options.
• The ANSI/ASCII output is sent back to the browser, where it is rendered and styled using ansi_up.

---

Configuration

• Temporary Upload Directory: By default, uploaded files are saved to /tmp. You may change this path in server.py if needed.

• File Size Limit: The default maximum upload size is 2MB (enforced on both client and server).

• Allowed Options: Only options present in the UI are accepted by the backend for security.

---

Project Structure

chafa-frontend/
├── static/
│   ├── css/
│   │   └── app.css        # Main CSS, themed for Material 3
│   ├── js/
│   │   └── app.js         # Main frontend logic
│   └── index.html         # Main HTML page
├── server.py              # Flask backend and Chafa integration
└── README.md              # This documentation

---

Security Notes

• All user inputs are validated and sanitized on the server.
• Only allowed Chafa options are passed to the CLI.
• Uploaded files are deleted after processing.
• Output is parsed and rendered safely in the browser using ansi_up.

---

Customization

• Add More Chafa Options: You can expose more Chafa CLI options by adding them to the frontend and whitelisting them in server.py.
• Change Theme: Edit /static/css/app.css and the Material variables in :root for a different look.
• Increase File Size Limit: Change MAX_FILE_SIZE in server.py and the corresponding value in the frontend JS.

---

License

MIT License

---

Credits

• Chafa by Hans Petter Jansson
• Material Web Components
• ansi_up

---