🎨 ASCIIartify

Transform videos and images into stunning ASCII art with color themes, smooth animations, and YouTube support!

🎬 Demo

Original Video

ASCII Version

👆 Click to view the full ASCII animation (10 seconds, 300 frames)

Command used:

python run_asciiartify.py video "https://www.youtube.com/watch?v=oo8tfJ2jz_Y" \
  --quality 480p --width 120 --start 5 --end 15 \
  --contrast 2.0 --color retro -o output/demo.html

✨ Features

🎬 Video to ASCII - Convert any video file or YouTube URL
🎨 5 Color Themes - Matrix green, retro, cyan, rainbow, or classic
📺 Live Playback - Watch in your terminal with smooth animations
💾 Export Options - Save as HTML, text, or animated files
⚡ Fast & Efficient - Skip frames, adjust quality, optimize performance
🎯 Customizable - Width, contrast, FPS, character sets, and more

🚀 Quick Start

Install

git clone https://github.com/whyujjwal/asciiartify.git
cd asciiartify
pip install -e .

Basic Usage

# Convert a video
python run_asciiartify.py video movie.mp4 --play --color retro

# Convert YouTube video
python run_asciiartify.py video "https://youtu.be/dQw4w9WgXcQ" --play

# Convert an image
python run_asciiartify.py image photo.jpg --width 120

# Save as HTML animation
python run_asciiartify.py video clip.mp4 -o output.html

🎮 Examples

Terminal Playback

# Matrix-style with progress bar
python run_asciiartify.py video movie.mp4 --color green --width 100 --play

# High quality, full color
python run_asciiartify.py video movie.mp4 --color retro --width 150 --play

YouTube Videos

# Quick preview (fast)
python run_asciiartify.py video "https://youtu.be/VIDEO_ID" \
  --quality 360p --skip 2 --start 0 --end 10 --play

# High quality HTML
python run_asciiartify.py video "https://youtu.be/VIDEO_ID" \
  --quality 720p --width 150 -o animation.html

Save & Share

# Create shareable HTML animation
python run_asciiartify.py video clip.mp4 --width 120 -o share.html

# Custom character set
python run_asciiartify.py image photo.jpg --custom-chars "█▓▒░ "

� Documentation

Getting Started:

• 📘 Quick Start Guide - 5-minute setup
• 📋 Usage Guide - All commands & options
• 🎬 YouTube Guide - YouTube features
• 🎨 Terminal Guide - Color themes & tips

For Developers:

• 💻 Developer Guide - Architecture & API
• 🤝 Contributing - How to contribute
• 📚 Full Documentation - Complete docs index

💡 Use Cases

• 🎓 Education - Create unique presentations and demos
• 🎬 Content Creation - Generate retro-style video effects
• 🎮 Fun - Turn your favorite videos into ASCII art
• 🖼️ Art - Create ASCII artwork from images
• 💻 Terminal Rice - Impress your friends with terminal animations

🎨 Color Themes

Theme	Preview	Best For
none	█░▒▓	Classic ASCII
green	█░▒▓	Matrix style
retro	█░▒▓	High contrast
cyan	█░▒▓	Modern look
rainbow	█░▒▓	Fun effects

�️ Options

--width, -w          # Width in characters (default: 80)
--color              # Color theme: none, green, retro, cyan, rainbow
--quality            # YouTube quality: 144p-1080p (default: 720p)
--play               # Play in terminal
--skip               # Skip frames for faster processing
-o, --output         # Save to file
--format             # Output format: txt, html

See Usage Guide for complete options.

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md for details.

# Quick setup
git clone https://github.com/whyujjwal/asciiartify.git
cd asciiartify
pip install -e ".[dev]"
pytest

⚡ Performance Tips

Fast processing:

--width 60 --skip 3 --quality 360p

Best quality:

--width 180 --charset detailed --contrast 2.5

🐛 Troubleshooting

Issue	Solution
Import errors	Run pip install -e .
yt-dlp missing	Run pip install yt-dlp
Slow playback	Use --width 60 --skip 2
No colors	Try a modern terminal or --color none

More help: Troubleshooting Guide

� License

MIT License - see LICENSE file for details

🙏 Acknowledgments

Built with OpenCV, yt-dlp, Pillow, Click, and colorama

⭐ Star History

If you like this project, give it a star! ⭐

---

Made with ❤️ and ASCII art

GitHub • Documentation • Contributing • Issues

Core Components

video-to-ascii/
├── asciiartify/              # Main package
│   ├── core/                 # Core conversion logic
│   │   ├── video_processor.py    # Extract frames from video (OpenCV)
│   │   ├── ascii_converter.py    # Convert images to ASCII art
│   │   └── frame_manager.py      # Manage frame buffering (future)
│   ├── rendering/            # Output renderers
│   │   ├── terminal_renderer.py  # Display in terminal with animation
│   │   ├── file_renderer.py      # Save to text/HTML files
│   │   └── video_renderer.py     # Convert back to video format
│   ├── utils/                # Utility modules
│   │   ├── brightness_mapper.py  # Map brightness → ASCII chars
│   │   ├── image_processor.py    # Image preprocessing (resize, grayscale)
│   │   ├── color_mapper.py       # Color support (future)
│   │   └── config.py             # Configuration management
│   ├── cli/                  # Command-line interface
│   │   └── commands.py           # CLI commands and argument parsing
│   └── models/               # Data models
│       ├── frame.py              # Frame data structure
│       └── video_config.py       # Video configuration model
├── tests/                    # Unit tests
├── assets/                   # Character sets, fonts
├── examples/                 # Example scripts
└── output/                   # Default output directory

