CliPlayer

Matrix / ASCII CLI Video Player — renders videos as real-time Matrix Green ASCII Art directly in your terminal!

Current version: 0.0.6 Beta (beta testing — not a stable release)

Features

• 🎬 Real-time video-to-ASCII conversion using OpenCV
• 🟢 Matrix Green color palette with dynamic brightness levels (also amber, cyan, white, rainbow)
• 🔊 Audio playback via ffplay
• ⏯️ Playback controls: pause, speed up, slow down, seek (±5s / ±30s / 0–90% jump)
• 🔁 Loop mode for continuous playback
• ⌨️ Keyboard-driven controls
• 🖥️ Alternate-screen rendering (your scrollback stays intact)

Requirements

• Python 3.8+
• OpenCV — Python library for reading video frames
• NumPy — fast array math for the renderer
• FFmpeg — external command-line tools for audio playback
  • ffplay — handles audio playback
  • CliPlayer does not use the ffmpeg-python wrapper; it relies on OpenCV for metadata and ffplay for audio

Install Dependencies

pip install -r requirements.txt

Install FFmpeg

FFmpeg is an external program required only for audio playback. Make sure ffplay is on your PATH:

• Windows: winget install ffmpeg or download a build from https://ffmpeg.org/
• Debian/Ubuntu: sudo apt install ffmpeg
• macOS: brew install ffmpeg

Usage

python CliPlayer.py <video_file> [options]

Examples

python CliPlayer.py video.mp4
python CliPlayer.py video.mp4 --loop
python CliPlayer.py video.mp4 --start 10 --speed 1.5 --no-audio
python CliPlayer.py video.mp4 --fps 30
python CliPlayer.py --version

Options

Flag	Description
file	Path to the video file
--version	Show the version and exit
--loop	Loop the video indefinitely
--start SECONDS	Start playback at a specific time (seconds, must be >= 0)
--fps FPS	Override the frame rate (must be > 0)
--speed SPEED	Playback speed multiplier (default: 1.0, must be > 0)
--theme THEME	Color theme: matrix (default), amber, cyan, white, rainbow
--chars CHARS	Characters used for the ASCII render
--brightness N	Brightness correction, clamped to -255..255
--contrast N	Contrast correction, clamped to -255..255
--no-audio	Disable audio playback

Keyboard Controls

Key	Action
Space	Pause / Resume
+ / =	Increase playback speed
-	Decrease playback speed
← / [ / ,	Seek back 5 seconds
→ / ] / .	Seek forward 5 seconds
↑ / }	Seek forward 30 seconds
↓ / {	Seek back 30 seconds
0–9	Jump to 0%–90% of the video
Q / Esc	Quit

How It Works

1. Frames are read from the video using OpenCV
2. Each frame is resized to fit the terminal dimensions
3. Pixels are mapped to ASCII characters based on brightness
4. Brightness-dependent ANSI colors are applied (vectorized with NumPy)
5. The ASCII frame is rendered in the alternate screen buffer in real time

Development

pip install -e .[dev]
python -m pytest tests -q

Building

Build a standalone Windows executable using PyInstaller.

Prerequisites

pip install pyinstaller

Build Command

python build.py
# Output: dist/CliPlayer.exe

The build script derives the version from __version__ in CliPlayer.py and cleans stale build/, dist/ and CliPlayer.spec artifacts first.

Or use the Windows shortcut script:

• Windows: build.bat

License

MIT