🎥 ASCII Cam: Real-Time ASCII Art Renderer from Live Camera Feed

Real-time ASCII art renderer from webcam feed — live camera output converted to colored ASCII characters and Matrix rain, built entirely in C++17 with OpenCV.

---

📌 Highlights

🎨 True Color ASCII — Each character is colored with the exact RGB value of the camera pixel it represents, using ANSI 24-bit escape codes for full terminal color fidelity.

🌧️ Matrix Rain Mode — A second rendering mode where rain drops fall over the live camera feed, brightness-mapped to green intensity so your face accentuates through the rain.

📐 Auto Terminal Sizing — Frame dimensions are dynamically read from the terminal on every frame — resize the window and the output adapts instantly.

⚡ FPS-Capped Pipeline — A Timer struct caps the render loop to a configurable target FPS using std::chrono::steady_clock, preventing CPU burn on fast machines.

🧱 Zero External Dependencies Beyond OpenCV — No ncurses, no SDL, no third-party terminal libraries. Windows Console API for terminal control, OpenCV for camera capture.

🎬 Local Video File Support — Pass any local video file via --video <path> and render it as ASCII art in real time. Videos loop automatically when they end. Compatible with both normal and matrix modes across all supported formats — MP4, AVI, MKV, MOV and more via OpenCV's backend.

---

🧮 How It Works

ASCII Mapping

Each camera pixel is converted to a single terminal character using the standard luminance formula:

$$brightness = 0.299 \cdot R + 0.587 \cdot G + 0.114 \cdot B$$

These weights reflect human perceptual sensitivity — we're most sensitive to green, least to blue. The brightness value (0–255) is then mapped linearly to an index in the charset:

$$index = \frac{brightness \times (|charset| - 1)}{255}$$

Default charset ordered dark to bright:

" .:-=+*#%@"

ANSI True Color

Each character is wrapped in an ANSI 24-bit escape sequence:

