bolt

README

⚡ bolt

Bolt is a high-speed, terminal-based media downloader written in Go. It’s not just a wrapper; it’s a modern, interactive experience for yt-dlp that makes downloading videos and music as fast as a lightning strike.

Built with the Charmbracelet stack (bubbletea, lipgloss), Bolt offers a beautiful TUI to manage your downloads with ease.

✨ Features

• Interactive "Storm" Selection: Don't memorize flags. Pick your resolution (4K, 1080p, etc.) or format from a clean interactive menu.
• Chain Lightning (Concurrency): Download up to 3 videos simultaneously by default.
• Smart Routing: Automatically sends music to ~/Music and videos to ~/Videos.
• Rich Metadata: Automatically embeds thumbnails, subtitles, and ID3 tags.
• Real-time Progress: Smooth, frame-accurate progress bars powered by Go goroutines.

---

🚀 Installation

1. Prerequisites

You must have the following tools installed and available in your PATH:

• Go (v1.25.7+)
• yt-dlp (The engine)
• ffmpeg (For merging video/audio streams)

2. Install via Go

go install github.com/volkheim/bolt@latest

3. Configure your PATH

If the bolt command isn't recognized after installation, you need to add Go's binary folder to your shell configuration.

For Zsh (default on many systems/macOS):

echo 'export PATH=$PATH:$(go env GOPATH)/bin' >> ~/.zshrc
source ~/.zshrc

For Bash:

echo 'export PATH=$PATH:$(go env GOPATH)/bin' >> ~/.bashrc
source ~/.bashrc

---

🛠 Usage

Command	Description
bolt <url>	Interactive Mode: Pick resolution/format manually.
bolt <url1> <url2>	Multi-Download: Strike multiple links at once.
bolt -a <url>	Audio Mode: Direct-to-MP3 in your Music folder.
bolt -p <url>	Playlist Mode: Downloads a whole playlist into a subfolder.

TUI Controls

• Arrows / J / K: Navigate menus
• Enter: Confirm selection
• Q / Ctrl+C: Cancel and exit

---

🏗 Project Structure

Bolt is built with modularity in mind:

• main.go: Entry point & flag parsing.
• model.go: The TUI state machine.
• download.go: Concurrency logic and yt-dlp parsing.
• metadata.go: Format templates and JSON fetching.
• styles.go: The "lightning" aesthetic (Lip Gloss).

---

📜 License

Distributed under the MIT License. See LICENSE for more information.