A Python CLI tool that renders videos as ASCII art in the terminal in real-time.

• Local video support - Play any video file (MP4, AVI, MKV, etc.)
• YouTube support - Stream YouTube videos directly
• Color mode - Full color ASCII using ANSI 256-color codes
• Auto-sizing - Automatically fits to terminal dimensions
• Smooth playback - Double buffering prevents flickering
• Frame sync - Precise timing maintains correct playback speed

cd /Users/johan/Downloads/terminalVideo
pip install -r requirements.txt

Note: For YouTube support, ensure yt-dlp is also available in your PATH:

brew install yt-dlp  # macOS

# Play a local video
python -m ascii_video.main video.mp4

# Play with color
python -m ascii_video.main video.mp4 --color

# Set custom width
python -m ascii_video.main video.mp4 --width 120

# Play a YouTube video
python -m ascii_video.main "https://www.youtube.com/watch?v=VIDEO_ID"

# Override frame rate
python -m ascii_video.main video.mp4 --fps 30

ascii_video/
├── main.py           # CLI entry point
├── video_source.py   # Video input handling
├── ascii_converter.py # Frame to ASCII conversion
├── renderer.py       # Terminal rendering engine
└── utils.py          # Terminal utilities

The player uses time.perf_counter() for high-precision timing:

target_frame_time = 1.0 / fps
frame_start = time.perf_counter()

# Process and render frame...

elapsed = time.perf_counter() - frame_start
sleep_time = target_frame_time - elapsed
if sleep_time > 0:
    time.sleep(sleep_time)

This ensures the video plays at the correct speed regardless of processing time.

To prevent flickering, the renderer:

1. Builds the complete frame as a string in memory
2. Uses \033[H (cursor home) instead of clearing the screen
3. Writes the entire buffer at once

This overwrites the previous frame in-place without any visible clearing.

MIT