https://github.com/cod-e-codes/ascii-colorizer
Render any image or video as full-color ASCII art in your terminal.
https://github.com/cod-e-codes/ascii-colorizer
ansi ascii ascii-art cli image-processing python terminal truecolor video-processing
Last synced: 23 days ago
JSON representation
Render any image or video as full-color ASCII art in your terminal.
- Host: GitHub
- URL: https://github.com/cod-e-codes/ascii-colorizer
- Owner: Cod-e-Codes
- License: mit
- Created: 2025-07-25T00:05:38.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2026-05-01T20:05:25.000Z (about 2 months ago)
- Last Synced: 2026-05-16T13:48:28.735Z (about 1 month ago)
- Topics: ansi, ascii, ascii-art, cli, image-processing, python, terminal, truecolor, video-processing
- Language: Python
- Homepage: https://github.com/Cod-e-Codes/ascii-colorizer
- Size: 2.94 MB
- Stars: 14
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ascii-colorizer
Rust CLI that converts images and videos into colored ASCII art for terminal display.
## Requirements
- A terminal with ANSI color support (TrueColor recommended)
- [ffmpeg](https://ffmpeg.org/) and `ffprobe` on `PATH` for video input
## Install
### Prebuilt binaries (recommended)
Download the archive for your platform from [GitHub Releases](https://github.com/Cod-e-Codes/ascii-colorizer/releases), verify the SHA256 checksum, extract it, and place the binary on your `PATH`.
| Platform | Asset name pattern |
| --- | --- |
| Windows (x86_64) | `ascii-colorizer-x86_64-pc-windows-msvc.zip` |
| Linux (x86_64) | `ascii-colorizer-x86_64-unknown-linux-gnu.tar.gz` |
| Linux (ARM64) | `ascii-colorizer-aarch64-unknown-linux-gnu.tar.gz` |
| macOS (Intel) | `ascii-colorizer-x86_64-apple-darwin.tar.gz` |
| macOS (Apple Silicon) | `ascii-colorizer-aarch64-apple-darwin.tar.gz` |
Releases are published when a version tag is pushed (for example `v0.1.2`). See [latest release](https://github.com/Cod-e-Codes/ascii-colorizer/releases/latest).
### Install with Cargo
```bash
cargo install --git https://github.com/Cod-e-Codes/ascii-colorizer.git --tag v0.1.2 --locked
```
### Build from source
```bash
git clone https://github.com/Cod-e-Codes/ascii-colorizer.git
cd ascii-colorizer
cargo build --release
```
The binary is at `target/release/ascii-colorizer` (`.exe` on Windows).
## Usage
Image:
```bash
ascii-colorizer --file ./image.png
ascii-colorizer --file ./image.png --width 120 --detailed --color no-color
```
Video (live playback in terminal):
```bash
ascii-colorizer --file ./video.mp4 --type video --fps 12 --width 120 --color truecolor
```
Video (save to file):
```bash
ascii-colorizer --file ./video.mp4 --type video --fps 10 --save output.txt
```
Notes:
- Video output is streamed frame by frame to avoid loading all frames into memory.
- Saved video output uses a form feed separator between frames.
- Live playback runs in an alternate terminal screen and restores the previous screen on exit.
- Ctrl+C exits video playback cleanly and restores terminal state.
## CLI options
| Option | Description |
| --- | --- |
| `-f, --file ` | Input file path |
| `-w, --width ` | Output width in characters (default: `100`) |
| `--height ` | Optional max output height |
| `--detailed` | Use detailed character set |
| `--color ` | `truecolor` or `no-color` |
| `-s, --save ` | Write output to file |
| `--type ` | `auto`, `image`, or `video` |
| `--fps ` | Video frame rate (default: `12`) |
## Development
```bash
cargo fmt
cargo clippy --all-targets --all-features -- -D warnings
cargo test
cargo build --release
```
CI runs on every push and pull request to `main`. Pushing a `v*.*.*` tag builds release binaries and attaches them to a GitHub Release.
## Supported formats
**Images:** JPEG, PNG, BMP, GIF, TIFF, WebP (via the `image` crate)
**Videos:** MP4, MKV, MOV, AVI, WebM, FLV, M4V (decoded through ffmpeg)
## License
MIT. See [LICENSE](LICENSE).