Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/spoorn/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.
https://github.com/spoorn/media-to-ascii
ascii ascii-art cli image media opencv rust video
Last synced: about 1 month ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/spoorn/media-to-ascii
- Owner: spoorn
- License: mit
- Created: 2022-09-07T04:18:36.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-09-09T09:27:42.000Z (3 months ago)
- Last Synced: 2024-09-09T11:26:13.334Z (3 months ago)
- Topics: ascii, ascii-art, cli, image, media, opencv, rust, video
- Language: Rust
- Homepage: https://crates.io/crates/mediatoascii
- Size: 26 MB
- Stars: 67
- Watchers: 1
- Forks: 3
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-rainmana - spoorn/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. (Rust)
README
# 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 video formats (depends on OpenCV).
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&&&&PG&&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#55GYPPPPPPPPPYJJYGBBBBBBBBBBBBBBBBBPJYJGYJJYBBBBBBBBBBBB7PPPYP5PPPJB@@@@@@@B7P5PPP555555P
5YP55GP#PJY5~55GPPPPPPPPPPPPPPPPYBBBBBBBBBBBB7JGBGJYBBBBBBBBBBBBBBBBBBBBBB7JJJ55JYJ?P&@@@@GG?55J777777J5PPP
YJ5JJ5YJG&&&&&J?GJY5PPPPPPPPPYBBBBBBBBBBBBBBB5YYY7BBG7BBBBBBBBBBBBBBBBBB7JJJPPJ5YP55PPG#~?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
```bash
# 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
# For large videos, or if you see some alignment issues, please see the `--help` menu, notably settings `--scale-down`, `--font-size`, and `--height-sample-scale`
mediatoascii --video-path -o ascii.mp4 --scale-down 2.0
```
### Images
```bash
# 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:
```commandline
$ 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.exe [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. Affects output quality. Note: the output dimensions will also depend on the `font-size` setting [default: 1]
--font-size
Font size of the ascii characters. Defaults to 12.0. Affects output quality. This directly affects the scaling of the output resolution as we "expand" each pixel to fit the Cascadia font to this size. Note: this is not in "pixels" per-se, but will roughly scale the output to a multiple of this [default: 12]
--height-sample-scale
Rate at which we sample from the pixel rows of the frames. This affects how stretched the output ascii is vertically due to discrepancies in the width-to-height ratio of the Cascadia font, and the input/output media dimensions. This essentially lets you shrink/squeeze the ascii text horizontally, without affecting output frame resolution.
If you see text overflowing to the right of the output frame(s), or cut off short, you can try tuning this setting. Larger values stretch the output. The default magic number is 2.046. See https://github.com/spoorn/media-to-ascii/issues/2 for in-depth details [default: 2.046]
-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. Images will be resized to fit the ascii text. Videos will honor the aspect ratio of the input, but resolution will be scaled differently approximately to `(height|width) / scale_down * font_size`
--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
-V, --version
Print version
```
# Installation
Below are different ways you can install **mediatoascii**
## [Recommended] Portable Binaries
> :warning: Note: you may need to disable your antivirus for the downloaded executable if it blocks it
Pre-compiled binaries are available to download and use immediately
under [Releases](https://github.com/spoorn/media-to-ascii/releases). These don't require compiling/building dependencies
so installation is much faster. Select the one for your system
- `mediatoascii-x86_64-pc-windows-gnu` for Windows
- `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.
## [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
## Prerequisite: OpenCV
OpenCV 4.x is required on the system if you are not using the pre-compiled binaries installation, which has OpenCV
statically linked into the executable.
**mediatoascii** depends on [OpenCV Rust Bindings](https://github.com/twistedfall/opencv-rust) which require the OpenCV
C++ libraries to be installed.
See https://github.com/twistedfall/opencv-rust#getting-opencv for instructions on different systems.
Below is an abbreviation
### 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](https://www.nextofwindows.com/how-to-upgrade-existing-wsl-wsl2-ubuntu-18-04-to-20-04).
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
#### Direct
Follow https://github.com/twistedfall/opencv-rust#windows-package (recommend chocolatey route).
Make sure you set the environment variables `OPENCV_LINK_LIBS`, `OPENCV_LINK_PATHS` and `OPENCV_INCLUDE_PATHS` properly,
according to https://github.com/twistedfall/opencv-rust/issues/118#issuecomment-619608278
Also, make sure the opencv `bin/` is in your PATH: https://github.com/twistedfall/opencv-rust/issues/113
If you see this error (or some other ones):
```bash
CMake Error at ports/atlmfc/portfile.cmake:7 (message):
Unable to locate 'afxres.h'. Ensure you have installed the ATL/MFC
component of Visual Studio.
```
Make sure you have Visual Studio installed with `Desktop development with C++`, ATL and MFC checked. In newer versions
of Visual Studio, these may
be [defaulted to disabled](https://learn.microsoft.com/en-us/cpp/mfc/mfc-and-atl?view=msvc-170).
You can install them in the Visual Studio Installer when you modify the Visual Studio installation.
#### WSL
You can also install opencv 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 qt6-base opencv
```
## [Cargo binstall](https://github.com/cargo-bins/cargo-binstall) Binaries
```
# Install cargo-binstall
cargo install cargo-binstall
# Install mediatoascii
cargo binstall mediatoascii
# Run
mediatoascii --help
mediatoascii
```
## Crates.io
```commandline
cargo install mediatoascii
# Run
mediatoascii --help
mediatoascii
```
## Git
```commandline
# Clone repository and cd into it
git clone ...
cd mediatoascii/
# Install the package into cargo
cargo install --path .
# Run via `cargo run`
cargo run --release -- --help
cargo run --release --
```
# Development
You will need `rustup` installed, [OpenCV](#prerequisite:-opencv), and make sure you update any OpenCV environment
variables as per https://github.com/twistedfall/opencv-rust, along with the OpenCV bin folder appended
to `PATH` (
e.g. `C:\tools\opencv\build\x64\vc16\bin`) ([For Example on Windows](https://github.com/twistedfall/opencv-rust/issues/118#issuecomment-619608278)).
# Troubleshooting
1. 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
2. `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
3. `Picture size 12668x22512 is invalid ... global cap_ffmpeg_impl.hpp:3066 open VIDEOIO/FFMPEG: Failed to initialize VideoWriter`
or `dimensions too large for MPEG-4`
- mediatoascii scales up the image when writing ascii frames and there is a frame size limit to mpeg4. Try setting
the `--scale-down` setting to scale down the output resolution.
See https://github.com/spoorn/media-to-ascii/issues/2 for why the image has to be scaled up
4. `error: process didn't exit successfully: `
target\debug\mediatoascii.exe` (exit code: 0xc0000135, STATUS_DLL_NOT_FOUND)`
- Make sure the OpenCV bin folder is in `PATH`