https://github.com/sajagin/vidminal
Vidminal: Watch videos in your terminal! Turns any video into glorious ASCII art with accompanying audio. Perfect for retro vibes or if you just hate pixels. 📺✨🔊
https://github.com/sajagin/vidminal
ascii-art cmd command-line-tool ffmpeg ffmpeg-script my-projects python python-ffmpeg terminal video-player
Last synced: about 2 months ago
JSON representation
Vidminal: Watch videos in your terminal! Turns any video into glorious ASCII art with accompanying audio. Perfect for retro vibes or if you just hate pixels. 📺✨🔊
- Host: GitHub
- URL: https://github.com/sajagin/vidminal
- Owner: SajagIN
- Created: 2025-06-18T11:35:26.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2025-06-19T14:20:38.000Z (12 months ago)
- Last Synced: 2025-06-19T14:46:12.675Z (12 months ago)
- Topics: ascii-art, cmd, command-line-tool, ffmpeg, ffmpeg-script, my-projects, python, python-ffmpeg, terminal, video-player
- Language: Python
- Homepage:
- Size: 83.9 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 📺 Vidminal: Terminal Video as ASCII Art
### A little sneek peek:
https://github.com/user-attachments/assets/fbd1eaeb-4037-465c-b473-fa1c6f9ca26e
Ever wanted to watch videos as colored ASCII art in your terminal, with sound, and full keyboard controls? Now you can! This project turns any video into a glorious, eye-straining ASCII art experience—right in your terminal, with audio, seeking, and more.
---
## 🚀 How to Run
### 1. Download a Release (Recommended)
- Get the right executable for your OS from the [Releases](https://github.com/sajagin/vidminal/releases) page.
- No Python or dependencies needed. Just run it!
- All required files (including BadApple.mp4 and ffmpeg) are bundled.
### 2. Run from Python Source
- **Python 3.8+** required.
- Install dependencies:
```bash
pip install Pillow moviepy pygame py7zr colorama
```
- Run the script:
```bash
python vidminal.py
```
---
## 🆕 Playback Controls
- **Space**: Pause/Resume
- **Q**: Quit
- **A/D**: Rewind/Forward 5 seconds
- **←/→ (Arrow keys)**: Skip 1 second
- **M**: Mute/Unmute
- **+/-**: Volume Up/Down
---
## 🍿 Usage
- Run the script or binary. It will prompt for a video file (or use the default BadApple.mp4).
- All settings (width, fps, temp folder) are stored in `options.json` after first run. Edit this file to change defaults.
- The program will extract and use the correct ffmpeg binary for your OS automatically—no setup needed!
---
## ⚙️ Options (`options.json`)
This file is created on first run. You can edit it to change default behavior:
- **`temp`**: Name of the temporary folder for frames and audio (default: `temp`).
- **`wide`**: Default width of the ASCII art (default: `160`). The player will still resize dynamically to your terminal.
- **`fps`**: The frames-per-second to play the video at (default: `24`).
- **`ascii_chars_set`**: Choose a character set for the ASCII art: "`default`", "`detailed`", "`simple`", or "`custom`".
- **`chars`**: If `ascii_chars_set` is `custom`, this string of characters will be used (from darkest to lightest).
- **`gamma` / `contrast`**: Adjust the visual look of the ASCII video.
- **`audio_volume_start`**: Initial volume when a video starts (from `0.0` to `1.0`).
- **`default_video_path`**: Set a path to a video file to be used as the default if you don't provide one.
- **`show_ui_on_start`**: Show the fancy welcome box on startup (`true` or `false`).
- **`clear_screen_on_resize`**: Whether to clear the whole screen when the terminal is resized (`true` or `false`).
- **`seek_jump_seconds`**: How many seconds to jump with the `A`/`D` keys (default: `5`).
- **`fine_seek_seconds`**: How many seconds to jump with the arrow keys (default: `1`).
---
## 🧹 Cleanup
- All temporary files (frames, audio, temp ffmpeg) are deleted automatically when the program exits, even if you quit early or force close.
---
## 📖 How Does It Work?
- See [WORKING.md](./WORKING.md) for a full, beginner-friendly explanation of every part of the code, how ffmpeg works, and how everything fits together.
---
## ⚠️ Known Issues / Notes
- **Terminal Size Matters:** If your terminal is too small, the video will look bad. Make it big!
- **Performance:** It's Python and ASCII. It might stutter on slow machines or huge videos.
- **ffmpeg:** You do NOT need to install ffmpeg yourself. The right binary is extracted and used automatically.
- **Full video path is required (No relative path)**
---
## Contributing
Pull requests and issues are welcome! See the code and [WORKING.md](./WORKING.md) for details.
---
## License
MIT or similar. Use at your own risk. Don't blame me if your terminal melts.
---
## Credits
- Bad Apple!! video for testing
- All the open-source libraries used
---
For a full technical breakdown, see [WORKING.md](./WORKING.md).