PulseTube Studio

A high-performance batch media downloader with frosted-glass aesthetics & precision timestamp trimming.

Direct Downloads • Key Features • How It Works • Architecture • Build from Source

---

⚡ Overview

PulseTube Studio bridges the complete flexibility of yt-dlp and FFmpeg with a modern YouTube-inspired dark obsidian frosted-glass interface.

Built for archivists, researchers, creators, and audiophiles, it eliminates command-line friction while introducing features absent in most desktop wrappers:

• Per-item custom timestamp trimming within batch queues.
• Multi-worker concurrent pipelines with independent progress, ETA, and throughput monitors.
• True 4K VP9 & 1080p H.264 stream selection to eliminate green artifact lines on hardware decoders.
• Over-the-air (OTA) updates powered by GitHub Releases.

---

📦 Quick Downloads

Operating System	Package Type	Link
Windows 10 / 11	Modern Inno Setup Installer (.exe)	Download PulseTube_Setup.exe
Linux (Ubuntu / Mint / Debian)	Native Debian Binary (.deb)	Download pulsetube_amd64.deb
Windows (Portable)	Standalone Archive (.zip)	Download PulseTube_Portable.zip

---

✨ Key Features

• 🎯 Precision Timestamp Trimming: Expand any card in your queue and define From: [MM:SS] and To: [MM:SS] points. The engine uses keyframe-accurate cuts without redownloading the entire stream.
• ⚡ 4-Worker Concurrency Engine: Download up to 4 streams concurrently with independent progress, ETA, and transfer speed monitors.
• 🎨 Frosted Glass UI: Built using hardware-accelerated CSS backdrop filters, responsive dark/light modes, ambient red glow depth, and smooth animated state drawers.
• 🎧 Studio Audio Extraction: Extract audio up to 320 kbps MP3 with automatic high-resolution cover art embedding and ID3 tagging.
• 🎬 Glitch-Free 4K / 2K & 1080p Video: Smart codec fallback routes 1080p to native H.264 (avc1) for universal player compatibility and dynamically promotes 2K/4K to VP9—preventing Windows hardware decoder green-bar glitches.
• 📁 Flexible Link Input:
  • Drag and drop .txt link files directly onto the app window.
  • Paste single links or comma-separated lists (link1, link2, link3).
  • Automatically unfolds YouTube Playlists and Mixes into individually selectable items.
• 🔄 Zero-Friction OTA Updates: Automated background checks against GitHub Releases. Updates download in seconds, self-terminate the old instance, and seamlessly relaunch.
• 🛡️ Sandbox & Self-Healing: Stores runtime binaries (yt-dlp, FFmpeg) in isolated user-space directories (%LOCALAPPDATA% on Windows, ~/.local/share on Linux), preventing OneDrive locks and write-permission crashes.

---

🚀 Quickstart Guide

1. Load Your Links

• Method A: Click Browse .txt or drag & drop a .txt file containing YouTube URLs into the drop target.
• Method B: Paste URLs into the link bar separated by commas:

  https://youtu.be/dQw4w9WgXcQ, https://youtu.be/9bZkp7q19f0
  

2. Configure Formats & Ranges

• Toggle between MP3 Audio (128 / 192 / 320 kbps) and MP4 Video (480p to 4K Ultra HD).
• Click the chevron (▾) on any video item to expand its trim panel:
  • Check Download custom timestamp section only.
  • Specify start and end times (e.g., 00:45 to 02:30).

3. Choose Destination & Run

• Click Browse Dest to pick your save folder.
• Select your concurrency level (1x Sequential to 4x Turbo).
• Hit Download Selected and watch individual per-task progress meters.

---

🛠️ Architecture

PulseTube Studio
├── Frontend (Chromium / Edge App Mode)
│   ├── Tailwind CSS Glassmorphism Engine
│   ├── Inter & JetBrains Mono Typography
│   └── Bi-directional Eel IPC Bridge
└── Backend (Python 3 Engine)
    ├── Asynchronous Metadata Scraper (oEmbed + yt-dlp JSON)
    ├── ThreadPoolExecutor Queue (1–4 Parallel Workers)
    ├── Subprocess Wrapper (yt-dlp + FFmpeg stream parsing)
    └── GitHub REST API Auto-Updater Loop

---

💻 Building from Source

Prerequisites

• Python 3.10+
• Linux (for cross-compiling both .deb and .exe) or Windows
• Inno Setup 6 (for packaging Windows setup executables)
• Wine (if building Windows targets from Linux)

1. Clone & Set Up Virtual Environment

git clone https://github.com/SachinKJha/PulseTube.git
cd PulseTube

python3 -m venv venv
source venv/bin/activate  # On Windows: .\venv\Scripts\activate
pip install -r requirements.txt

2. Run Locally in Development Mode

python3 main.py

3. Compile Binary Packages

# Compile Linux .deb
chmod +x build_linux_deb.sh
./build_linux_deb.sh

# Ship new update to GitHub (Builds Windows + Linux, pushes tags & installers)
chmod +x ship_update.sh
./ship_update.sh 1.1.0 "Added drag-and-drop link import and 4K VP9 fixes"

---

📜 License

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

---

🤝 Contributing & Acknowledgments

• Built on the media extraction engine yt-dlp.
• Core conversion pipelines powered by FFmpeg.
• Webview desktop bridge enabled by Eel.

Crafted by Sachin Kant Jha