ytascii-player

Play any YouTube video as synced, true-color ASCII art in your terminal.

pip install ytascii-player
ytascii "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

That's it — no cloning a repo, no copying .py files, no python script.py syntax. Just install once, then run ytascii on any video link.

Requirements

• Python 3.8+ (pip installs everything else Python-related automatically)
• ffmpeg installed separately and on your PATH — pip cannot install this, it's not a Python package. See below.

Installing ffmpeg (one-time, per machine)

Windows:

1. Download the "release essentials" build from https://www.gyan.dev/ffmpeg/builds/
2. Extract it somewhere permanent, e.g. C:\ffmpeg
3. Add C:\ffmpeg\bin to your PATH (Win key → "Environment Variables" → Edit the system environment variables → Environment Variables → select Path → Edit → New → paste C:\ffmpeg\bin)
4. Open a new terminal and confirm with ffmpeg -version

macOS: brew install ffmpeg

Linux: sudo apt install ffmpeg (Debian/Ubuntu) or your distro's equivalent

Usage

ytascii "https://www.youtube.com/watch?v=VIDEO_ID"
ytascii "URL" --width 140
ytascii "URL" --mode grayscale

Press Ctrl+C anytime to stop playback.

Tuning tips

• Maximize your terminal and shrink the font (try 8pt) before running.
• Windows Terminal renders far more smoothly than the legacy conhost cmd window.
• If playback is choppy, lower --width or use --mode grayscale.

Legal note

Only use this on videos you have the right to download — your own uploads, Creative Commons content, or otherwise permitted use.

For developers: installing from source

git clone <this-repo>
cd ytascii-player
pip install -e .

-e installs in "editable" mode — code changes apply instantly without reinstalling.

Publishing (maintainer notes)

pip install build twine
python -m build
twine upload dist/*

Username is literally __token__; password is your PyPI API token from Account Settings → API tokens.