ASCII Video Player

This is a command-line Python application that plays back video (local or YouTube) in ASCII art directly in your terminal. It uses VLC, OpenCV, and PIL (Pillow) to handle video extraction, conversion to ASCII, and audio playback.

Features

• Cross-Platform: Runs on Linux, macOS, and Windows with appropriate setup.

• Local Video Playback: Supply a local file (e.g. movie.mp4).

• YouTube Video Playback: Supply a YouTube URL (-y <URL>); the video is downloaded temporarily.

• Color or Grayscale ASCII: Use -color to get each pixel approximated in 256-color.

• Subtitles: Automatically retrieve YouTube subtitles (-sub / -sub <lang>).

• Frame Skipping: Supply -f <fps> to decode fewer frames, reducing CPU load.

• Dynamic Skipping: Automatic skip of frames to maintain audio-video sync unless -noskip is specified.

• Debug FPS: A real-time FPS indicator in the top-right corner (-debug).

• Caching: Extract frames once (-write), then reuse them (-c) for faster subsequent playback.

Requirements

• Python 3.6+ (for f-strings, etc.)
• VLC installed on your system (the vlc Python module relies on VLC).
• OpenCV (pip install opencv-python).
• Pillow (pip install pillow).
• yt-dlp for YouTube downloading.
• pytube (for some YouTube metadata extraction).
• youtube_transcript_api (for subtitles).

Installation

1. Install VLC:

   • Linux: Install VLC using your package manager:

     sudo apt-get update
     sudo apt-get install vlc

   • macOS: Download and install VLC from here.
   • Windows: Download and install VLC from here. Ensure the VLC binary is added to your system PATH.

2. Install Python dependencies:

   pip install opencv-python pillow yt-dlp pytube youtube_transcript_api python-vlc

Usage

python player.py [options] <local_file> or -y <YouTubeLink>

Options:
  -y <link>    Play a YouTube video (downloads it first).
  -c           Use cached frames (skip extraction/resizing from disk).
               (Requires that you previously used -write so 'resized/' is populated
               with .png files and metadata.)
  -write       Store frames on disk in PNG format (lossless). This creates
               two loading bars: one for extraction, one for resizing.
               Without this, frames are handled purely in memory (one bar).
  -sub [lang]  Enable YouTube subtitles; optional language code.
  -f <fps>     Set a custom ASCII framerate (fewer frames per second).
               Audio still plays at normal speed (frames may be skipped).
  -noskip      Disable dynamic skipping (video may get out of sync).
  -nocompute   Do not precompute frames into memory; compute and render frames live during playback.
               This reduces memory usage at cost of performance, suitable for larger videos.
  -debug       Show live FPS (frames drawn per second) top-right.
  -color       Enable color approximation (each pixel is a colored block).
  -h, -help    Show this help message and exit.

Examples

1. Play local file at default FPS:

   python player.py movie.mp4
   

2. Download and play YouTube video in ASCII, with subtitles:

   python player.py -y https://www.youtube.com/watch?v=XYZ -sub en
   

3. Write frames to disk for faster later playback:

   python player.py -write myvideo.mp4
   

   Then, to use those frames later:

   python player.py myvideo.mp4 -c
   

4. Force ASCII playback at 10 FPS:

   python player.py movie.mp4 -f 10
   

Sample Videos

There are 4 sample videos in the sample_video folder that you can use to test color, timing, and audio playback. They are handy for experimenting with features like -color, -f <fps>, or playback delay

Notes

• Performance: Color mode uses the most performance, you can save performance by running at a lower resolution, or a lower framerate by using a custom framerate with -f <fps> (for example 25).
• Plaback lag: If you have low FPS at playback, the only option is to reduce the resolution, or switch from color to grayscale.
• Caching: When running with -write, the script writes frames in frames/ and resized frames in resized/, plus a resized/metadata.txt for future verification (used by -c).
• Frame Skipping: If you provide -f <fps> and that FPS is lower than the source, only approximately (Video_FPS / <fps>) frames are decoded. This significantly reduces CPU usage for high-FPS sources.
• Color Mode: Using -color can slow down rendering because each pixel is drawn as a colored block. Grayscale ASCII is usually faster.
• Subtitles: Only works automatically for YouTube videos if subtitles are available. If no subtitles exist, no text will be displayed.
• Windows Support: On Windows, ensure VLC is installed and its directory is added to your PATH. If you encounter issues with Python dependencies or paths, use python -m pip for installations and check your VLC installation is accessible from the terminal.

Showcases

Color Mode

Grayscale Mode