ESC[38;2;R;G;Bm{char}ESC[0m

This gives exact per-pixel color matching rather than the 8 or 256 color approximations used by older terminals.

Matrix Rain

Each column maintains a Drop — a head position falling downward at 1–2 rows per frame. Trail cells age every frame; age maps to green intensity:

Age	Color
0	Bright white head
1–2	Full green, boosted by camera brightness
3–6	80% green
7–12	55% green
13+	Fading, dim

Camera brightness applies a quadratic boost curve so face highlights shoot to full green while dark backgrounds stay dim:

$$green = 150 + 105 \times \left(\frac{brightness}{255}\right)$$

---

📁 Project Structure

ascii-cam/
├── CMakeLists.txt
├── main.cpp
├── include/
│   ├── camera.hpp
│   ├── frame.hpp
│   ├── ascii_mapper.hpp
│   ├── renderer.hpp
│   ├── matrix_renderer.hpp
│   ├── terminal.hpp
│   ├── timer.hpp
│   └── config.hpp
├── src/
│   ├── camera.cpp
│   ├── frame.cpp
│   ├── ascii_mapper.cpp
│   ├── renderer.cpp
│   ├── matrix_renderer.cpp
│   ├── terminal.cpp
│   └── timer.cpp
├── assets/
│   ├── charsets.txt
│   └── demo.gif
└── build/

---

⚙️ Core Components

Frame — 2D grid of Pixel structs (R, G, B). All data flows through this struct between camera, mapper and renderer.

Camera — Wraps cv::VideoCapture. Captures frames, converts BGR→RGB, resizes to terminal dimensions.

AsciiMapper — Maps each pixel to a brightness-indexed character and wraps it in an ANSI color escape sequence.

Renderer — Main render loop. Captures → maps → prints. Auto-resizes frame to terminal on every tick.

MatrixRenderer — Alternate render loop. Maintains per-column Drop state and a trail_age grid. Camera brightness shapes rain intensity.

Terminal — Windows Console API wrapper. Reads terminal dimensions, clears screen, moves cursor home between frames to render in-place without scroll flicker.

Timer — FPS cap using std::chrono::steady_clock. Sleeps for remaining frame budget after render completes.

Config — Compile-time constants (constexpr) in a namespace. Single source of truth for FPS, charset, device ID.

---

🔧 Dependencies

Tool	Purpose
GCC 9+ / MSVC 2022 / Clang 12+	C++17 compiler
CMake 3.15+	Build system
Ninja	Fast build runner
OpenCV 4.x	Camera capture & frame processing

---

🚀 Installation & Build

Windows (MSYS2 UCRT64 + MinGW — Recommended)

1. Install MSYS2

Download from msys2.org. Open MSYS2 UCRT64 and run:

pacman -Syu   # restart terminal when prompted
pacman -Su
pacman -S --needed base-devel mingw-w64-ucrt-x86_64-toolchain
pacman -S mingw-w64-ucrt-x86_64-cmake mingw-w64-ucrt-x86_64-ninja

Add to Windows System PATH:

C:\msys64\ucrt64\bin

2. Build OpenCV from source

Prebuilt OpenCV binaries from opencv.org target MSVC, not MinGW. Build from source for GCC compatibility.

cd /d/libs
git clone https://github.com/opencv/opencv.git
mkdir opencv-build && cd opencv-build

cmake /d/libs/opencv -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX=/d/libs/opencv-mingw \
  -DBUILD_SHARED_LIBS=ON \
  -DBUILD_TESTS=OFF \
  -DBUILD_PERF_TESTS=OFF \
  -DBUILD_EXAMPLES=OFF \
  -DWITH_CUDA=OFF

ninja && ninja install

Add to Windows System PATH:

D:\libs\opencv-mingw\x64\mingw\bin

Alternative: Install Visual Studio 2022 + vcpkg and run vcpkg install opencv — no source build needed.

3. Build ascii-cam

cd /d/Codes/projects/ascii-cam/build
cmake .. -G Ninja -DCMAKE_BUILD_TYPE=Release
ninja

---

macOS

brew install opencv cmake ninja
mkdir build && cd build
cmake .. -G Ninja -DCMAKE_BUILD_TYPE=Release
ninja

---

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install libopencv-dev cmake ninja-build build-essential
mkdir build && cd build
cmake .. -G Ninja -DCMAKE_BUILD_TYPE=Release
ninja

---

▶️ Running

Windows:

# Normal ASCII color mode — live camera
.\ascii-cam.exe

# Local video file
.\ascii-cam.exe --video "D:\myvideo.mp4"

# Matrix rain mode — live camera
.\ascii-cam.exe --matrix

# Matrix rain mode — video file
.\ascii-cam.exe --matrix --video "D:\myvideo.mp4"

macOS / Linux:

# Normal ASCII color mode — live camera
./ascii-cam

# Local video file
./ascii-cam --video "/home/user/myvideo.mp4"

# Matrix rain mode — live camera
./ascii-cam --matrix

# Matrix rain mode — video file
./ascii-cam --matrix --video "/home/user/myvideo.mp4"

Exit with Ctrl+C — the signal handler cleanly stops the camera and restores the terminal.

⚠️ Note: Matrix mode and terminal control currently only work on Windows. Linux/macOS support is planned.

Exit with Ctrl+C — the signal handler cleanly stops the camera and restores the terminal.

---

🔩 CMakeLists.txt

cmake_minimum_required(VERSION 3.15)
project(ascii-cam)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

set(OpenCV_DIR "D:/libs/opencv-mingw")   # Windows only — remove on macOS/Linux

find_package(OpenCV REQUIRED)

include_directories(include)
include_directories(${OpenCV_INCLUDE_DIRS})

file(GLOB SOURCES "src/*.cpp")

add_executable(ascii-cam main.cpp ${SOURCES})
target_link_libraries(ascii-cam ${OpenCV_LIBS})

---

🚧 Known Limitations

• Windows only terminal control — terminal.cpp uses the Windows Console API. Linux/macOS port requires ncurses or raw ANSI escape codes.
• Single camera — defaults to device 0. Change Config::DEFAULT_DEVICE for external cameras.
• Terminal font matters — square monospace fonts (Cascadia Code, Fira Mono) give the best aspect ratio. Default Windows terminal fonts may distort proportions.

---

🔮 Planned Features

• Linux/macOS terminal support via ncurses
• Katakana charset for authentic Matrix look
• Configurable charset and FPS via CLI flags
• Record output to file / GIF export
• Edge-detection mode — outline rendering only

---

⚖️ License

MIT License — free to use, modify, and distribute with attribution.

---

👨‍💻 Author

Anvay Mayekar
🎓 B.Tech in Electronics & Computer Science — SAKEC, Mumbai