A terminal ASCII media player. View images, gifs, videos, webcam, YouTube, etc.. directly in the terminal as ASCII art.

Overview

Image description

Terminal Media Player

Crates.io Crates.io License

View images, videos (files or YouTube links), webcam, etc directly in the terminal as ASCII. All images you see below are just made by characters on the terminal command line, drawn really fast.

Table of Contents

Who is it for?

  • You really don't like graphical applications or are working on a computer without graphical capabilities.
  • You are looking for a quick way to convert any visual media to ASCII art.
  • You want to watch a video in the terminal, but you don't want to use mpv or vlc because they're too mainstream.
  • You want to show off your terminal skills to your friends and make them think you're a hacker.

Features

This crate is still in early development, but it already has a lot of features. Here's a list of what it can or can't do:

  • Converts and shows any media to ASCII art in the terminal
  • Supports images/gifs/videos/webcam and YouTube links
  • Any resolution, aspect ratio, and framerate
  • Use any character set as supported by your terminal
  • Handy pause/unpause and char map selection controls
  • RGB Colors (on terminals that support RGB colors)
  • Play sounds
  • Spark joy
  • Full media controls (forward, backward, loop, etc)
  • Subtitles
  • Replace a fully fledged media player

RGB Colors

colors

Live update when updating character size

font_size

On-the-fly character map selection

char_maps

Dynamic resize

resize

Emojis

emojis

Webcam support

webcam

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.

Prerequisites

Being a Rust crate, you will need to have Rust installed on your system. You can find the installation instructions here.

The following dependencies are also required:

They can be simply installed on linux with your package manager. See below for more details.

Prerequisites Installation on Linux

If you're on Linux (Ubuntu), you can install all dependencies with your package manager. First install Rust:

sudo apt install curl
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Then install tplay's prerequisite dependencies:

sudo apt install libopencv-dev clang libclang-dev ffmpeg libavfilter-dev libavdevice-dev libasound2-dev yt-dlp

Prerequisites installation on Windows

The crate can run on Windows and all prerequisites (opencv, ffmpeg) can be installed with vcpkg. However the installation/setup process is lengthy and prone to errors. Performance is also very poor. Save yourself a headache: use WSL and follow the Linux instructions.

Installation

For users

Arch Linux

You can install it on Arch Linux using aur by running the following commands (using paru):

paru -S tplay-git

Other Distros

The package is not currently available on other Linux distros. With contribution and support it can be made available on other distros as well :).

Install Using Cargo

You can install the tplay command line tool by running the following command:

# Install the tplay command line tool
cargo install tplay

So that you can run it from anywhere as

tplay <media> [options]

For developers

# Clone the repository
git clone https://github.com/maxcurzi/tplay.git

# Change to the project directory
cd tplay

# (optional) Build the project
cargo build

# (optional) Run the tests
cargo test

# Run the project (use --release for faster performance)
cargo run --release -- <media> [options]

Feature flags

By default the crate uses rodio for audio playback. If you wish to use MPV (libmpv1 libmpv1-dev) as a audio playback backend, you can build/install the crate with:

--features="mpv_0_35" --no-default-features

or

--features="mpv_0_34" --no-default-features

within cargo build, cargo run, or cargo install commands.

MPV support may be dropped in future releases.

Usage

tplay <media> [options]

