tvplay

tvplay is a high-performance command-line video player written in Go. It renders video files or streams directly in your terminal using ANSI escape codes, pushing the boundaries of what's possible in a text-based interface.

Features

• Multiple Rendering Modes:
  • Color (-mode color): Uses 24-bit TrueColor ANSI codes with half-block characters (▀) for vibrant, full-color playback.
  • Braille (-mode braille): Leverages Unicode Braille patterns (U+2800 range) to achieve 8x higher resolution (4x2 pixels per character cell) than standard text blocks.
  • High-Performance B/W (-mode bw-high): An optimized grayscale mode using Braille characters. It processes 1-byte grayscale data instead of 3-byte RGB, maximizing performance and detail while minimizing CPU usage.
• Audio Support: Plays synchronized audio alongside video (requires ffplay).
• Streaming Support: Seamlessly plays videos from YouTube, Twitch, and other platforms by automatically resolving URLs with yt-dlp.
• Responsive: Automatically detects terminal dimensions to maximize the viewing area.
• Robust: Built with a modular architecture and 100% test coverage.

Requirements

• Go 1.20+ (to build from source)
• FFmpeg: Both ffmpeg and ffplay must be installed and available in your system PATH.
• yt-dlp: (Optional) Required if you want to play videos from URLs.
• Terminal: A modern terminal emulator with support for:
  • TrueColor (24-bit color)
  • Unicode/UTF-8 (for Braille characters)
  • Recommended: iTerm2, Alacritty, Kitty, WezTerm, or VS Code Integrated Terminal.

Installation

Build Locally

Clone the repository and build the binary:

git clone https://github.com/yourusername/tvplay.git
cd tvplay
go build -o tvplay ./cmd/tvplay

Usage

The basic syntax is:

./tvplay [flags] <input>

Flags

• -fps <int>: Set the target frames per second (default: 24).
• -mode <string>: Choose the rendering mode. Options:
  • color (default): Standard color rendering.
  • braille: High-resolution color rendering using Braille dots.
  • bw-high: High-resolution grayscale rendering (fastest).

Examples

Play a local video file in color:

./tvplay my_movie.mp4

Play a YouTube video in high-resolution Braille mode:

./tvplay -mode braille "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

Play a video in high-performance B/W mode (best for detail/speed):

./tvplay -mode bw-high -fps 30 path/to/video.mkv

Project Structure

The project follows a clean, modular architecture:

• cmd/tvplay: Main entry point and CLI argument parsing.
• pkg/player: Orchestrates the playback loop, synchronizing decoding and rendering.
• pkg/decoder: Wraps ffmpeg to stream raw pixel data (RGB or Grayscale).
• pkg/render: Handles the conversion of pixel data into ANSI escape sequences and Unicode characters.
• pkg/stream: Integrates with yt-dlp to resolve streaming URLs.

Testing

The project maintains 100% code coverage. You can verify this by running:

go test -coverprofile=coverage.out ./...
go tool cover -func=coverage.out

License

MIT