📺 Vidminal: Terminal Video as ASCII Art

A little sneek peek:

SNEEK.PEAK.mp4

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 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:

  pip install Pillow moviepy pygame py7zr colorama

• Run the script:

  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 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 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.