Developer Tool / Creative Coding 2026
yt2ascii
A command-line tool that plays YouTube videos as coloured ASCII art in the terminal, with synced audio.
- Year
- 2026
- Status
- Built
- Platform
- Command line
- Scope
- CLI, Rendering pipeline, Playback
A still frame put through yt2ascii's own renderer at 120 columns, truecolor. Characters come from the default luminance ramp.
Overview
yt2ascii takes a YouTube URL, converts every frame into coloured characters and plays it back in place in the terminal, timed to the source, with the audio alongside. The terminal is the entire interface, and nothing is left on disk after it exits.
Challenge
Terminals are slow to draw and every frame has a deadline. Converting and painting thousands of coloured cells per frame in Python, while keeping video and audio in step, leaves little room for per-pixel loops.
Direction
Resize each frame as soon as it is decoded, do the luminance and colour work as whole-array NumPy operations, and write each frame to the terminal in a single call with run-length-encoded colour. A monotonic clock decides what is shown, skipping frames when playback falls behind rather than drifting.
Frame pipeline
- 01YouTube URLvalidated, canonicalised
- 02yt-dlpmetadata and download
- 03OpenCV decoderesized immediately
- 04LuminanceNumPy, per cell
- 05Character rampdark to light
- 06ANSI colourrun-length encoded
- 07Terminalone write per frame
Video timing comes from a monotonic clock; audio plays through an external player kept in step with it.
What was built
- URL handling for watch, short, embed and live links, or a bare video id
- Metadata, duration limit and download through yt-dlp into one temporary directory
- Vectorised frame conversion to characters with per-cell colour
- Truecolor, 256-colour and grayscale rendering, and a custom character ramp
- Aspect-ratio correction for terminal cells, or stretch-to-fill
- Monotonic-clock playback with frame skipping, and audio synced through an external player
- Pause, restart and live width controls
- Clean exit on every path: terminal restored, audio stopped, temporary files deleted
Technology
- Python
- NumPy
- OpenCV
- yt-dlp
- ANSI escape codes
- pytest
Outcome
Version 0.1.0: a working terminal player with a tested renderer, colour conversion and playback scheduler.
Output
Fetching video information...✓ Video found✓ Duration: 09:56✓ Resolution: 1920x1080✓ Source FPS: 30 Preparing renderer...✓ ASCII width: 120✓ Playback FPS: 15✓ Colour: truecolor Press SPACE to pause • Q to quit