🎬 PlayCLI — Terminal Video Player

Real-time video playback in your terminal using ANSI true-color escape sequences, with 5 render modes, audio sync, subtitles, and adaptive quality.

🎯 What It Does

PlayCLI is a real-time terminal video player. It renders videos frame-by-frame directly in your terminal using 24-bit true color ANSI escape sequences — no GUI, no browser, just your shell.

$ playcli video.mp4

It supports 5 render modes, audio sync via your system’s audio device, keyboard controls, subtitles, streaming from URLs, static images, playlists, screenshots (PNG + ANSI HTML), and adaptive quality throttling.

🧱 Tech Stack

Zero external runtime dependencies beyond NumPy and imageio-ffmpeg for the core player. Audio and image extras are optional.

🏗️ Architecture

ascii_play/
├── cli.py          # Entry point, argparse dispatch
├── player.py       # FFmpeg decode loop, audio sync, keyboard input
├── renderers.py    # 5 render modes (MODES dict)
├── resize.py       # Quality levels: nearest, 4-tap, box filter
├── ansi.py         # ANSI escape sequence helpers
├── subtitle.py     # SRT parser + Pillow text overlay

The data flow:

1. cli.py parses arguments and dispatches to the player
2. player.py opens the video via imageio-ffmpeg, reads frames as NumPy arrays, synchronizes to audio via sounddevice (or wall clock if no audio), captures keyboard events via tty.setraw(), and pushes rendered frames to stdout
3. renderers.py converts each NumPy frame into ANSI escape codes using one of 5 modes
4. resize.py downsizes frames to fit terminal dimensions at configurable quality
5. ansi.py provides the low-level ANSI sequences (cursor positioning, RGB color codes, clear screen)
6. subtitle.py parses SRT files and overlays text via Pillow before rendering

All pixel operations are NumPy-vectorized — no Python-level loops over pixels.

🎨 Render Modes

Half-block mode (▀) is the star of the show. Each terminal cell renders one ▀ character with a foreground color (top half) and background color (bottom half), effectively doubling the vertical resolution compared to a single colored character. This gives near-photographic quality in modern terminals that support 24-bit color.

🔊 Audio Sync

PlayCLI uses sounddevice to play audio in a separate thread while the main thread renders video frames. The audio thread tracks the current playback position, and the video loop drops or repeats frames to stay in sync. If sounddevice is not installed, it falls back to wall-clock timing.

⌨️ Keyboard Controls

📦 Key Features

• Adaptive quality: Automatically reduces quality when frame decode falls behind real-time
• Streaming: URL playback via yt-dlp integration
• Playlists: JSON playlist format with shuffle
• Subtitles: SRT file rendering via Pillow with configurable font
• Screenshots: Captures both a PNG image and an ANSI-escape HTML file
• Static images: Display images directly (no video)
• Persistent config: ~/.config/playcli/config.json

🚀 Quick Start

pip install playcli
playcli video.mp4

# Stream from YouTube
playcli https://youtu.be/dQw4w9WgXcQ

# Use ASCII mode
playcli video.mp4 --mode ascii

# Keyboard shortcuts shown at bottom of terminal

💡 Why It’s Interesting

PlayCLI is a showcase of what’s possible with ANSI terminal escape sequences when you push them to their limit. The half-block rendering technique gives surprisingly good video quality using nothing more than stdout output. It’s genuinely useful for quick video previews without leaving the terminal, watching tutorials in a split pane, or just impressing your friends at a meetup.