https://github.com/geo-mena/pixii
🎨 Convert images, video to ascii!
https://github.com/geo-mena/pixii
markdown shell zig
Last synced: 2 months ago
JSON representation
🎨 Convert images, video to ascii!
- Host: GitHub
- URL: https://github.com/geo-mena/pixii
- Owner: geo-mena
- License: mit
- Created: 2025-06-22T19:46:20.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-22T20:03:16.000Z (about 1 year ago)
- Last Synced: 2025-06-22T20:37:10.053Z (about 1 year ago)
- Topics: markdown, shell, zig
- Language: Zig
- Homepage:
- Size: 0 Bytes
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- License: LICENSE
Awesome Lists containing this project
README
pixii - convert images & video to ASCII art
A high-performance CLI engine built entirely in Zig.
## Architecture Overview
pixii is designed as a modular pipeline that decomposes media processing into four specialized internal libraries, each with a single well-defined responsibility:
```mermaid
flowchart TB
CLI["main.zig — CLI Dispatcher"] -- image input --> IMG["libpixiiimg — Image Pipeline"]
CLI -- video input --> AV["libpixiiav — Video Pipeline"]
IMG --> CORE["libpixii — Core Engine"] & TERM["libpixiiterm — Terminal Renderer"]
AV --> CORE & TERM & FFMPEG["av — FFmpeg Bindings"]
CORE --> STB["stb — Image I/O"] & BMP["bitmap — 8x8 Font Rasterization"]
```
- **libpixii** serves as the computational core, implementing Difference-of-Gaussians edge detection, Floyd-Steinberg dithering, histogram-based auto-contrast, Gaussian blur, and the brightness-to-character mapping engine.
- **libpixiiimg** orchestrates the image processing flow: loading via STB, scaling, ASCII generation, and output encoding to PNG or plain text.
- **libpixiiav** manages video decoding and encoding through FFmpeg, employing a multithreaded producer-consumer architecture with a thread-safe circular frame buffer for real-time terminal streaming.
- **libpixiiterm** handles ANSI escape sequences for true-color rendering, cursor management, and adaptive terminal sizing.
---
## Installation
### Homebrew
```bash
brew tap geo-mena/pixii
brew install pixii
```
### Build from Source
Requires **Zig 0.14.0** and FFmpeg development libraries.
Platform-specific dependencies
**Linux:**
```bash
sudo apt-get install libavutil-dev libavformat-dev libavcodec-dev libswscale-dev libswresample-dev pkg-config
```
**macOS:**
```bash
brew install ffmpeg pkgconf
```
**Windows:**
```bash
choco install ffmpeg-shared
```
```bash
zig build -Doptimize=ReleaseFast
```
The compiled binary will be located at `./zig-out/bin/pixii`. For direct execution without a separate install step:
```bash
zig build run -Doptimize=ReleaseFast -- [options]
```
---
## Usage
```bash
pixii -i [options]
```
When the `-o` flag is omitted, pixii renders directly to the terminal. The output format is inferred from the file extension: `.txt` produces plain text, video extensions produce encoded video, and all other extensions produce a PNG image.
### Core Options
| Flag | Description | Default |
|------|-------------|---------|
| `-i, --input ` | Input media file, accepts local paths and URLs | **Required** |
| `-o, --output ` | Output file path | Terminal stdout |
| `-c, --color` | Enable true-color ASCII rendering | Disabled |
| `-n, --invert_color` | Invert brightness-to-character mapping | Disabled |
| `-s, --scale ` | Resize factor applied before conversion | `1.0` |
| `-a, --auto_adjust` | Histogram-based auto brightness and contrast | Disabled |
| `-b, --brightness_boost ` | Manual brightness multiplier | `1.0` |
| `-e, --detect_edges` | Enable Difference-of-Gaussians edge detection | Disabled |
| `--stretched` | Fit output to terminal dimensions | Disabled |
### Character Set Configuration
| Flag | Description | Default |
|------|-------------|---------|
| `--symbols ` | Preset character set: `ascii` or `block` | `ascii` |
| `--ascii_chars ` | Custom character mapping string | ` .:-=+*%@#` |
| `--full_characters` | Use the complete 70-character spectrum | Disabled |
| `--disable_sort` | Prevent automatic sorting of characters by visual density | Disabled |
| `--block_size ` | Processing block size in pixels | `8` |
### Edge Detection & Dithering
| Flag | Description | Default |
|------|-------------|---------|
| `--sigma1 ` | First Gaussian sigma for DoG filter | `0.5` |
| `--sigma2 ` | Second Gaussian sigma for DoG filter | `1.0` |
| `--threshold_disabled` | Disable edge magnitude threshold | Enabled |
| `-d, --dither floydstein` | Apply Floyd-Steinberg error diffusion | Disabled |
### Video-Specific Options
| Flag | Description | Default |
|------|-------------|---------|
| `--codec ` | Encoder codec, e.g. `libx264`, `hevc_videotoolbox` | Auto-detected |
| `--keep_audio` | Preserve audio stream from input | Disabled |
| `-f, --frame_rate ` | Target output frame rate | Matches input |
| `--fg ` | Foreground color override | `#d36a6f` |
| `--bg ` | Background color override | `#15091b` |
---
## Examples
### Image Processing
Generate a basic ASCII image:
```bash
pixii -i input.jpg -o output.png
```
Export as plain text:
```bash
pixii -i input.jpg -o output.txt
```
Enable color with edge detection and a custom scale factor:
```bash
pixii -i input.jpeg -o output.png -s 4 -e -c
```
Render directly in the terminal with brightness adjustment:
```bash
pixii -i input.png -e -c -b 1.5
```
### Video Processing
Encode an ASCII video preserving audio:
```bash
pixii -i video.mp4 -o ascii.mp4 --codec hevc_nvenc --keep_audio
```
Stream to terminal, stretched to fit the window:
```bash
pixii -i video.mp4 --stretched -c
```
Pass custom FFmpeg encoder parameters via positional arguments:
```bash
pixii -i video.mp4 -o ascii.mp4 -c --codec libx264 --keep_audio -- -preset fast -crf 20
```
---
## Supported Formats
**Image input:** BMP, GIF, JPEG, PNG, TIFF, WebP, ICO
**Video input:** MP4, AVI, MOV, WebM, MPEG, OGG, 3GP, 3G2, MPEG-TS
**Output:** PNG, TXT, MP4, and any format supported by the installed FFmpeg encoders
---
## Platform Compatibility
| Platform | Architecture | Status |
|----------|-------------|--------|
| macOS | ARM64, x86_64 | Supported |
| Linux | x86_64, ARM64 | Supported |
| Windows | x86_64 | Build from source |
---
## License
Released under the [MIT License](LICENSE).