Velo

High-performance YouTube media downloader, stream diagnostic engine, and interactive transcript suite.

Velo is a modern web application built to inspect, stream, download, and extract transcripts from YouTube videos at full quality (up to 4K UHD). It combines client-side streaming intelligence with backend fallback ladders to bypass rate limits, resolve throttled streams, and mux multi-track audio/video with zero quality loss.

---

Highlights & Features

1. Zero-Loss Video & Audio Muxing

• Full Resolution Support: Fetch 1080p Full HD, 1440p QHD, 4K UHD (2160p), 720p HD, and audio-only streams.
• Direct Copy-Muxing: YouTube separates 1080p+ video streams from audio tracks. Velo pairs the highest-bitrate video stream with original AAC/Opus audio and muxes them into a single MP4/WebM container on the fly without lossy re-encoding.
• Real-Time Telemetry & Pre-Flight: Inspects video containers, available itags, detected codecs (H.264, AV1, VP9, AAC, Opus), and optimal download pipelines before starting.

2. Interactive YouTube-to-Transcript Suite

• Time-Synced Cues: Scrollable transcript with click-to-seek timestamp buttons that instantly jump and play the video.
• In-Transcript Search: Instant keyword filtering with live match count and highlighted search terms.
• Multi-Format Subtitle Downloads:
  • TXT — Plain text or timestamped notes.
  • SRT — Standard SubRip subtitle format with sequence numbers and millisecond timestamps.
  • VTT — WebVTT caption file format.
  • JSON — Structured array of timed cue objects ({ id, start, end, text }).
• 1-Click AI Prompt Library:
  • 📝 Executive Summary (Quick overview & key takeaways)
  • 📚 Detailed Study Notes (Hierarchical concepts & definitions)
  • ❓ Q&A & FAQ Generator (Top questions & answers from video content)
  • ⏱️ Timestamps & Chapters (Ready-to-paste YouTube chapter markers)
  • ✅ Action Items & Checklist (Extracts tools, guides, and practical steps)
  • 🧵 Social Media Thread (Engaging Twitter/X or LinkedIn summary thread)

3. Creator & Video Editor Ingest Suite

• NLE Timeline Marker Exporters:
  • DaVinci Resolve Marker CSV: SMPTE timecodes (HH:MM:SS:FF), cue names, notes, and color tagging.
  • Final Cut Pro XML (.fcpxml): Full project sequence with timed <marker> and <chapter-marker> tags.
  • Adobe Premiere Pro EDL (.edl): CMX 3600 compliant marker event lists with clip comments.
  • Audacity Label Tracks (.txt): Tab-delimited high-precision time markers for DAWs.
• Precision Time-Range Clipper (Clip & Cut):
  • Custom Start Time and End Time inputs with quick presets (Full Video, First 60s, First 5 Mins).
  • Proportional clip file size calculation and 1-click yt-dlp --download-sections command generator.
• High-Res Artwork & Thumbnail Extractor:
  • 1-click downloads for uncompressed 1080p MaxRes JPG (maxresdefault.jpg), high-efficiency WebP, SD, and HQ assets.

4. Anti-Throttle Bulk & Playlist Ingest Engine

• Intelligent Link Extractor: Parses freeform text, multi-line pastes, CSVs, markdown, and playlists to extract unique YouTube videos while skipping duplicates.
• Playlist Auto-Expansion: Automatically fetches and unpacks playlist items into individual queue rows.
• Anti-Burst Concurrency & Pacing:
  • Configurable concurrency workers (1, 2, or 3 concurrent streams).
  • Staggered launch delays (1.0s - 3.0s) between successive requests to prevent YouTube 429 rate limits and BotGuard burst triggers.
  • Progressive exponential backoff with auto-retry on transient failures.
• Global & Per-Item Quality Presets: Apply 1080p Full HD, 720p HD, Audio-Only, or Subtitles-Only across the entire queue.
• Multi-Format Batch Exporters:
  • yt-dlp Bash Script (.sh): Executable local script with optimal --concurrent-fragments and copy-mux flags.
  • Clean URL List: Formatted for IDM, JDownloader, aria2, or curl.
  • Structured JSON: Complete queue metadata with titles, durations, and statuses.

5. Resilient Multi-Tier Fallback Ladder

• InnerTube Multi-Client Routing: Dynamic switching between WEB_EMBEDDED, VISIONOS, TV_SIMPLY, WEB, and ANDROID clients.
• Proof-of-Origin (PO Token): Automated WebPO token minting and validation to prevent bot-detection blocks.
• Throttling Bypass & nsig Deciphering: Live transformation of YouTube's n parameter to prevent 40 KB/s stream choking.
• SOCKS Proxy Pool & Same-Hop Routing: Failover to IPv4 proxies when server IPs encounter 403 blocks.

5. Session Credential Vault & Browser Exporter

• Universal Cookie Importer: Supports Netscape HTTP cookie format, JSON arrays, and HTTP Archive (.har) files.
• Step-by-Step Guides for Every Browser: Detailed instructions for Chrome, Firefox, Safari (macOS), Edge, and Mobile Safari (iOS Bookmarklet).
• Session Health Diagnostics: Validates authentication tokens (SID, SAPISID, LOGIN_INFO) and checks live YouTube session status.
• Encrypted Local & Server Vault: Stores cookies safely with strict per-user database isolation.

---

Tech Stack

