You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
# 📺 Vidminal: 'Cause Who Needs Graphics Anyway? 🤷♀️
2
-
Ever wanted to watch videos but, like, without all those fancy pixels? Just good ol' text? And maybe with sound too? No? Well, too bad, 'cause this thing does it! 🙄
3
-
4
-
It's a super "optimized" tool that turns any video into a glorious, eye-straining ASCII art experience right in your terminal. Plus, it plays the audio. Because even a lazy developer knows you can't just have silent movies. 😴
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.
12
7
8
+
---
13
9
14
-
## 🚀 How to Get This Masterpiece Running
15
-
16
-
### From Binaries
17
-
Just download the right executable for your OS from the [Releases](https://github.com/sajagin/vidminal/releases) page. No Python or dependencies needed. Run it and follow the prompts. All required files (including BadApple.mp4 and ffmpeg) are bundled.
10
+
## 🚀 How to Run
18
11
19
-
### From Python Script
12
+
### 1. Download a Release (Recommended)
13
+
- Get the right executable for your OS from the [Releases](https://github.com/sajagin/vidminal/releases) page.
14
+
- No Python or dependencies needed. Just run it!
15
+
- All required files (including BadApple.mp4 and ffmpeg) are bundled.
20
16
21
-
- Prerequisites (Stuff You Probably Already Have, Hopefully)
22
-
-**Python**: 'Cause that's what this is written in. Duh.
23
-
-**Pillow**: For image magic. `pip install Pillow`
24
-
-**moviepy**: For video wrangling. `pip install moviepy`
25
-
-**pygame**: For sound. `pip install pygame`
17
+
### 2. Run from Python Source
18
+
-**Python 3.8+** required.
19
+
- Install dependencies:
20
+
```bash
21
+
pip install Pillow moviepy pygame py7zr colorama
22
+
```
23
+
- Run the script:
24
+
```bash
25
+
python vidminal.py
26
+
```
26
27
27
-
### No FFmpeg Setup!
28
-
You don't need to install ffmpeg yourself . This repo ships with a compressed `ffmpeg_bin.7z` containing all the ffmpeg binaries for Windows, Mac, and Linux (even ARM stuff). The script will extract and use the right one for your system, automatically. So, yeah, just run it.
28
+
---
29
29
30
30
## 🆕 Playback Controls
31
31
-**Space**: Pause/Resume
32
32
-**Q**: Quit
33
33
-**A/D**: Rewind/Forward 5 seconds
34
-
-**←/→ (Arrow keys)**: Skip 1 frame
35
-
36
-
## 🍿 Usage: "Watch" a Video
37
-
Just run it. The script will ask you for everything (video file, width, fps, temp folder) like a lazy wizard. ✨
38
-
```bash
39
-
python vidminal.py
40
-
```
41
-
Or, if you downloaded a binary, just run it:
42
-
```bash
43
-
./vidminal-windows.exe # or vidminal-linux, vidminal-macos
44
-
```
45
-
Just follow the prompts. Or just hit Enter for the defaults. That's it.
46
-
47
-
## ⚙️ Options (If You're Feeling Fancy)
48
-
You don't need to remember any command-line arguments. The program will create an `options.json` file the first time you run it, containing all the main settings:
49
-
50
-
- Video file (default: BadApple.mp4)
51
-
- Temp folder (default: temp)
52
-
- Width (default: 160)
53
-
- FPS (default: 24)
54
-
55
-
Just edit `options.json` to set your preferred defaults. The script will use these values every time you run it. No more prompts for width, fps, or temp folder—just set and forget!
If you delete `options.json`, it'll be recreated with defaults next time you run the program.
60
-
61
-
## ⚠️ Known Issues / "Features"
62
-
- Terminal Size Matters: If your terminal is too small, things will look like a jumbled mess. Make it big! Or don't, I'm not your boss.
63
-
- Performance: It's Python. It's ASCII. It might stutter. Don't come crying to me.
64
-
- Temporary Files: It creates a bunch of image files and an audio file. It doesn't clean them up automatically. Why? **Because I'm lazy. Delete them yourself!** 🔥🗑️
65
-
- ffmpeg will be extracted to the script's root folder if not already there. If you delete it, it'll just get extracted again. Magic.
34
+
-**←/→ (Arrow keys)**: Skip 1 second
35
+
36
+
---
37
+
38
+
## 🍿 Usage
39
+
- Run the script or binary. It will prompt for a video file (or use the default BadApple.mp4).
40
+
- All settings (width, fps, temp folder) are stored in `options.json` after first run. Edit this file to change defaults.
41
+
- The program will extract and use the correct ffmpeg binary for your OS automatically—no setup needed!
42
+
43
+
---
44
+
45
+
## ⚙️ Options
46
+
-`options.json` is created on first run. You can edit it to set:
47
+
- Video file (default: BadApple.mp4)
48
+
- Temp folder (default: temp)
49
+
- Width (default: 160)
50
+
- FPS (default: 24)
51
+
- No more prompts for width, fps, or temp folder—just set and forget!
52
+
53
+
---
54
+
55
+
## 🧹 Cleanup
56
+
- All temporary files (frames, audio, temp ffmpeg) are deleted automatically when the program exits, even if you quit early or force close.
57
+
58
+
---
59
+
60
+
## 📖 How Does It Work?
61
+
- 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.
62
+
63
+
---
64
+
65
+
## ⚠️ Known Issues / Notes
66
+
-**Terminal Size Matters:** If your terminal is too small, the video will look bad. Make it big!
67
+
-**Performance:** It's Python and ASCII. It might stutter on slow machines or huge videos.
68
+
-**ffmpeg:** You do NOT need to install ffmpeg yourself. The right binary is extracted and used automatically.
66
69
-**Full video path is required (No relative path)**
67
70
68
-
## Contributing (LOL)
69
-
Sure, if you really wanna make this "better," feel free. But honestly, it works, right? So why bother? Issues and pull requests are technically welcome, I guess. 🙄
71
+
---
72
+
73
+
## Contributing
74
+
Pull requests and issues are welcome! See the code and [WORKING.md](./WORKING.md) for details.
75
+
76
+
---
77
+
78
+
## License
79
+
MIT or similar. Use at your own risk. Don't blame me if your terminal melts.
80
+
81
+
---
82
+
83
+
## Credits
84
+
- Bad Apple!! video for testing
85
+
- All the open-source libraries used
70
86
71
-
# License
72
-
This project is probably under some open-source license. Just assume you can do whatever with it, but don't blame me if it breaks your computer. Or your eyes. 😜
87
+
---
73
88
74
-
#### PS: It's fun sometimes written a README from hand without any tool. 😆
75
-
#### added `BadApple.mp4` in repo for testing. It's literally the best thing after "Hello World".
89
+
For a full technical breakdown, see [WORKING.md](./WORKING.md).
0 commit comments