PRODUCTION READY | THREE.JS WEBGPU & TSL SHADERS | ANSI TERMINAL PLAYER

Turn images and videos into live ASCII art and retro effects

RGB ASCII & Retro FX Studio is a dedicated visual processing engine for creative developers, artists, and terminal power users. Run real-time GPU retro shaders in your browser with zero server roundtrips, stream 24-bit ANSI True Color video with synchronized audio in your terminal, or batch-render full-resolution clips via a bounded export microservice.

Engine
Three.js WebGPU
WebGL2 Fallback
Shaders
16 Retro Modes
ASCII, CRT, Matrix
Terminal
ANSI True Color
Audio Sync & ▀ Half-Block
Privacy
100% Local Studio
Zero Media Uploads
Backend API
FastAPI / FFmpeg
Chunked MP4 & GIF Export
Direct Product Interface

Interactive Web Studio Workspace

Launch Studio Workspace →
rgb-ascii studio v1.0.0 [webgpu]
Interactive RGB ASCII and Retro FX Studio interface showing 16 shader modes on the left rail, real-time WebGPU canvas preview in center stage, tone curve controls, and export drawer
Drag & drop photos, load videos, or stream webcam feeds directly into the interactive workspace.
Architecture & Surfaces

Three Specialized Production Surfaces

RGB ASCII is architected as three distinct components rather than a single monolith. Client-side preview, terminal rendering, and cloud transcoding are strictly segregated.

Surface 01 Client GPU

Browser Interactive Studio

Zero-install client web application running Three.js WebGPU and Three Shading Language (TSL). Automatically falls back to WebGL2 on unsupported browsers.

  • Inputs: PNG, JPG, WebP, GIF, MP4, WebM, Live Webcam
  • Shaders: 16 realtime shader modes with live parameter sliders
  • Tone: Rec. 601 brightness, contrast, saturation, hue, gamma, invert
  • Client Exports: PNG, JPEG, GIF (1-5s), SVG, .txt grid, WebM
  • Privacy: 100% on-device GPU processing; zero file uploads
Surface 02 Local Terminal

Python ANSI True Color CLI