Argument Description
media Name of the file or stream to be processed (required).
-f, --fps Forces a specific frame rate (--fps 23.976).
-c, --char-map Custom lookup character table to use for the output (default: .:-=+*#%@).
-g, --gray Start in grayscale mode
-w, --w-mod Experimental width modifier for certain characters such as emojis (default: 1). Use a value of 2 if your char_map is composed of emojis.
-a, --allow-frame-skip Experimental frame skip flag. Try to use if the playback is too slow.
-n, --new-lines Experimental flag. Adds newline and carriage return \n\r at the end of each line (except the last). Terminals wrap around and don't need new lines, but if you want to copy-paste the text outside the terminal you may want them. The output would be a single long string otherwise. Uses more CPU.

Substitute tplay with cargo run --release -- if you plan to run from source.

# Run it
tplay <media> [options]

# Example: local image
tplay ./image.png

# Example: local gif
tplay ./image.gif

# Example: local video
tplay ./video.mp4

# Example: remote video (YouTube)
tplay https://www.youtube.com/watch?v=dQw4w9WgXcQ

# Example: remote video (Other)
tplay https://media.developer.dolby.com/Atmos/MP4/shattered-3Mb.mp4

# Example: YouTube video, with different char maps
tplay https://www.youtube.com/watch?v=fShlVhCfHig --char-map " β–‘β–’β–“β–ˆ"

# Example: YouTube video, with different char maps (use w-mod to adjust width when using emoji-based char maps)
tplay https://www.youtube.com/watch?v=FtutLA63Cp8 --char-map "🍎🍏❀️😊" --w-mod 2

# Example: webcam on Linux (YMMV on other OSes)
tplay /dev/video0

Playback commands

  • 0-9 - change character map (with0 0
  • space - toggle pause/unpause
  • g - toggle grayscale/color
  • m - toggle mute/unmute
  • q - quit

Known Issues

  • Videos played through the Konsole terminal may have reduced performance. This is due to the way Konsole handles terminal output. If you experience this issue, try using a different terminal emulator. I recommend Alacritty for great performance.
  • Media playback is CPU-intensive. To improve performance, increasing font size, reduce the terminal window size, or run with the -a / --allow-frame-skip flag.

Alternatives

This is my ASCII media player: there are many like it, but this one is mine.

For other ASCII media players, check out: https://github.com/search?q=ascii+player&type=repositories

Contributing

Contributions are welcome! Please open an issue or submit a pull request. Some ideas:

  • Reduce external dependencies and streamline installation process.
  • Investigate migration from OpenCV to ffmpeg.
  • More media controls (jump forward, jump backward, loop, etc.).
  • Testing and feedback on installing and running it on other OSes.
  • Let me know if you have any other ideas!

License

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

Why?

Your Scientists Were So Preoccupied With Whether Or Not They Could, They Didn’t Stop To Think If They Should

Mostly did it for fun while learning Rust. I also wanted to see if it was possible to make a video player that could run in the terminal. I think it's pretty cool that you can play videos in the terminal now. I hope you enjoy it too!

Credits

Thanks to the following people for their contributions and support:

Comments
  • panicked at 'Failed to init MPV builder: VersionMismatch { linked: 65644, loaded: 131072 }',

    panicked at 'Failed to init MPV builder: VersionMismatch { linked: 65644, loaded: 131072 }',

    panicked at 'Failed to init MPV builder: VersionMismatch { linked: 65644, loaded: 131072 }'

    mpv 0.35.1-dirty Copyright Β© 2000-2023 mpv/MPlayer/mplayer2 projects
    built on Fri Apr 21 07:11:25 2023
    FFmpeg library versions:
    libavutil 58.2.100
    libavcodec 60.3.100
    libavformat 60.3.100
    libswscale 7.1.100
    libavfilter 9.3.100
    libswresample 4.10.100
    FFmpeg version: n6.0
    

    But it works on the following:

    mpv 0.34.1 Copyright Β© 2000-2021 mpv/MPlayer/mplayer2 projects built on UNKNOWN 
    FFmpeg library versions: libavutil       56.70.100 
    libavcodec      58.134.100 
    libavformat     58.76.100 
    libswscale      5.9.100 
    libavfilter     7.110.100 
    libswresample   3.9.100 
    FFmpeg version: 4.4.2-0ubuntu0.22.04.1
    
    opened by maxcurzi 17
  • Application doesn't work on Arch Linux

    Application doesn't work on Arch Linux

    I was planning to package your commandline app for the aur but it seems like your application doesn't work on arch linux.

    Steps to Reproduce

    How did you install it

    sudo pacman -S yt-dlp opencv clang mpv ffmpeg 
    cargo install tplay
    

    How did you run

    In the home directory:

    ./.cargo/bin/tplay "https://<some-youtube-video-url>"
    
    

    What Happened

    After running the application the program froze with blank terminal with no audio or video playing even waiting for several minutes didn't help.

    Expected Result

    To get a youtube video to be played in the terminal.

    Terminal Used

    Kitty 0.28.1

    Operating System Used

    Arch Linux with linux-zen kernel version 6.2.13

    opened by neon-mmd 6
  •  updating installation instructions, adding subsections, fixing code, removing libmpv code and deleting build.rs

    updating installation instructions, adding subsections, fixing code, removing libmpv code and deleting build.rs

    Since the build.rs didn't work I had to remove it and remove feature based approach in cargo.toml and I had to also change, remove and reimplement some code and now it works just fine with just the rodio crate so I find it unnecessary to have libmpv code in the project and I also updated the installation instructions in the README and under For Users section added several subsections for Arch Linux, Other Distros and Install using Cargo and also added your package to the aur and now it can be easily installed with this command:

    paru -S tplay-git
    

    Also you can view the package here.

    Also here is the screenshot of the application working with just rodio crate: demo

    Note: There seems to be a minor bug that just pops before the video appears and lasts for a few seconds but other than that everything fine.

    opened by neon-mmd 5
  • updating installation instructions and adding subsections

    updating installation instructions and adding subsections

    I updated the installation instructions in the README and under For Users section added several subsections for Arch Linux, Other Distros and Install using Cargo and also added your package to the aur and now it can be easily installed with this command:

    paru -S tplay-git
    

    Also you can view the package here.

    Also one more suggestion, my bad, I forgot to put it in the issues but also write a workflow file this will allow you for automated testing for an example on how to write it. you can take a look at my project's workflow located here.

    opened by neon-mmd 2
  • [BUG] non-integer frame rates are truncated

    [BUG] non-integer frame rates are truncated

    Describe the bug Non-integer framerates like 23.976 are truncated down to 23, etc. This occurs because there is a wrong calculation in the "should send frame" function. It casts self.fps to u64 before performing the division: 1_000_000_000u64 / fps as u64 should be (1_000_000_000f64 / fps) as u64

    opened by maxcurzi 1
  • add credits section

    add credits section

    In this PR I have added a credits section to allow you to thank all the contributors of this project. This is necessary as this will allow people to feel more welcomed towards your project.

    opened by neon-mmd 0
  • Support playback with colors

    Support playback with colors

    Extract RGB information from scaled image and stylize each character with its color info. Update charmaps to better handle the colorization. Outstanding issues to consider:

    - Use only solid blocks when using colors?

    Default ASCII charmap is fine, can switch to solid block after. Other defaults tbc.

    - Allow characters, but the issue is that default char map is chosen to quantize grayscale/luminance. How would it look like when RGB colors (which already contains luminance information) are applied?

    Unresolved, just select the char map that makes it look best for you

    - Add command line flag (color or grayscale by default?)

    Default is color (is a media player, after all), grayscale with flag and live-toggle

    - Will grayscale images/videos work?

    I couldn't find any media that didn't work. More test will be needed on a variety of media files

    opened by maxcurzi 0
  • Allow just audio playback

    Allow just audio playback

    Describe the solution you'd like A media player would be incomplete without an audio-only/music playback feature.

    Additional context Unknowns: what should be displayed in the terminal during playback?

    enhancement 
    opened by maxcurzi 0
  • Investigate feasibility for back/forward

    Investigate feasibility for back/forward

    Ideally, pressing left/right would jump few (say... 5) seconds backward/ahead.

    This feature is not trivial because this is not a traditional media player. The video iterator used by opencv probably allows seeking, as well as the audio player (in theory). Due to the independence of A/V streams, a loss of sync is very possible (and not desirable of course)

    Investigate if jumping ahead/backward is doable without a major rearchitecture

    enhancement help wanted 
    opened by maxcurzi 0
  • Add a loop feature

    Add a loop feature

    Describe the solution you'd like Allow looping of videos, rather than stopping at the end.

    Additional context

    • Ideally the loop can be enabled via command line flag (--loop, -l )

    • A "keypress" to enable loop could also be considered, but at the moment the is no way of visualizing playback status to it may be confusing/not intuitive.

    • Not straightforward to implement (we can't just "seek(0)", videos and audio are played independently. A simple solution could be re-open and re-start playback of video/audio on stream end. Should we keep the same threads alive, or should we spawn new threads when playback ends (at a higher level).

    enhancement 
    opened by maxcurzi 0
  • Clarify external dependencies

    Clarify external dependencies

    Currently the external dependencies include things like MPV and various packages to install in Ubuntu. With the default feature (rodio audio, which uses alsa) the user does not need to install MPV. The readme should clarify what's really needed and what not

    documentation good first issue 
    opened by maxcurzi 0
Releases(v0.4.2)
  • v0.4.2(May 4, 2023)

  • v0.4.1(May 4, 2023)

    What's Changed

    • FIXED #15: Fix frame duration calculation which would cause an incorrect (slow) playback on non-integer framerates (i.e. 23.976 would play at 23 fps).

    • ADD credits section by @neon-mmd in https://github.com/maxcurzi/tplay/pull/11

    Full Changelog: https://github.com/maxcurzi/tplay/compare/v0.4.0...v0.4.1

    Source code(tar.gz)
    Source code(zip)
  • v0.4.0(May 3, 2023)

    Update audio player to use rodio backend (and have feature flags for mpv)

    What's Changed

    • Cargo.lock: commit for binary packages by @colemickens in https://github.com/maxcurzi/tplay/pull/8
    • Mpv select by @maxcurzi in https://github.com/maxcurzi/tplay/pull/10
    • updating installation instructions, adding subsections, fixing code, removing libmpv code and deleting build.rs by @neon-mmd in https://github.com/maxcurzi/tplay/pull/9

    New Contributors

    • @colemickens made their first contribution in https://github.com/maxcurzi/tplay/pull/8

    Full Changelog: https://github.com/maxcurzi/tplay/compare/v0.3.1...v0.4.0

    Source code(tar.gz)
    Source code(zip)
    tplay-0.4.0.crate(40.81 KB)
  • v0.3.1(May 2, 2023)

    What's Changed

    • Support playback with colors by @maxcurzi in https://github.com/maxcurzi/tplay/pull/1
    • Audio by @maxcurzi in https://github.com/maxcurzi/tplay/pull/2
    • show yt-dlp output by @maxcurzi in https://github.com/maxcurzi/tplay/pull/5

    Full Changelog: https://github.com/maxcurzi/tplay/commits/v0.3.1

    Source code(tar.gz)
    Source code(zip)
Owner
Max Curzi
Max Curzi
A simple CLI tool to convert the images to ASCII art with rust πŸ¦€πŸ’™

aarty: A simple CLI tool to convert images to ASCII art with Rust ?? More screenshots Original image Original image Original image Original image Orig

Anas Elgarhy 26 Feb 13, 2023
A CLI tool that converts images to ASCII art.

Rust ASCII Art Converter This Rust tool converts images into ASCII art. It takes an image file as input, resizes it according to specified width and h

TheD24 133 Dec 3, 2023
A more compact and intuitive ASCII table in your terminal: an alternative to "man 7 ascii" and "ascii"

asciit A more compact and intuitive ASCII table in your terminal: an alternative to man 7 ascii and ascii. Colored numbers and letters are much more e

Qichen Liu 刘启辰 5 Nov 16, 2023
An ascii webcam in your console, written as a way of learning rust.

asciicam An ascii webcam in your console, written as a way of learning rust. asciicam picture of me holding a basketball usage only linux is supported

Vilhelm BergsΓΈe 3 Nov 15, 2022
A simple but production-ready link shortener. Repository belonging to one of my YouTube videos

What is this? This is a simple link shortener, which is the result of a tutorial I did on YouTube. Important technologies used Rust (as our most belov

Oliver Jumpertz 7 Apr 21, 2024
A small command-line application to view images from the terminal written in Rust.

A small command-line application to view images from the terminal written in Rust. It is basically the front-end of viuer

Atanas Yankov 1.9k Jan 3, 2023
Build terminal dashboards using ascii/ansi art and javascript

blessed-contrib Build dashboards (or any other application) using ascii/ansi art and javascript. Friendly to terminals, ssh and developers.

Yaron Naveh 15k Jan 2, 2023
Enhance low quality images and videos using AI technology.

Real ESRGAN GUI Real ESRGAN GUI is a simple and minimal GUI for xinntao's Real-ESRGAN This allows you to enhance low quality images and videos using A

null 20 Dec 21, 2022
Advanced image to ascii art fully created with rust πŸ¦€ πŸš€

RASCII image to ascii art fully created with rust ?? ?? multiple language character lists -> βœ”οΈ creatable custom char list -> βœ”οΈ pixel art creaton ->

KoBruh 16 Dec 16, 2022
API Client to Generate AI ASCII Art 🦾🧠

Charisma Charisma serves a purpose of being a bridge between Dall-e mini. It's used to generate ASCII Art directly from your terminal. It uses Craiyon

camel_case 3 Jul 23, 2023
ask.sh: AI terminal assistant that can read and write your terminal directly!

ask.sh: AI terminal assistant that read from & write to your terminal ask.sh is an AI terminal assistant based on OpenAI APIs such as GPT-3.5/4! What'

hmirin 5 Jun 20, 2023
Nazuna - 🐦 Download Twitter videos using your terminal!

Nazuna ?? Download Twitter videos using your terminal! Installation Binary Download the desired file for your OS (Windows, Mac, Linux) from https://gi

Felipe Garcia 27 Nov 22, 2022
❗️ Small script to view GitHub notifications in the terminal

github-notifications Small script to view GitHub notifications in the terminal Shows and color-codes the notification source, eg if you're the owner o

Brian Shaginaw 1 Jan 10, 2022
View Source, but for terminal escape sequences

Escape Artist Escape Artist is a tool for seeing ANSI escape codes in terminal applications. You interact with your shell just like you normally would

Reilly Wood 8 Apr 16, 2023
Terminal UI for leetcode. Lets you browse questions through different topics. View, solve, run and submit questions from TUI.

Leetcode TUI Use Leetcode in your terminal. Why this TUI: My motivation for creating leetcode-tui stemmed from my preference for tools that are lightw

Akarsh 8 Aug 10, 2023
Ask ChatGPT for a shell script, code, or anything, directly from your terminal πŸ€–πŸ§ πŸ‘¨β€πŸ’»

ShellGPT Ask ChatGPT for a shell script, code, or anything, directly from your terminal ?? ?? ??‍?? Demo Install The binary is named gpt when installe

null 4 May 15, 2023
Play videos on IT8951-controlled e-paper displays

it8951-video Play videos on IT8951-controlled e-paper displays via USB. This has been tested with a Waveshare 7.8inch e-Paper HAT display. Design This

Andreas Dzialocha 4 Nov 28, 2022
A Rust-based renderer for Remotion videos.

Rustymotion A Rust-based renderer for Remotion projects. ?? WARNING: This is exploratory work only, use at your own risk. Design Remotion allows you t

Siddharth 12 Oct 6, 2023
Periodically download a youtube playlist, extract audio, convert to mp3, move to directory (possibly synced using syncthing).

auto-dl Periodically download a youtube playlist, extract audio, convert to mp3, move to directory (possibly synced using syncthing). drop https://git

Paul Adenot 10 Jan 12, 2023