Layer	Technology
Framework	TanStack Start + React 19
Routing & RPC	TanStack Router with type-safe server functions (createServerFn)
Styling	Tailwind CSS v4 + Radix UI + Lucide Icons
Media & InnerTube	youtubei.js, yt-dlp, ffmpeg copy-transmux
Database & Auth	PGLite / PostgreSQL + Better Auth
Testing	Node.js native test runner (node --test), Playwright smoke tests

---

Project Structure

.
├── src/
│   ├── components/
│   │   ├── bulk-downloader.tsx      # Anti-throttle bulk queue & playlist download manager
│   │   ├── transcript-viewer.tsx    # Interactive transcript reader & AI prompt generator
│   │   ├── video-panel.tsx          # Video details, pre-flight telemetry, preset selector
│   │   ├── cookie-import.tsx        # Multi-format cookie import dialog & health checker
│   │   ├── session-guide.tsx        # Browser cookie extraction guides (Desktop & Mobile)
│   │   ├── history-list.tsx         # Recent downloads list with isolated user shelves
│   │   ├── save-stage.tsx           # File download / storage manager
│   │   └── ui/                      # Button, Input, Skeleton, Badge, Dialog components
│   ├── lib/
│   │   ├── bulk-download.ts         # Bulk link extractor, concurrency queue, batch exporters
│   │   ├── youtube.ts               # Video presets, codecs, duration/view formatters
│   │   ├── youtube.server.ts        # InnerTube client, format resolution, caption fetcher
│   │   ├── transcript.ts            # WebVTT parser, SRT/TXT/JSON formatters, AI templates
│   │   ├── ytdlp.server.ts          # Process management, fallback ladder, slot throttler
│   │   ├── stream-unlock.ts         # Stream cipher / signature / nsig deciphering
│   │   ├── cookies.ts               # Netscape/JSON/HAR cookie parser and validator
│   │   ├── vault.ts                 # Server-side encrypted cookie credential vault
│   │   └── guest-limit.server.ts    # Rate limiting & quota enforcement for guest IPs
│   └── routes/
│       ├── __root.tsx               # Root application layout
│       ├── index.tsx                # Main video search, analyzer, and download page
│       ├── login.tsx                # Authentication page
│       └── api/                     # Backend streaming and RPC routes
├── scripts/
│   ├── browser-smoke.mjs            # Automated Playwright desktop & mobile render test
│   ├── auto-update.mjs              # Verified dependency + yt-dlp updater with rollback
│   └── migrate.mjs                  # Database schema migration runner
└── package.json

---

Getting Started

Prerequisites

• Node.js: v22.0.0 or later

• npm: v10 or later

• Python / yt-dlp / ffmpeg (optional for local development, pre-configured in sandbox)

  Velo is TypeScript end to end, but the yt-dlp extraction path shells out to Python (python3 -m yt_dlp). Without it the app still runs — the browser hybrid and InnerTube paths cover most videos — but 1080p muxing over SOCKS, the most reliable path, is unavailable. Install with:

  python3 -m pip install -U "yt-dlp[default,curl-cffi]"

  The extras bring the --impersonate backend and the EJS signature solver in the versions this yt-dlp supports; yt-dlp also needs ffmpeg on PATH to merge 1080p video with its audio.

  On Debian 12+ / Ubuntu 23.04+ the system Python refuses that ("externally-managed-environment", PEP 668). Use a virtualenv and point Velo at it — this also works for pyenv, or a distro that only ships python:

  python3 -m venv ~/.velo-py
  ~/.velo-py/bin/pip install -U "yt-dlp[default,curl-cffi]"
  export VELO_PYTHON=~/.velo-py/bin/python   # PYTHON_BIN also works

  npm run update:deps upgrades yt-dlp inside that same interpreter.

  Velo probes the runtime once per process and reports which piece is missing — the interpreter or the yt_dlp module — rather than failing per download.

Installation

1. Clone the repository:

   git clone https://github.com/EgerDev/velo.git
   cd velo

2. Install dependencies:

   npm install

3. Start the development server:

   npm run dev

   Open http://localhost:8080 in your browser.

---

Verification & Testing

Run all unit tests across the media engine, transcript parser, cookie validator, and quota system:

npm test

Run TypeScript checks and ESLint:

npm run typecheck
npm run lint

Build for production and verify with browser smoke tests:

npm run build
node scripts/browser-smoke.mjs

---

Keeping Dependencies Current

Extraction depends on libraries that track a moving target: youtubei.js and bgutils-js follow the YouTube player, and the yt-dlp Python module ships roughly monthly because YouTube keeps breaking it. Once they go stale, extraction fails for reasons that look like bugs in this repo.

npm run update:check   # report what is behind; exits 1 if there is work (CI)
npm run update:deps    # apply in-range updates + yt-dlp, verified

update:deps never leaves the tree red. Each install is followed by typecheck + test + lint, and anything that fails is rolled back to the exact package.json and package-lock.json that were on disk beforehand. The in-range updates land as one batch and are bisected package-by-package if that batch fails, so a single bad release does not hold back the rest.

Two kinds of version are left alone unless you ask for them:

Flag	What it unlocks
--major	Versions past a spec's ceiling, rewriting the range in package.json. Applied one at a time.
--pinned	Exact specs such as jose: "6.2.9" and nitro, which are pinned deliberately.

Names under overrides are never bumped — the override would silently win over the direct spec. Other useful flags: --dry-run, --only=pkg,pkg, --skip-tests, --skip-ytdlp.

---

License

MIT License. Designed and built with modern web standards.