High-performance terminal video player built using standard-library Python. Emits 24-bit True Color escapes (\x1b[38;2;R;G;Bm) with synchronized audio.

  • Resolution: Half-block mode (▀) for 2× vertical cell resolution
  • Audio Sync: Master clock sync with adaptive frame load shedding
  • Smoothing: Temporal alpha smoothing reduces ASCII scintillation
  • Pipeline: Subprocess FFmpeg pipe decoding + FFplay audio playback
  • Zero Deps: Pure standard library Python 3.10+ runtime
Surface 03 FastAPI Cloud

High-Resolution Export API

Production FastAPI microservice for heavy transcoding tasks. Renders high-resolution MP4 video and animated GIFs with original source audio preservation.

  • Transcoding: FFmpeg H.264/AAC MP4 & two-pass palettegen GIF
  • Uploads: Chunked binary uploads (/api/export/chunk)
  • Security: Cloudflare Turnstile bot verification
  • Lifecycle: Isolated workspaces purged automatically by janitor
  • Hosting: Free-tier single-worker deployment with bounded limits
Shader Capabilities

16 Real-Time Retro Visual Shaders

Every shader runs as a native GPU pipeline in Three.js TSL. Switch between modes instantly with live parameter sliders and Rec. 601 pre-tone curve adjustments.

MODE 01 ascii

ASCII Glyph Atlas

Monospace luminance mapping with standard, dense, simple, and blocks ramps or freeform custom characters. Configurable cell size, spacing, and aspect ratio.

MODE 02 dither

Ordered Dithering

Floyd-Steinberg and Bayer 4×4 / 8×8 matrix dispersion. Adjust quantization step levels and error distribution spread.

MODE 03 halftone

Halftone Dot Screen

Rotated CMYK / monochrome dot matrix printing raster with adjustable screen angle, dot frequency, and maximum radius.

MODE 04 vhs

VHS / CRT Monitor

Analog cathode-ray tube emulation featuring horizontal scanlines, RGB chromatic aberration, tape noise, and barrel curvature.

MODE 05 matrix

Matrix Digital Rain

Phosphor green digital rain streams cascading down columns. Tunable waterfall stream speed and glyph column density.

MODE 06 dots

Circular Dot Grid

Subsampled circular LED/dot raster with luminance-scaled radii and dark inter-cell gutters.

MODE 07 contour

Topological Contour

Iso-luminance elevation lines creating vector-like cartographic contour maps across high-contrast gradients.

MODE 08 pixelSort

Directional Pixel Sort

Simulated glitched pixel displacement along directional vectors based on brightness threshold and span length.

MODE 09 blockify

Mosaic Blockify

8-bit mosaic pixelation quantization with configurable block dimensions and luminance averaging.

MODE 10 threshold

High-Contrast Threshold

Binary 1-bit black/white cutoffs for stark graphic novel silhouettes and stencil separations.

MODE 11 edgeDetect

Sobel Edge Detection

Spatial gradient convolution matrix revealing outlines, wireframe contours, and structural borders.

MODE 12 crosshatch

Pen Crosshatching

Layered diagonal stroke patterns emulating vintage print engravings and hand-drawn pen sketches.

MODE 13 waveLines

Oscillating Wave Lines

Horizontal raster scans modulated by harmonic sinusoidal distortion and vertical displacement.

MODE 14 noise

Film Grain & Static

Procedural pseudo-random analog film grain and static noise injection with variable intensity.

MODE 15 voronoi

Voronoi Stained Glass

Geometric cellular tiling and stained glass crystallizations mapped over input colors.

MODE 16 tone

Rec. 601 Tone Grading

Pure Rec. 601 pre-tone stage without geometric shaders: brightness, contrast, saturation, hue, gamma, and inversion.

Engineering Details

Technical Specifications & Prerequisites

Clear facts regarding hardware capabilities, platform limitations, privacy boundaries, and supported formats.

Privacy & Data Boundary Policy

Surface Network Transmission Processing Location Storage / Retention
Browser Studio (/studio/) 0 bytes transmitted Local GPU / WebGPU / Canvas Ephemeral memory only; cleared on tab close
Terminal Player (CLI) 0 bytes transmitted Local CPU + local FFmpeg process Reads local disk file; zero telemetry
Server Export API Encrypted TLS chunks FastAPI worker running FFmpeg Temporary disk file purged by janitor worker

Browser & Hardware Prerequisites

  • WebGPU: Supported on Chromium 113+, Safari 18+, and modern Firefox with WebGPU enabled. Uses dedicated hardware adapters where present.
  • WebGL2 Fallback: When WebGPU is unsupported or adapter creation fails, Three.js automatically switches to forceWebGL: true.
  • Webcam Feeds: Requires explicit user camera permission via the browser navigator.mediaDevices.getUserMedia API over HTTPS.
  • WebM Recording: Depends on client MediaRecorder API support with VP8/VP9 or compatible codecs.

Supported Input & Export Formats

  • Inputs: PNG, JPEG, WebP, GIF, MP4, WebM, live camera stream.
  • Client Image Export: PNG or JPEG snapshot directly from GPU canvas via canvas.toBlob().
  • Client GIF Export: Animated GIF rendered client-side with gifenc. Enforces a 1 to 5 second duration limit to safeguard browser memory.
  • Vector & Text Export: Scalable vector SVG with colored <tspan> elements and raw Rec. 601 plain text (.txt) grids.
  • Server Video Export: Full-length MP4 (H.264 video, AAC audio) with source audio track preservation and high-resolution GIF palettes.
Developer Workflows

Quick Start & Command Reference

Get up and running with the terminal video player, local browser studio, or server export backend in minutes.

Surface 02 // CLI

1. Run the Python ANSI Terminal Video Player

Requirements: Python 3.10+ and system FFmpeg/FFplay binaries. Plays any video file directly in modern 24-bit ANSI True Color terminals with master-clock synchronized audio.

# Clone repository and install in editable mode
git clone https://github.com/Sujoy-004/ASCII.git
cd ASCII
pip install -e .

# Play video with 2x vertical resolution in ANSI True Color
rgb-ascii video.mp4 --half-block

# Alternative CLI options
rgb-ascii video.mp4 --preset dense --no-audio
rgb-ascii video.mp4 --no-color --smoothing 0.2
Surface 01 // Frontend

2. Run the Interactive Web Studio Locally

Requirements: Node.js 18+. Starts the Vite development server with Hot Module Reloading. Open http://localhost:5173/studio/.

cd web
npm install
npm run dev

# Open http://localhost:5173/studio/
Surface 03 // Backend

3. Run the FastAPI / FFmpeg Export Service

Starts the FastAPI microservice on port 8000 with CORS and health endpoints.

pip install -r requirements.txt
uvicorn src.api.main:app --host 0.0.0.0 --port 8000 --reload

# Check health endpoint: http://localhost:8000/health
Reference & Clarifications

Frequently Asked Questions

Does the interactive web studio upload my images or webcam feed?

No. The interactive studio runs 100% inside your local browser via WebGPU and WebGL2. When you drag and drop photos or videos, or activate your webcam, media buffers are uploaded exclusively to local GPU textures. Zero bytes leave your machine during interactive editing or client exports.

What happens if my browser or device does not support WebGPU?

The studio automatically falls back to Three.js’s WebGL2 backend (forceWebGL: true). While WebGPU offers higher performance and modern compute capabilities on supported browsers (Chromium 113+, Safari 18+), the WebGL2 fallback ensures shader compatibility on standard modern devices.

Why is the client-side GIF export limited to 5 seconds?

Client-side GIF rendering generates, quantizes, and palettizes uncompressed frames entirely within the browser tab’s memory using JavaScript (gifenc). Limiting recordings to 1–5 seconds guarantees smooth encoding without browser tab crashes or mobile memory out-of-bounds errors. For full-duration video and long GIF rendering, use the server-side export microservice.

How does the Python terminal video player keep audio and video synchronized?

The terminal CLI establishes a master audio clock timebase. An FFplay subprocess streams the audio track while an FFmpeg subprocess pipes decoded raw video frames to stdout. The Python runner continuously measures elapsed audio time and applies adaptive frame load shedding—dropping frames if the terminal emulator lags or holding frames if rendering leads—preventing desynchronization.

When should I use the server-side export service versus client export?

Use client exports (PNG, JPEG, SVG, .txt, 5s GIF, WebM) for instant, private downloads without server queues. Use the server export microservice when you need full-length high-resolution MP4 rendering with intact source audio tracks, or multi-pass palette-optimized animated GIFs.