---

Setup Instructions

Prerequisites

• Python 3.9 or higher
• uv package manager (Install uv)

Installation Steps

# 1. Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh
# On Windows: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 2. Clone the repository
git clone <repository-url>
cd video-to-ascii

# 3. Create virtual environment with uv
uv venv

# 4. Activate virtual environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# 5. Install the project in editable mode with dev dependencies
uv pip install -e ".[dev]"

# 6. Verify installation
python -c "import asciiartify; print('Installation successful!')"

Why uv?

• 10-100x faster than pip for package installation
• Better dependency resolution
• Built-in virtual environment management
• Drop-in replacement for pip commands

Dependencies

Core Dependencies:

• opencv-python (4.8.0+) - Video processing and frame extraction
• numpy (1.24.0+) - Numerical operations on image data
• Pillow (10.0.0+) - Image manipulation and processing
• colorama (0.4.6+) - Cross-platform colored terminal output
• click (8.1.0+) - CLI framework
• tqdm (4.65.0+) - Progress bars

Dev Dependencies:

• pytest (7.4.0+) - Testing framework
• pytest-cov (4.1.0+) - Code coverage
• black (23.0.0+) - Code formatter

---

Current Implementation Status

✅ Completed Components

1. BrightnessMapper (asciiartify/utils/brightness_mapper.py)

Maps pixel brightness values (0-255) to ASCII characters.

Key Features:

• Configurable character sets
• Linear brightness-to-character mapping
• Support for custom character sets from files

Usage:

from asciiartify.utils.brightness_mapper import BrightnessMapper

mapper = BrightnessMapper(char_set="@%#*+=-:. ")
char = mapper.get_char(128)  # Returns middle brightness character

2. ImageProcessor (asciiartify/utils/image_processor.py)

Preprocesses images for ASCII conversion.

Key Features:

• Aspect ratio correction (characters are ~2x taller than wide)
• Grayscale conversion
• Contrast adjustment for better ASCII representation
• Returns numpy arrays of brightness values

Usage:

from asciiartify.utils.image_processor import ImageProcessor
from PIL import Image

processor = ImageProcessor(target_width=100)
image = Image.open('photo.jpg')
brightness_matrix = processor.process(image, contrast=1.5)

3. ASCIIConverter (asciiartify/core/ascii_converter.py)

Main conversion engine combining ImageProcessor and BrightnessMapper.

Key Features:

• Converts PIL Images to ASCII art (list of strings)
• File-to-ASCII conversion
• Print and save functionality

Usage:

from asciiartify.core.ascii_converter import ASCIIConverter

converter = ASCIIConverter(width=80, contrast=1.5)
ascii_lines = converter.file_to_ascii('image.jpg')
converter.print_ascii(ascii_lines)

---

How the Conversion Works

Step-by-Step Process

Video File
    ↓
[1] Extract Frame (OpenCV)
    ↓
PIL Image (RGB)
    ↓
[2] Resize (maintain aspect ratio × 0.5 for character shape)
    ↓
[3] Convert to Grayscale (L mode, 0-255 brightness)
    ↓
[4] Adjust Contrast (enhance features for ASCII)
    ↓
2D Brightness Matrix (NumPy array)
    ↓
[5] Map Each Brightness Value to ASCII Character
    ↓
List of ASCII Strings (one per line)
    ↓
[6] Render to Terminal / File / Video

Technical Details

Brightness to Character Mapping:

Brightness Range: 0 (black) ────────────────→ 255 (white)
Character Set:    @  %  #  *  +  =  -  :  .  (space)
                  ↑                              ↑
                dark                          light

Aspect Ratio Correction:

• Terminal characters are approximately 2:1 (height:width)
• When resizing, height = (original_height / original_width) × target_width / 2
• This prevents ASCII art from appearing stretched vertically

---

Testing

Run Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=asciiartify

# Run specific test file
pytest tests/test_ascii_converter.py

Debug Script

Use test_conversion.py to debug image conversion issues:

python test_conversion.py path/to/image.jpg

This will show step-by-step diagnostics of the conversion process.

---

Common Issues & Solutions

Issue 1: Import Errors

Problem: ModuleNotFoundError: No module named 'asciiartify'

Solution:

uv pip install -e .

Issue 2: All Same Characters

Problem: ASCII output is all spaces or all the same character

Solution: The character set might be inverted. Try:

mapper = BrightnessMapper(char_set="@%#*+=-:. ", invert=True)

Issue 3: OpenCV Not Found

Problem: ImportError: No module named 'cv2'

Solution:

uv pip install opencv-python

Issue 4: Distorted Output

Problem: ASCII art looks stretched

Solution: Adjust aspect ratio or width:

converter = ASCIIConverter(width=120)  # Try different widths

Issue 5: uv Command Not Found

Problem: bash: uv: command not found

Solution:

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Add to PATH (if needed)
export PATH="$HOME/.cargo/bin:$PATH"