ASCILINE/README.md

🌌 ASCILINE Engine

ASCILINE is a high-performance, real-time ASCII video rendering engine. Our core objective is to transform the web into a highly dynamic and interactive typographic canvas. By moving away from traditional video players, ASCILINE streams visual data from a Python backend directly into the browser at 60 FPS as raw, manipulable text.

_{* Showcases rendered using Mode 3 (32K Colors)}

🎯 Strategic Vision & Core Capabilities

1. Pure Typographic Manipulation: The visual stream is not a standard media file—it's raw HTML/Canvas text. This makes the impossible possible: you can apply real-time CSS filters (neon glows, text shadows) to a playing video, dynamically manipulate colors, or let users literally copy a moving visual element with their cursor.
2. Local AI & LLM Ready: By reducing complex pixel streams into structured logical strings, ASCILINE acts as a perfect bridge for AI. Instead of feeding heavy computer vision models, lightweight text blocks can be fed directly to Local LLMs. Analyzing visual changes becomes as simple as taking a "diff" between two text strings.
3. Ultra-Low Bandwidth & IoT Compatibility: Standard codecs (H.264/VP9) choke microcontrollers and weak networks. ASCILINE processes the heavy lifting once on the backend, streaming only a few kilobytes of String packets per second via WebSockets. It enables zero-latency live streams on satellite connections, embedded systems, and extreme low-bandwidth environments.
4. Bypassing Browser Constraints: Modern browsers aggressively throttle autoplay videos, and ad-blockers restrict traditional media frames. To the browser, ASCILINE is simply "JavaScript updating text on a page." This circumvents traditional restrictions, allowing for immediate, unblockable visual streams.

🚀 Technical Features

• Real-Time Streaming: Low-latency video-to-ASCII conversion.
• High Performance: Uses HTML5 Canvas for rendering instead of heavy DOM elements, enabling 60 FPS playback.
• Binary Protocol: Frames are encoded into Uint8Array (binary) for efficient bandwidth usage.
• Multiple Color Modes: Supports everything from classic B&W to 16M color ultra-fidelity.
• Modern Aesthetic: Premium dark-mode UI with interactive ripple dissolve effects.

🛠️ Architecture

1. Backend (Python/FastAPI): Decodes video using OpenCV, maps pixels to ASCII characters via NumPy, and streams binary data.
2. Frontend (Vanilla JS): Receives binary frames via WebSockets, manages a jitter buffer, and renders to a Canvas grid.
3. Communication: Optimized WebSocket protocol with a custom INIT handshake for dynamic resolution/FPS adjustment.

📦 Installation

1. Clone the repository

git clone https://github.com/yourusername/ASCILINE.git
cd ASCILINE

2. Install dependencies

pip install fastapi uvicorn opencv-python numpy websockets

3. Run the engine

Place a video.mp4 in the root directory and start the server:

python stream_server.py

Open http://localhost:8000 in your browser.

🎨 Customization

You can easily customize the look and feel of the engine:

Styling

Edit style.css to change the accent colors and typography using CSS variables:

:root {
    --accent-color: #00ff41; /* Classic Matrix Green */
    --bg-color: #050505;
}

Rendering Modes

The engine supports different fidelity levels via the --mode flag:

• 1: Black & White (DOM mode)
• 2: 512 Colors
• 3: 32K Colors
• 4: 262K Colors
• 5: 16M Colors (Ultra)

python stream_server.py --mode 5 --cols 240 --rows 100

📜 License & Ethical Guardrails

MIT License (with Anti-Ad Restriction)

ASCILINE is distributed under the MIT License, but with a strict ethical guardrail. Because this engine bypasses standard browser constraints and ad-blockers (by rendering pure text instead of video), we strictly prohibit its use by ad-networks to serve unblockable advertisements.

See the LICENSE file for the full text, which includes the ANTI-ADVERTISEMENT RESTRICTION clause.