{"id":28959253,"url":"https://github.com/sajagin/vidminal","last_synced_at":"2026-04-11T08:04:46.453Z","repository":{"id":300031073,"uuid":"1004277348","full_name":"SajagIN/vidminal","owner":"SajagIN","description":"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. 📺✨🔊","archived":false,"fork":false,"pushed_at":"2025-06-19T14:20:38.000Z","size":87946,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-19T14:46:12.675Z","etag":null,"topics":["ascii-art","cmd","command-line-tool","ffmpeg","ffmpeg-script","my-projects","python","python-ffmpeg","terminal","video-player"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SajagIN.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":["https://codewhiteweb.thedev.id/#sponsor"]}},"created_at":"2025-06-18T11:35:26.000Z","updated_at":"2025-06-19T14:21:54.000Z","dependencies_parsed_at":"2025-06-19T14:56:18.601Z","dependency_job_id":null,"html_url":"https://github.com/SajagIN/vidminal","commit_stats":null,"previous_names":["sajagin/vidminal"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/SajagIN/vidminal","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SajagIN%2Fvidminal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SajagIN%2Fvidminal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SajagIN%2Fvidminal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SajagIN%2Fvidminal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SajagIN","download_url":"https://codeload.github.com/SajagIN/vidminal/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SajagIN%2Fvidminal/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261577973,"owners_count":23179766,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ascii-art","cmd","command-line-tool","ffmpeg","ffmpeg-script","my-projects","python","python-ffmpeg","terminal","video-player"],"created_at":"2025-06-24T00:01:23.529Z","updated_at":"2026-04-11T08:04:46.416Z","avatar_url":"https://github.com/SajagIN.png","language":"Python","funding_links":["https://codewhiteweb.thedev.id/#sponsor"],"categories":[],"sub_categories":[],"readme":"# 📺 Vidminal: Terminal Video as ASCII Art\n\n### A little sneek peek:\nhttps://github.com/user-attachments/assets/fbd1eaeb-4037-465c-b473-fa1c6f9ca26e\n\nEver 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.\n\n---\n\n## 🚀 How to Run\n\n### 1. Download a Release (Recommended)\n- Get the right executable for your OS from the [Releases](https://github.com/sajagin/vidminal/releases) page.\n- No Python or dependencies needed. Just run it!\n- All required files (including BadApple.mp4 and ffmpeg) are bundled.\n\n### 2. Run from Python Source\n- **Python 3.8+** required.\n- Install dependencies:\n  ```bash\n  pip install Pillow moviepy pygame py7zr colorama\n  ```\n- Run the script:\n  ```bash\n  python vidminal.py\n  ```\n\n---\n\n## 🆕 Playback Controls\n- **Space**: Pause/Resume\n- **Q**: Quit\n- **A/D**: Rewind/Forward 5 seconds\n- **←/→ (Arrow keys)**: Skip 1 second\n- **M**: Mute/Unmute\n- **+/-**: Volume Up/Down\n\n---\n\n## 🍿 Usage\n- Run the script or binary. It will prompt for a video file (or use the default BadApple.mp4).\n- All settings (width, fps, temp folder) are stored in `options.json` after first run. Edit this file to change defaults.\n- The program will extract and use the correct ffmpeg binary for your OS automatically—no setup needed!\n\n---\n\n## ⚙️ Options (`options.json`)\nThis file is created on first run. You can edit it to change default behavior:\n\n- **`temp`**: Name of the temporary folder for frames and audio (default: `temp`).\n- **`wide`**: Default width of the ASCII art (default: `160`). The player will still resize dynamically to your terminal.\n- **`fps`**: The frames-per-second to play the video at (default: `24`).\n- **`ascii_chars_set`**: Choose a character set for the ASCII art: \"`default`\", \"`detailed`\", \"`simple`\", or \"`custom`\".\n- **`chars`**: If `ascii_chars_set` is `custom`, this string of characters will be used (from darkest to lightest).\n- **`gamma` / `contrast`**: Adjust the visual look of the ASCII video.\n- **`audio_volume_start`**: Initial volume when a video starts (from `0.0` to `1.0`).\n- **`default_video_path`**: Set a path to a video file to be used as the default if you don't provide one.\n- **`show_ui_on_start`**: Show the fancy welcome box on startup (`true` or `false`).\n- **`clear_screen_on_resize`**: Whether to clear the whole screen when the terminal is resized (`true` or `false`).\n- **`seek_jump_seconds`**: How many seconds to jump with the `A`/`D` keys (default: `5`).\n- **`fine_seek_seconds`**: How many seconds to jump with the arrow keys (default: `1`).\n\n---\n\n## 🧹 Cleanup\n- All temporary files (frames, audio, temp ffmpeg) are deleted automatically when the program exits, even if you quit early or force close.\n\n---\n\n## 📖 How Does It Work?\n- 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.\n\n---\n\n## ⚠️ Known Issues / Notes\n- **Terminal Size Matters:** If your terminal is too small, the video will look bad. Make it big!\n- **Performance:** It's Python and ASCII. It might stutter on slow machines or huge videos.\n- **ffmpeg:** You do NOT need to install ffmpeg yourself. The right binary is extracted and used automatically.\n- **Full video path is required (No relative path)**\n\n---\n\n## Contributing\nPull requests and issues are welcome! See the code and [WORKING.md](./WORKING.md) for details.\n\n---\n\n## License\nMIT or similar. Use at your own risk. Don't blame me if your terminal melts.\n\n---\n\n## Credits\n- Bad Apple!! video for testing\n- All the open-source libraries used\n\n---\n\nFor a full technical breakdown, see [WORKING.md](./WORKING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsajagin%2Fvidminal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsajagin%2Fvidminal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsajagin%2Fvidminal/lists"}