GitHub - pj4533/richpixelvid: Play videos in your terminal using rich-pixel

2 min read Original article ↗

Rich-Pixel Video Player

Play videos in your terminal using Unicode half-block characters (▄) for a unique retro-style visualization.

Demo

Rich-Pixel Puppy Example

Installation

Prerequisites

  • Python 3.7+
  • ffmpeg (must be installed and in PATH)

Install ffmpeg on macOS:

Install ffmpeg on Ubuntu/Debian:

sudo apt update
sudo apt install ffmpeg

Install Rich-Pixel Video Player

# Clone the repository
git clone [your-repo-url]
cd richpixelvid

# Install in development mode
pip install -e .

Usage

Basic playback

Options

  • --fps <number>: Set playback frame rate (default: auto, max 15 fps)
  • --loop: Loop video playback continuously
  • --width <number>: Set video width in terminal characters
  • --height <number>: Set video height in terminal rows

Examples

# Play at 10 fps
richpixelvid video.mp4 --fps 10

# Loop playback
richpixelvid video.mp4 --loop

# Combine options
richpixelvid video.mp4 --fps 12 --loop

How It Works

Rich-Pixel Video uses the Unicode "Lower Half Block" character (▄) to achieve double vertical resolution in the terminal. Each character cell represents two pixels vertically:

  • The upper pixel uses the background color
  • The lower pixel uses the foreground color

This technique, combined with the rich-pixels library, creates a distinctive visual style perfect for terminal-based video playback.

Features

  • Automatic terminal size detection and video scaling
  • Smooth playback with configurable frame rate
  • Memory-efficient streaming (no temp files)
  • Support for various video formats (mp4, avi, mov, mkv, etc.)
  • Loop playback option
  • Graceful interrupt handling (Ctrl+C)

Limitations

  • No audio playback (video only)
  • Performance depends on terminal emulator capabilities
  • Best viewed in terminals with good Unicode and color support
  • Large videos may require lower frame rates for smooth playback

Future Plans

See IMPLEMENTATION_PLAN.md for the complete roadmap including:

  • Export to various formats (HTML, GIF, video)
  • Streaming support (YouTube, webcam)
  • Advanced playback controls (pause, seek, speed)
  • Network streaming capabilities
  • Plugin system for custom renderers

License

MIT

Credits

Built with: