A desktop video downloader and media processor built with Electron, powered by yt-dlp and FFmpeg. Download videos and audio from YouTube, X (Twitter), Instagram, and hundreds of other sites, with support for format selection, subtitle extraction, re-encoding, and hardsubbing.
The app provides two interfaces you can switch between at any time:
- Classic Mode: A traditional form with URL input, action selection, and cookie/proxy settings.
- AI Mode: Describe what you want in plain language (e.g., "Download this video and add an English hardsub to it"). The app translates your request into safe
yt-dlporFFmpegcommands and runs them for you.
- Dual interfaces: Switch between the traditional form and a conversational AI chat at any time.
- Broad platform support: Downloads media using
yt-dlpfrom YouTube, X, Instagram, TikTok, and more. - Quality & format control: Select specific resolutions and containers, or extract audio directly (M4A, MP3, Opus, FLAC, WAV).
- Embedded thumbnails: Automatically attaches video thumbnails into MP4 containers.
- Subtitle handling: Download subtitles by language, or burn them into the video (hardsub) with top or bottom positioning.
- MP4 re-encoding: Convert videos to universally compatible H.264/AAC MP4 files via FFmpeg.
- Hardware acceleration: Takes advantage of macOS VideoToolbox for fast encoding.
- Cookie support: Pass cookies from Chrome, Firefox, Brave, or Safari to download age-restricted or member-only videos.
- SOCKS5 proxy: Route downloads and queries through a local (e.g.
127.0.0.1:1080) or remote proxy. - Safe cancellation: Stop any in-progress download or encoding job with one click; partial files are cleaned up automatically.
Install and update using Homebrew:
brew install --cask Shawshank01/tap/vidbutlerTo update in the future:
brew update --force
brew upgrade --cask Shawshank01/tap/vidbutler- Download the latest release from the Releases page.
- Run the installer for your operating system:
- macOS:
.dmg(selectmac-arm64for Apple Silicon M-series Macs) - Windows:
.exeinstaller (selectwin-x64for most users) - Linux:
.AppImage
- macOS:
Important
The macOS DMG is unsigned and not notarised because the project does not have an Apple Developer Program membership. macOS may block a direct DMG installation. Homebrew is the recommended macOS installation method, direct-download users may need Open Anyway in System Settings > Privacy & Security, or as a fallback run xattr -cr /Applications/VidButler.app.
-
Clone the repository:
git clone https://github.com/Shawshank01/Vidbutler.git cd Vidbutler -
Install dependencies:
pnpm install
-
Start the application:
pnpm start
(On macOS, you can also double-click
start.commandin the project root to install dependencies and launch the app.)
To build an installer for your current platform:
pnpm run buildInstallers and executables are output to the dist/ directory.
macOS release builds are unsigned and do not require Apple Developer Program credentials. Windows signing is used when the optional WIN_CSC_LINK and WIN_CSC_KEY_PASSWORD secrets are configured.
Click AI in the top-right corner to open the chat panel. You can ask for downloads, conversions, file management, or media inspection in conversational language.
- "Download this video: https://..."
- "Download this video in 720p: https://..."
- "Get the audio of this video as an M4A"
- "What subtitle languages are available for this video?" followed by "Hardcode the English ones at the top"
- "Download it, then re-encode it to a compatible MP4"
- "Show me what's in my download folder" / "Delete the leftover subtitle files"
The assistant has access to dedicated tools for fetching video info, inspecting local media, listing formats and subtitles, downloading media/thumbnails, burning subtitles, re-encoding to MP4, and listing or deleting downloaded files.
Note
The assistant can only perform actions supported by these tools (for instance, video trimming is not supported yet; it will tell you so and can suggest an ffmpeg command). AI mode shares the exact same download folder, browser cookies, and proxy settings as Classic mode.
Rather than giving an LLM direct shell access, the app executes requests through predefined, strictly validated tools:
- No shell access: The model cannot run arbitrary terminal commands. Every operation maps to a predefined tool that builds argument arrays directly.
- Strict parameter validation: URLs must use
http(s), file names cannot escape the designated download directory, and format codes are regex-checked. - Prompt injection defense & URL provenance: Text from websites (titles, descriptions, comments) is treated as untrusted data. URLs that did not come directly from your message require explicit confirmation before downloading.
- Configurable confirmations: Operations considered high risk (re-encoding existing files, deleting files, downloading full playlists) prompt for confirmation before proceeding.
- Zero framework bloat: The AI integration is written with vanilla ES modules and standard HTTP requests—no LangChain, LlamaIndex, or heavy external agent runtimes.
- Click top right corner AI, then open AI Settings.
- Select your provider, verify the model, paste your API key, and click Save key.
- Click Test connection, then Save.
- Choose your download folder and start chatting.
| Provider | Requirement | Notes |
|---|---|---|
Google Gemini (default, model gemini-3.5-flash-lite) |
Free API key from Google AI Studio | Free tier can be busy (HTTP 503) or rate limited, the app retries automatically. Your messages go to Google. |
xAI Grok (model grok-4.3) |
API key from the xAI console | Uses xAI's Responses API at https://api.x.ai/v1/responses. Your messages go to Musk. |
| Ollama (local) | Ollama running with a tool-capable model, for example LFM3:1.7b, Qwen3. |
Everything stays on your computer if you run a local model. Small models are faster but less reliable. |
| OpenAI-compatible | Server URL, model name, usually an API key | Works with llama.cpp, OpenAI, OpenRouter, Groq, LM Studio and similar. |
Additional settings:
- Reasoning effort: Adjust how long models think before responding (Fast is recommended for quick downloads).
- Confirmation level: Choose whether to require approval for Risky actions only (default), Every action, or Never.
- What is sent to the provider: Only your chat prompts, assistant replies, and necessary tool outputs (video titles, format lists, filenames).
- API key storage: Stored securely using Electron's
safeStorage(macOS Keychain, Windows DPAPI, Linux Secret Service). Keys never touch renderer memory or client-side storage. - Ephemeral conversations: Chat history is kept in memory only during the active session. Closing the window or starting a new chat discards it completely.
- Isolated file operations: File operations are strictly locked to your selected download folder.
Classic mode provides a straightforward, no-fuss interface:
- Paste a video URL and select your destination folder.
- Choose your action:
- Download Video (Best Quality): Grabs the best available stream.
- List Formats: Shows every available stream and its format code.
- Download (Custom Format): Enter a specific format code (run List Formats first to view available options). Choose an audio-only format code to download just the audio.
- Download Thumbnail: Saves only the thumbnail image.
- Download Subtitles: Displays available subtitle tracks and lets you pick which to save.
- Download & Re-encode to MP4: Re-encodes with H.264/AAC for maximum playback compatibility.
- Download & Add Hardsub: Burns subtitles directly into the video stream with customizable position (top or bottom).
- If needed, select your browser under Browser for Cookies (helpful for age-restricted or private links) or toggle the SOCKS5 Proxy.
- Click Run.
To stop an ongoing task, click Cancel Action. The active yt-dlp or FFmpeg process will exit immediately and clean up any incomplete temp files.
Installed release builds check for updates each time VidButler launches:
-
VidButler checks for a newer version from the official GitHub Releases feed each time it launches.
-
On Windows and Linux AppImage, choose Download and Restart. The update is checksum-verified, installed, and the new version launches automatically.
-
On macOS, choose Copy Homebrew Command, then paste the command into Terminal. The command refreshes the custom tap before upgrading:
brew update --force && brew upgrade --cask Shawshank01/tap/vidbutlerIf VidButler was installed directly from a DMG, choose Open GitHub Release instead.
-
You can also check manually from About > Check for Updates. Nothing is downloaded until you agree.
Source runs and extracted Linux builds cannot replace themselves; they link to the latest release instead.
Note
Packaged release builds bundle their own copies of yt-dlp, FFmpeg, and Deno (used for solving YouTube JavaScript challenges). In development runs (pnpm start), the app looks for tools installed on your system PATH.
-
Missing Tools in Development
- Development mode expects
yt-dlpandffmpegon yourPATH. - Install them via package managers:
- macOS:
brew install yt-dlp ffmpeg - Linux (Ubuntu/Debian):
sudo apt install yt-dlp ffmpeg - Windows: Download from official releases and add to your PATH.
- macOS:
- Development mode expects
-
Browser Cookies Access (macOS)
- When reading cookies from Chrome, Firefox, or Safari, macOS may request permission.
- If access is denied, go to System Settings > Privacy & Security > Files & Folders and ensure
VidButler.appis enabled.
-
AI Mode Connection Issues
- HTTP 503 (Overloaded): Google Gemini free tier can occasionally experience high demand. The app automatically retries; if it persists, wait a moment or try another provider.
- HTTP 429 (Rate Limit): Quota exhausted. Wait for it to reset or switch to a local Ollama model.
- Authentication Errors: Open AI Settings, re-enter your key, and use Test connection.
src/
main.js Electron main process: window creation, IPC handlers
preload.cjs Secure context bridge (window.electronAPI)
renderer.js Classic mode interface logic
ai-ui.js AI mode interface: chat, settings, confirmation dialogs
markdown.js Lightweight safe Markdown renderer for chat replies
dependencies.js Tool resolution (bundled vs system PATH)
check-dependencies.js Pre-flight dependency checks
settings-store.js Atomic JSON configuration store
settings-schema.js Schema validation for settings
update.js Platform update coordinator (check, Homebrew guidance, download/install)
core/ Shared yt-dlp / FFmpeg operations (Electron-free)
tools.js Download, query, subtitle, and media operations
task-manager.js Task queueing, concurrency, and cancellation
ffmpeg.js FFmpeg command generation and execution
llm/ AI execution engine (Electron-free)
agent.js Agent loop: tool execution, step budgeting, and event dispatch
tool-registry.js Tool declarations and risk classification
tools/ Tool implementations (info, download, media, files)
validate.js Strict input validation for model arguments
provenance.js URL origin tracking to guard against indirect prompt injection
chat-service.js Conversation management, confirmation handling, and state
key-store.js Encrypted API key storage via Electron safeStorage
providers/ Provider implementations (Gemini, xAI, Ollama, OpenAI-compatible)
test/ Unit tests using node:test runner
Contributions, bug reports, and suggestions are welcome!
Before submitting a pull request, please ensure linting and tests pass:
pnpm run lint
pnpm testThe test suite runs offline using mock HTTP responses and fake model scripts. Tests cover parameter validation, provider adapters, the agent loop, safe key storage, settings schemas, and interface wiring.
