🎬 Transform YouTube into ASCII cinema - right in your terminal

Because who needs 4K when you have 80 columns.

Features • Demo • Installation • Usage • Options • Dependencies

---

Features

• Stream YouTube videos as ASCII art in real-time
• Full color support with ANSI colors
• Synchronized audio playback
• Multiple charset presets for different styles

---

Demo

demo.mp4

# One command. Instant ASCII cinema.

stdout-tv play "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

---

Installation

Prerequisites

Note: Make sure you have Rust installed (1.75+)

From Source (Recommended)

# Clone the repository
git clone https://github.com/SameerVers3/stdout-tv.git
cd stdout-tv

# Build with Cargo (optimized release build)
cargo build --release

# Run it!
./target/release/stdout-tv --help

Quick Install Script

# One-liner install
curl -sSL https://raw.githubusercontent.com/SameerVers3/stdout-tv/main/install.sh | bash

Add to PATH

# Linux/macOS - Add to your local bin
sudo cp ./target/release/stdout-tv /usr/local/bin/

# Or symlink it
ln -s $(pwd)/target/release/stdout-tv ~/.local/bin/stdout-tv

---

Usage

Play a Video

# Basic - just paste the URL
stdout-tv play "https://www.youtube.com/watch?v=VIDEO_ID"

#  Custom size (height auto-calculated for 16:9)
stdout-tv play "<url>" --width 120

#  Experiment with charsets
stdout-tv play "<url>" --charset-preset dense    # More detail
stdout-tv play "<url>" --charset-preset blocks   # Pixel art vibes

#  Silent mode (no audio)
stdout-tv play "<url>" --no-audio

#  Invert colors (for light terminals)
stdout-tv play "<url>" --invert

#  Custom FPS (default: source video FPS)
stdout-tv play "<url>" --fps 30

Get Video Info

stdout-tv info "https://www.youtube.com/watch?v=VIDEO_ID"

Example Output

Title: Never Gonna Give You Up
Uploader: Rick Astley
Upload Date: 20091025
Duration: 3m 32s
View Count: 1500000000
Like Count: 15000000

Description:
The official video for "Never Gonna Give You Up" by Rick Astley...

Tags:
rick astley | never gonna give you up | rickroll | 80s |

Check Dependencies

stdout-tv check

Checking dependencies for stdout-tv...

✓ yt-dlp found: yt-dlp 2024.12.01
✓ ffmpeg found: ffmpeg version 6.1.1

All dependencies are installed!

---

Options

Play Command Options

Option	Description	Default
--width <WIDTH>	Terminal width in characters	80
--height <HEIGHT>	Terminal height in characters	Auto (16:9)
--fps <FPS>	Frames per second	Source FPS
--charset <CHARSET>	Custom charset (5-50 chars)	—
--charset-preset <PRESET>	Preset: default | dense | blocks	default
--invert	Invert brightness mapping	false
--color	Enable ANSI color output	true
--no-audio	Disable audio playback	false
--yt-dlp-path <PATH>	Custom yt-dlp executable	yt-dlp
--ffmpeg-path <PATH>	Custom ffmpeg executable	ffmpeg

Charset Presets

Preset	Style	Best For
default	@%#*+=-:.	General purpose, balanced
dense	Extended ASCII range	High detail, complex scenes
blocks	█▓▒░	Retro pixel art look

---

🔧 Dependencies

stdout-tv requires these external tools to work its magic:

Tool	Purpose	Install
	Fetches video streams	brew install yt-dlp / pacman -S yt-dlp
	Video processing & audio	brew install ffmpeg / pacman -S ffmpeg

Tip: Run stdout-tv check to verify everything is set up correctly!

---

Project Structure

stdout-tv/
├── Cargo.toml            # Project manifest
├── src/
│   ├── main.rs           # Entry point
│   ├── cli.rs            # CLI with clap
│   ├── utils.rs          # Terminal magic
│   ├── commands/
│   │   ├── play.rs       # The main show
│   │   ├── info.rs       # Video metadata
│   │   └── check.rs       # Dependency checker
│   └── video/
│       ├── yt_dlp.rs     # yt-dlp wrapper
│       └── ffmpeg.rs     # ffmpeg pipeline

---

Contributing

Contributions, issues, and feature requests are welcome!

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Implementation Notes

• This project uses pixel2ascii, a companion crate developed to handle image-to-ASCII conversion efficiently.

---

Made with ❤️ and 🦀 Rust
_{Star ⭐ this repo if you found it useful!}