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"
ytascii "never gonna give you up rick astley"

That's it — no cloning a repo, no copying .py files, no python script.py syntax, and no separate ffmpeg/yt-dlp install. pip install is genuinely all that's needed. You can paste a video URL or just type a name/description — both work.

Requirements

• Python 3.8+ — that's it. Everything else is a normal pip dependency: yt-dlp (used as a Python library, not a CLI tool), opencv-python, numpy, and imageio-ffmpeg (ships a real ffmpeg binary inside the pip package itself, so there's nothing to separately download or add to PATH).

Usage

ytascii "https://www.youtube.com/watch?v=VIDEO_ID"
ytascii "imagine dragons believer"
ytascii "URL or search text" --width 140
ytascii "URL or search text" --mode grayscale

You can pass either a YouTube URL, or just a plain video/song name/description - ytascii detects which one you gave it and searches YouTube automatically for anything that isn't a link. Multi-word searches need quotes, same as URLs do.

Press Ctrl+C anytime to stop playback. When you search by name, ytascii prints which video it actually found before downloading - useful if the top YouTube result wasn't the one you meant (e.g. it grabbed a cover or lyric video).

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.

Troubleshooting

ytascii : command not recognized, right after installing Pip installs the command into a Scripts folder that isn't always on your system's PATH by default — this depends on how Python itself was installed on your machine. Two options:

1. Quick workaround, no setup changes: run python -m ytascii.cli "URL" instead — this works immediately because it doesn't rely on PATH at all.
2. Permanent fix: when you ran the install, pip prints a warning like The script ytascii.exe is installed in 'C:\...\Scripts' which is not on PATH. Copy that exact folder path, then: Win key → search "Environment Variables" → Edit environment variables for your account → select Path → Edit → New → paste the folder → OK. Open a new terminal and ytascii will work directly.

'pip' is not recognized Same PATH issue, one level up. Use python -m pip install ytascii-player instead, which works regardless of PATH.

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. Remember to bump the version number in pyproject.toml and src/ytascii/__init__.py before every new upload — PyPI never allows re-uploading the same version number.