video-to-ascii 1.3.1

It is a simple python package to play videos in the terminal

It's a simple python package to play videos in a terminal using ASCII characters.

Translations

• 🇺🇸 English
• 🇪🇸 Español
• 🇹🇼 繁體中文

Requirements

• Python3
• PortAudio (Only required for installation with audio support)
• FFmpeg (Only required for installation with audio support)
• Linux or MacOS ... for now

Installation

From PyPI (Recommended)

Standard installation (without audio support):

$ pip install video-to-ascii

With audio support:

$ pip install video-to-ascii[audio]

Complete installation (with all optional dependencies):

$ pip install video-to-ascii[all]

🔄 Migration Guide

If you were using the old installation method with --install-option:

# ❌ Old way (no longer supported)
$ pip install video-to-ascii --install-option="--with-audio"

# ✅ New way  
$ pip install video-to-ascii[audio]

Note: The --install-option flag has been deprecated by pip and removed in pip 23.1+.

From Source

Clone the repository and install:

$ git clone https://github.com/joelibaceta/video-to-ascii.git
$ cd video-to-ascii
$ pip install .

Or with audio support:

$ pip install .[audio]

How to use

Just run video-to-ascii in your terminal

$ video-to-ascii -f myvideo.mp4

Options

--strategy Allow to choose a strategy to render the output.

-o --output Export the rendering output to a bash file to share with someone.

-a --with-audio If an installation with audio support was made, you can use this option to play the audio track while rendering the video ascii characters.

How it works

Every video is composed by a set of frames that are played at a certain frame rate.

Since a terminal has a specific number of rows and columns, we have to resize our video to adjust to the terminal size limitations.

To reach a correct visualization of an entire frame we need to adjust the frame height to match the terminal rows, avoiding using more characters than the number of terminal columns.

When picking a character to represent a pixel we need to measure the relevance of that pixel's color in the frame, based on that we can then select the most appropriate character based on the relative luminance in colorimetric spaces, using a simplified version of the luminosity function.

Green light contributes the most to the intensity perceived by humans, and blue light the least.

This function returns an integer in the range from 0 to 255, we assign a character according to density to show more colored surface for areas with more intense color (highest values).

CHARS_LIGHT 	= [' ', ' ', '.', ':', '!', '+', '*', 'e', '$', '@', '8']
CHARS_COLOR 	= ['.', '*', 'e', 's', '@']
CHARS_FILLED    = ['░', '▒', '▓', '█']

The reduced range of colors supported by the terminal is a problem we need to account for. Modern terminals support up to 256 colors, so we need to find the closest 8 bit color that matches the original pixel in 16 or 24 bit color, we call this set of 256 colors ANSI colors.

Finally, when putting it all together, we will have an appropriate character for each pixel and a new color.

Contributors

Code Contributors

This project exists thanks to all the people who contribute. [Contribute].

Financial Contributors

Become a financial contributor and help us sustain our community. [Contribute].

Or maybe just buy me a coffee.

Individuals

Organizations

Support this project with your organization. Your logo will show up here with a link to your website. [Contribute]

As Seen On