Media-To-Ascii

CLI and utilities for converting media files (images/videos) to ascii outputs (output media file or print to console).
Supports most standard image formats, and some video formats.

Only output format for videos is .mp4 at the moment

Examples

mediatoascii is capable of extremely high quality ascii images/videos (click on the images below to see the full resolution), or the usual fun scaled-down ones!

Videos

(From https://www.tiktok.com/@swishanime_/video/7143035431066602794)

Or for a more high quality version: https://i.imgur.com/vRJMpA1.mp4

Images

&&&#&&&&GP&&&&&&G&G#&G5J#J#PPP#&JGG7#GPYGGPP5GGPPJGGGP55G5#JGPPP7JJ557JP5JY55JYJPPPY75PJ5PPPPPPP555JJ55JJJJ
&#&&&&&&P5GG&&&&P&#G&&Y5J5JY55YGGJ55#BBBPPG555PPJJJPGG557G5GPP55555YJJYPP5JJ5Y55PYPPPPPPPPPPP555555JJP5JJJ5
P&&#&&&&5JGY#GG&&&&?JJ5?YGG?J5G?BBBBBBBBJ#G5JJJJ5JJY5555JJ55P5J75P?Y?JP75555PP5Y?PPPPPYYJJJ5PY#JJJ55P575
5P#P#&YG7#57&&&&YJPGPPGPPGG5&BBBBBBBBBGGGGJGG5555PP5J555JPJ7GBBBBBBPPY55PYPPPPP?JG@@@@@@@YY5555555557
5J#5P###5Y5JP5P#55GYPPPPPPPPPYJJYGBBBBBBBBBBBBBBBBB&#PJYJGYJJYBBBBBBBBBBBB7PPPYP5PPPJB@@@@@@@B7P5PPP555555P
5YP55GP#PJY5~55GPPPPPPPPPPPPPPPPYBBBBBBBBBBBB7JGBGJYBBBBBBBBBBBBBBBBBBBBBB7JJJ55JYJ?P&@@@@GG?55J777777J5PPP
YJ5JJ5YJG&&&&&J?GJ&#Y5PPPPPPPPPYBBBBBBBBBBBBBBB5YYY7BBG7BBBBBBBBBBBBBBBBBB7JJJPPJ5YP55PPG#~?7YYJJJJJ5PP5557
#&&#######&#######&##7JJ7YJJJ5Y&BBBBBBBBBBBBBB7YYYYYY&BBBBBBBBBBBBBBBBBBBB7PPPPPPGJ5555Y?555555555J###GGGP5
##&&#&&&&&&&GGJJ#GP5PPPPPPPPPP5BBBBBBBBBBBBBBBYYYYYY7BBBBBBBBBBBBBBBBBBBB#??7?JPP75555Y~PPP5JY555575###PJYG
&&&GYPPPPPPPPPPPJYYY77?JPJPPPY&BBBB&&&&&&&&&&&B&&&&&&BBBBBBBBBBBBBBBBBBB&?GPPPPPG~55557PJJPJ5J57#G7PPPPP5#7
&#JPGYJJ575PYPPP5PP5PPPPPPPP7YJ55555555555575555555555YY#&&BB&&&&&&B&&&#PYGGGGGGGY555Y?PPPPPPJYPPP5J5?7P~YY
&&&&&&&&&&&P5#PPJJYYYPPP7?7B?555555JJ55YJ555J5555555J7555555Y7P&&&&&&&G555GGGGGG55555Y?GPPPPPPPPJ5JYP???YYY
BBBBBBBBB&&&&&&&&&&&&&&&&&&P55557@@@@@@@@&J555555555555JYY77555557J##555YJPGGGGGY55557PGGGPPPPPPPPJJPPPPJ5P
BBBBB&BBBBBBBBBBBBBBBBB&&&&75555@@@Y~~~7@@Y5555555555Y@@@@@@@BY5555J7J55?#######?55557#GGGGGGJJPPP55P?P555Y
Y5B&PJ@@BBBBBBBBBBBBBBBBBBBY55Y@@@&~~~~~@@P555555557@@@&~~~?B@@Y5555J7?7&&&&&&#G~555J~GY777Y5J??P7?5PPGGPGY
7JY?7JYGBJ@@@@B@BBBBBBBBBBB5557@@@@@GP#@@@J5555555JB@@B~~~~~5@@@Y555Y7?B&&G5&&PJY55577PPPP5J55PPPPPPP55PPPP
PP?57Y77JJBB@GPJ77JGBB@BBBBJ555P@@@@@@@@@#555555557@@@@&~~~G@@@@Y55577?BBB&&&&&5555575P&P###GPPP77YJ555JP55
YY5&@&?JY&BBB@@@@@@@@@@@@#555P555JJ5P5YY555JJ555555J@@@@@@@@@@@7555J77#BBBBBB&B?555Y?&&&#########5GPG7J7JYY
@GP5@BBBBBBBB@@@@BB@@BB@@Y55G&�J~:Y55555557#@@@@@@B?5555777BBBBBBBBG55557&&&###############G###G
BBBBBBBBBBB@@@@@@@@@@@@@@?555555555555555JJ7J55555555555555PP55555J7?BBBBBBBBB7555Y7&&#####################
@@@@@@@@@@@@@@@@@@@@@@@@G5Y?J5J55JJ555JJJ5JJJ77YYJ555555555PGG55JJY?YY5BBBBBB755JJ?&&&&&&&&&&&#############
@@@@@@@@@@@@@@@@@@@@@@@@@@@B?7JJJJJJJJJJJJJJJJJJJJJ55JJ555555JJJJY7:YYYY5BBB55J5Y7#B&&&&&&&&&&&&###########
@@@@@@@@@@@@@@@@@@@@@@@@@JYYYYY7~7JJJJJJJJJJJJJJJJJJJJJJJJJJJJ?Y~:7YYYYYY7&G77Y77#BBBBBBBBB&&&&&&&&&&&&&&&&
@@@@@@@@@@@@@@@@@@@@@@@PYYYYYYYY??JY~?77JJJJJJJJJJJJJJJJJY77??:???YYYYYYYYY~7777GBBBBBBBBBBBBBBBBBB&&&&&&&&
@@@@B@@@@@@@@@@@@@@@@B7YY???755JJJJJJ~?P^::?~~:~::::~~??:Y~~????7YYYYYYYYYYY:7?BB@@@@@@@@@@@BBBBBBBBBBBBBBB
BBBBBBBBBBBBBBBBBBBBB?Y~J5JJJJJJJJJYJPPPY~:Y^7777?YG77JJJJJJJJY^?YYYYYYYYYYY7GB@B@@@@@@@@@@BBBBBBBBBBBBBBBB
BBBBBBBBBBBBBBBBBBBBJYYY7Y7?~~::::GPPPPP?5&BYG?PPPP57JJJJJJJJJJJJJ77YYYYYYYY7?BBBBBBBBBBBBBBBBBBBBBBBBBBBBB
BBBBBBBBBBBBBBBBBBB&~YYY77777Y7????:Y#&BBBBBB&?JPPPPP?JJY~YJJJJJJJJJJJ?7Y77Y?~BBBBBBBBBBBBBBBBBBBBBBBBBBBBB
&&&&&&B&&&&&&&&&&&&G~7777777777?~7GJPBBBBBBBBBBB5PPPP7JY77B&??~^YJJJJJJ7?777?:B&&&&&&&&&&&&&&&&&&&&&&&&&&&&
&&&&&&&&&&&&&&&&&&&P:?7777777777~G7J#&&&&BB&&&&&&&&&BY???:&&~~77777~JJ~:777?~7&&&&&&&&&&&&&&&&&##&#########
&&&&&&&&&&&&&&&&&&&&Y:77777777777?5#G7G&&&&&&&&&&&&P5??~7J~~77777777777777?~7&####################GGGGGGGGG
&&&&&&&&&&&&&&&&&&&&PP^?777777777777??5GGG5Y7????~~?YYY~?777777777777777??:YP#############GGGGGGGGGGGGGGGGG
&&&&&#########&&&&#&##J7~?77777777777777777777777777777777777777777777?~~~?#########GGGGGGGGGGGPPPPPPPPPPPP
#######################YP~:?777777777777777777777777777777777777777?~~::5P#########GGGGGGGGGGGGGPPPPPPPPPPP
#########################Y55^~~?7??77777777??7777??????7777777??~~~::P?G#GGGGGGGGGGGGGGGGGGGGGGGGPPPPPPPPPP
#########################G##7YP~::~~~~????????????????????~~~~~::JP?JJJJJGGGGGGGGGGGGGGGGGGGGGGGGGGPPPPPPPP
GGGGGGGGGGGGGGGGGGGGGGGGGJJJJJY7~YPY:::::~~~~~~~~~~~~~~:::::YPY~7:JYYYYYYYPGGGGGGGGGGGGGGGGGPPPPPPPPPPPPPPP
GGGGGGGGGGGGGGGGGGGGGGGGJJJJYYYYJJ?:77?~~7J555JJJJJY7?::::::YYY?YYYYYYYYYYYPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPP
GGGGGGGGGGGGGGGGGGGGGGGGYJJYYYYYJ:~~~~~~~7JJYYYYYY7:~77777?~^^YYYYYYYYYYYYYPPPPPPPPPPPPPPPPPPPPPPPP55555555
GGGGGGGGGGGGGGGGGGGGGGGPPPYYYYYY^~~~~~~~~YYYYYYYYYYYYYYY~~~~~:YYYYYYYYYYYY5PPPP5555555555555555555555555555
PPPPPPPPPPPPPPPPPPPPPPPPPPPPPYYYYY::~YYYYYYYYYYYYYYYYYY:~~~~~~:YYYYYYYY555555555555555555555555555555555555
PPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPJYYYYYYYYYYYYYYYYYYYYYY^~:~:~:777Y5555555555555555555555555555555555JJJJJJJ
PPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPP55JY777777777777777777YJ55555555555555555555J5JJJJJJJJJJJJJJJJJJJJJJJJJJ

How To Use

Basic Usage

Videos

# Playing videos as ascii art in the console (warning, for large videos, this may cause flickering on certain terminals)
mediatoascii --video-path 

# Saving ascii art as a video file (only .mp4 is supported as the output format)
mediatoascii --video-path  -o ascii.mp4

# Scale down the video by 2x so file size is smaller in storage and resolution
mediatoascii --video-path  -o ascii.mp4 --scale-down 2.0

Images

# Converting images to ascii in the console
mediatoascii --image-path 

# Outputting ascii images in an image file
mediatoascii --image-path  -o ascii.png

# Outputting ascii images as ascii text in a file
mediatoascii --image-path  -o ascii.txt --as-text

For the full set of features, see the `--help` menu:

$ mediatoascii --help
mediatoascii 0.1.0
spoorn
CLI and utilities for converting media files (images/videos) to ascii outputs (output media file or
print to console).
Supports most standard image formats, and video formats.

USAGE:
    mediatoascii [OPTIONS] <--image-path |--video-path >

OPTIONS:
        --image-path 
            Input Image file.  One of image_path, or video_path must be populated

        --video-path 
            Input Video file.  One of image_path, or video_path must be populated

        --scale-down 
            Multiplier to scale down input dimensions by when converting to ASCII.  For large
            frames, recommended to scale down more so output file size is more reasonable [default:
            1]

        --height-sample-scale 
            Rate at which we sample from the pixel rows of the frames.  This affects how stretched
            the output ascii is in the vertical or y-axis [default: 2.4]

    -i, --invert
            Invert ascii greyscale ramp (For light backgrounds.  Default OFF is for dark
            backgrounds.)

        --overwrite
            Overwrite any output file if it already exists

        --max-fps 
            Max FPS for video outputs.  If outputting to video file, `use_max_fps_for_output_video`
            must be set to `true` to honor this setting.  Ascii videos in the terminal default to
            max_fps=10 for smoother visuals

        --as-text
            For images, if output_file_path is specified, will save the ascii text as-is to the
            output rather than an image file

    -o, --output-file-path 
            Output file path.  If omitted, output will be written to console. Supports most image
            formats, and .mp4 video outputs

        --use-max-fps-for-output-video
            Use the max_fps setting for video file outputs

    -r, --rotate 
            Rotate the input (0 = 90 CLOCKWISE, 1 = 180, 2 = 90 COUNTER-CLOCKWISE)

    -h, --help
            Print help information

    -V, --version
            Print version information

Installation

Prerequisite: OpenCV

OpenCV 4.x is required on the system.

mediatoascii depends on OpenCV Rust Bindings which require the OpenCV C++ libraries to be installed. See below for instructions on different systems. This should be a one-time setup.

Ubuntu/Linux/WSL2

You'll need to be on Ubuntu 20.04+ for OpenCV 4.x.

To check Ubuntu version:

lsb_release -a

If you are on an older version of Ubuntu, see various tutorials for updating your system.

Install OpenCV and related libs:

sudo apt install libopencv-dev clang libclang-dev

Check OpenCV version:

dpkg -l | grep libopencv

MacOS

Install OpenCV:

brew install opencv

Check OpenCV version:

brew info opencv

Windows

Currently only supported through WSL2 - allowing a Linux subsystem with a terminal to run on Windows: https://learn.microsoft.com/en-us/windows/wsl/install.

Then you can follow the Ubuntu setup above.

Note: on WSL2, drives in paths are prefixed with /mnt/c/ rather than C:/

Arch Linux

Install OpenCV:

pacman -S clang qt5-base opencv

Installing mediatoascii

Below are different ways you can install mediatoascii

[Optional] Cargo

If you choose an installation method below that involves the cargo command, you'll want to install the rust toolchain which includes cargo if you don't already have it: https://doc.rust-lang.org/cargo/getting-started/installation.html

[Recommended] Cargo binstall Binaries

# Install cargo-binstall
cargo install cargo-binstall

# Install mediatoascii
cargo binstall mediatoascii

Portable Binaries

Pre-compiled binaries are available to download and use immediately under Releases. These don't require compiling/building dependencies so installation is much faster. Select the one for your system

mediatoascii-x86_64-unknown-linux-gnu for Linux-based systems (Ubuntu/WSL2/etc.)
mediatoascii-x86_64-apple-darwin for macOS

Extract the artifacts, then you can then run the binary like any shell/script file in a terminal e.g. ./path/to/mediatoascii |`cd path/to/mediatoascii && mediatoascii , or you can add it to your system PATH so it can be run from any directory. You can easily find tutorials on the internet for "add a binary file to system PATH" for your OS system.

Crates.io

cargo install mediatoascii

Git

# Clone repository and cd into it
git clone ...
cd mediatoascii/

# Install the package into cargo
cargo install --path .

# OR run the pre-packaged binary in bin/
./bin/mediatoascii ...

# OR via `cargo run`
cargo run --release

Troubleshooting

If you're trying to update Ubuntu on WSL2, you may run into silent failures during the upgrade
- See https://askubuntu.com/questions/1340153/how-to-upgrade-ubuntu-18-04-to-20-04-in-wsl-when-wsl-export-fails
error while loading shared libraries: libopencv_videoio.so.4.2: cannot open shared object file: No such file or directory
- Make sure you have OpenCV 4.x installed