Repository navigation
Releases
v1.0.3 — The Interactive & Aesthetic Update 🎨⚡
⚡ TermTube v1.1.0 — The Interactive & Aesthetic Update
Stream YouTube videos directly inside your terminal with ANSI truecolor or ASCII rendering and synchronized audio. This release introduces seamless live hotkeys (no playback interruption), vibrant color themes, robust stream extraction with Deno, and a streamlined zero-install workflow.
🌟 Highlights & What's New
1. ⌨️ Live In-Flight Hotkey Controls
Switch styles, tweak lighting, or change colors on the fly without stopping playback:
S/Tab/Space: Cycle through all rendering styles with automatic wrap-around.1-6: Jump directly to Binary 0101, Block Shades (░▒▓█), High-Contrast, Classic ASCII, Matrix Code, or Dots.0/H: Switch straight into Half-Block HD Truecolor (▀).C: Cycle color modes (RGB ➔ Matrix ➔ Cyberpunk ➔ Glitch ➔ Rainbow ➔ Amber ➔ Fire ➔ Gray).G&M: Instant one-key toggles for VHS Glitch and Matrix Neon Green.+/-&[/]: Dial contrast and brightness up or down in real time.A/I: Instant toggle for Dynamic Auto-Contrast and Ramp Inversion.- On-Screen Display (OSD): Visual badge overlay displays current settings whenever modified.
2. 🌈 Aesthetic Color Palettes & Custom Ramps
Transform any video stream to match your terminal setup:
glitch: Multicolor chromatic aberration with VHS scanline fringe splits.rainbow: Psychedelic neon spectrum mapped across luminance levels.matrix&cyberpunk: Cyberpunk green phosphor monitor and electric cyan/magenta hues.amber&fire: Vintage CRT amber glow and thermal flame gradients.- Preset Ramps: Built-in artistic ramps for Binary, Braille, Dots, Math symbols, and more.
3. 🛡️ Bulletproof YouTube Extraction (Deno Runtime + Auto-Repair)
- Integrated embedded Deno JS runtime support to handle YouTube's latest signature challenges and anti-bot checks smoothly without throttling.
- Auto-healing stream resolver: Automatically detects yt-dlp stream errors and updates components dynamically.
4. 🚀 Zero-Install & One-Click Launchers
- Windows (
play.bat): Automatically bootstraps an isolated, portable Python 3.11 environment, FFmpeg, ffplay, and Deno—no manual installer or admin rights required. - Linux & macOS (
play.sh): Auto-installs missing packages throughaptorbrewand sets up the audio/video pipes out of the box.
5. 🛠️ Stability & Terminal Performance
- Fixed Windows terminal freezing when clicking the console window or switching focus (QuickEdit console mode auto-disabled).
- Non-blocking input polling prevents missed frames or keyboard buffer accumulation.
- Automatic 16:9 terminal scaling with scroll/buffer overflow protection.
⌨️ Live Hotkey Cheat Sheet
| Key | Action | Description |
|---|---|---|
S / Tab |
Cycle Styles | Cycles through all 7 styles smoothly |
0 / H |
HD Half-Block | 24-bit Truecolor half-block (▀) mode |
1 |
Binary 0101 | Matrix binary stream |
2 |
Block Shades | Smooth density blocks ( ░▒▓█) |
3 |
High-Contrast | Deep blacks with bright highlights |
4 - 6 |
ASCII / Matrix / Dots | Classic ASCII, Matrix characters, or Dots (·•○●█) |
C |
Cycle Colors | RGB ➔ Matrix ➔ Cyberpunk ➔ Glitch ➔ Rainbow ➔ Amber ➔ Fire ➔ Gray |
G / M |
Glitch / Matrix | Quick toggle VHS chromatic aberration or Green Phosphor |
+ / - |
Contrast | Boost or decrease contrast dynamically |
] / [ |
Brightness | Increase or decrease brightness |
A |
Auto-Contrast | Toggle dynamic range stretching ON/OFF |
I |
Invert | Invert dark/light character mapping |
Q |
Quit | Clean exit and pipe termination |
v1.0.2
TermTube v1.0.2
Adds full Linux and macOS support with automatic dependency installation, an interactive FPS selection option, and a black-background rendering fix for ASCII mode.
Added
- Cross-platform setup script (
play.sh) with automatic dependency installation for:- Debian/Ubuntu and derivatives (Linux Mint, Pop!_OS, Elementary OS) via
apt-get - Fedora/RHEL/CentOS derivatives (Rocky Linux, AlmaLinux) via
dnf - Arch Linux and derivatives (Manjaro, EndeavourOS) via
pacman - macOS (Apple Silicon and Intel) via Homebrew, with architecture-aware Deno binary selection
- Debian/Ubuntu and derivatives (Linux Mint, Pop!_OS, Elementary OS) via
- Safe fallback for unsupported distributions (e.g. openSUSE, Gentoo, Alpine) — prints clear manual installation instructions instead of crashing
- Portable Deno auto-downloader for systems missing the Deno JS runtime, fetched directly from Deno's official GitHub releases
- Interactive FPS selection prompt (15 / 24 / 30) in the guided playback flow, so users can pick smoother or safer playback without needing to know the
--fpsflag — explicit--fpson the command line still takes priority and skips the prompt - Virtual environment cleanup on failed setup, preventing corrupted
.venvstate from blocking future runs - Version-aware Python venv package detection (fixes install failures on newer Python versions where Ubuntu splits the venv package by version, e.g.
python3.14-venv)
Fixed
- ASCII render mode (
--style ascii) now forces a solid black background behind every character, removing terminal-theme-colored gaps between characters while preserving true per-pixel video colors - Improved handling of YouTube extraction failures related to missing JS runtime support
Notes
- The Debian/Ubuntu install path has been directly tested end-to-end on a clean VM
- Fedora/Arch/macOS install paths are implemented but less thoroughly tested — feedback and bug reports from users on these platforms are welcome
- See the README for guidance on balancing rendering detail (
--cols), FPS, and playback smoothness based on your terminal and hardware
Built solo as part of the protagonist.lab project series.
v1.0.1-hotfix
TermTube v1.0.1
Patch release fixing YouTube extraction failures caused by missing JS runtime support and stale yt-dlp versions.
Fixed
- Resolved
This video is not availableerrors on videos that require JavaScript execution to decode YouTube's signature cipher - Added automatic detection and use of the Deno JS runtime during stream extraction, when available
- Added automatic yt-dlp update-and-retry flow when extraction fails due to an outdated yt-dlp version
Added
--update/-uflag to manually update yt-dlp to the latest version without needing a video URL- Setup script now automatically installs Deno if it isn't already on PATH
- Clearer diagnostic logging: resolver now reports whether the Deno runtime is being used, and prompts a rerun after an automatic yt-dlp update instead of silently continuing with stale state
Notes
- If you still hit resolution errors after updating, confirm Deno is installed and available on PATH (
deno --version) — a fresh terminal session may be required after installation for PATH changes to take effect - No changes to rendering, audio sync, or CLI playback behavior in this release
Full diff and details in the linked pull request.
v1.0.0
TermTube v1.0.0
Stream any YouTube video straight into your terminal — real-time video rendered as colored text, with fully synced audio. No browser, no video player, no GUI. Just Python, ffmpeg, and numpy turning pixels into characters, live.
Features
- Live YouTube resolution via yt-dlp — no downloading, prefers 720p with locked 16:9 aspect ratio
- Two render styles:
halfblock(high-density colored blocks) andascii(classic density-character text art), plus custom--rampsupport - Synced audio playback via ffplay, waits for audio to finish naturally instead of cutting it off early
- Clock-driven AV sync with automatic frame-drop recovery to prevent drift on longer videos
- Fast numpy-vectorized rendering, well under 2ms/frame even at 720p
- Auto-detects terminal size to fill your window (or set manually with --cols)
- Startup benchmark + live drift logging + frame-drop summary at exit
Requirements
- Python 3.10+
- ffmpeg and ffplay on PATH
- yt-dlp, numpy
Known Limitations
- Minor drift possible on long videos under heavy load or unstable network
- Tested mainly on Windows Terminal / PowerShell
- No seek/pause controls yet, no playlist support