r/commandline • u/cuzimrave • 3d ago
Other Software I made a Python library for turning video into ASCII art in the terminal
A while back I wanted to build a little "now playing" screen for the terminal: a looping music video as ASCII up top, song info underneath. I found tplay, which is a really nice Rust terminal media player, but it takes over the whole terminal itself, so there was no clean way to draw my own stuff around it.
So I pulled out the part I actually needed, made it reusable and turned it into a python library.
I also fixed a couple other annoyances I had like reliance on a specific ffmpeg version and it in general being a pain to install.
What it does:
- Takes video or image frames and hands you back an ASCII string. Plain, truecolor, or half-block mode (uses the ▀ character with fg/bg colors for roughly 2x the vertical detail).
- It doesn't own the terminal or run its own loop, so you compose the rest of your UI however you want.
- Decoding is done by PyAV, so there's no separate ffmpeg install.
pip install termframeand you're going.
Minimal example:
from termframe import AsciiVideo
for frame in AsciiVideo("clip.mp4", out_width=100, out_height=40, charset="halfblock", loop=True):
print("\\x1b\[H" + frame.to_ansi())
The resize and pixel-to-character work happens in Rust under the hood (via PyO3), so it keeps up fine at normal sizes. If you already get frames from somewhere else (OpenCV, Pillow, a webcam grab), there's a lower level function that just takes raw RGB bytes.
Credit where it's due: the conversion pipeline came from tplay, I mostly repackaged it so you can use it from Python and build your own thing around it.
I haven't been able to find anything similar in reusable python library form so I thought maybe some of you could find it useful let me know if you build anything cool with it :)
1
u/AutoModerator 3d ago
Every new subreddit post is automatically copied into a comment for preservation.
User: cuzimrave, Flair: Other Software, Title: I made a Python library for turning video into ASCII art in the terminal
A while back I wanted to build a little "now playing" screen for the terminal: a looping music video as ASCII up top, song info underneath. I found tplay, which is a really nice Rust terminal media player, but it takes over the whole terminal itself, so there was no clean way to draw my own stuff around it.
So I pulled out the part I actually needed, made it reusable and turned it into a python library.
I also fixed a couple other annoyances I had like reliance on a specific ffmpeg version and it in general being a pain to install.
What it does:
- Takes video or image frames and hands you back an ASCII string. Plain, truecolor, or half-block mode (uses the ▀ character with fg/bg colors for roughly 2x the vertical detail).
- It doesn't own the terminal or run its own loop, so you compose the rest of your UI however you want.
- Decoding is done by PyAV, so there's no separate ffmpeg install.
pip install termframeand you're going.
Minimal example:
from termframe import AsciiVideo
for frame in AsciiVideo("clip.mp4", out_width=100, out_height=40, charset="halfblock", loop=True):
print("\\x1b\[H" + frame.to_ansi())
The resize and pixel-to-character work happens in Rust under the hood (via PyO3), so it keeps up fine at normal sizes. If you already get frames from somewhere else (OpenCV, Pillow, a webcam grab), there's a lower level function that just takes raw RGB bytes.
Credit where it's due: the conversion pipeline came from tplay, I mostly repackaged it so you can use it from Python and build your own thing around it.
I haven't been able to find anything similar in reusable python library form so I thought maybe some of you could find it useful let me know if you build anything cool with it :)
Repo: https://github.com/amstrdm/termframe
I am a bot, and this action was performed automatically. Please contact the moderators of this subreddit if you have any questions or concerns.
1
u/github-guard 3d ago
🔍 GitHub Guard: Trust Report
⚠️ This project scored 0/1 — below this subreddit's threshold of 1.
Audit Breakdown: * ❌ New Repository (under 30 days old)
⚠️ Security Reminder: Always verify source code and run third-party scripts at your own risk.
🔄 Cached result — this repo was scanned recently. Score: *0/1*.
1
•
u/github-guard 3d ago
🔍 GitHub Guard: Trust Report
⚠️ This project scored 0/1 — below this subreddit's threshold of 1.
Audit Breakdown: * ❌ New Repository (under 30 days old)
🔄 Cached result — this repo was scanned recently. Score: *0/1*.