Skip to content
BranchesTags

Repository files navigation

🇬🇧 English | 🇻🇳 Tiếng Việt

⚡ TokenVector Media Downloader

TokenVector Cross Platform CI Passing Binary Size License Sponsor

🌟 Overview

TokenVector Media Downloader is a high-performance, cross-platform (Windows, Linux, macOS) media downloader written entirely in the TokenVector (.tkv) programming language.

Unlike traditional media downloaders that are notoriously heavy (often 30 MB – 150 MB due to bundling Python runtimes, Node.js, or Chromium engines), TokenVector Downloader harnesses the power of the TokenVector Compiler (tkvc) to compile directly to native Common Intermediate Language (CIL/MSIL) bytecode. This delivers:

  • 🚀 Ultra-lightweight binary: Full-featured GUI application weighs only ~32 KB, CLI only ~25 KB!
  • ⚡ Instant startup: 0-second delay, minimal RAM footprint (< 15 MB under load).
  • 🛡️ Zero Dependencies: Fully standalone, direct native HTTP/HTTPS streaming, HLS parsing, and stream resolution.
  • 🌐 True Cross-Platform: Runs seamlessly on Windows (Native PE), Linux (Ubuntu, Debian, Arch...), and macOS (Apple Silicon & Intel) in both Graphical User Interface (GUI) and Command-Line Interface (CLI) modes.

⚖️ Detailed Comparison: TokenVector Media Downloader vs. yt-dlp

Feature / Metric ⚡ TokenVector Media Downloader 🐢 yt-dlp (Traditional) The TokenVector Advantage
Programming Language TokenVector (.tkv) Python (C-Python runtime) Clean modern language, optimized native CIL architecture
Executable Size (.exe) ~32 KB (GUI) / ~25 KB (CLI) ~17 MB – 85 MB (PyInstaller bundle) Over 500x lighter
Third-Party Dependencies 0 (Zero Dependency) Requires Python Runtime, FFmpeg (~80 MB) to merge audio/video Runs out-of-the-box, no external utilities needed
User Interface (UI) Cross-platform GUI (WinForms) & CLI Command-Line only (requires complex wrappers) Intuitive, responsive UI across Windows, Linux & macOS
Startup Latency Instant (< 50ms) 1.5s – 3.5s (due to unpacking Python environment) Significantly faster, zero noticeable lag
RAM Footprint ~12 MB – 18 MB ~60 MB – 150 MB (Python VM + child processes) Maximum system resource efficiency
Progress Indicator Adaptive: Exact % & animated pulsing glow (Marquee) Plain console text output Smooth visual tracking
Safe Stop & Cleanup One-touch STOP button, instantly releases threads & cleans .part files Pressing Ctrl+C often leaves orphaned temp files Safe for disk storage, never leaves corrupted files
HLS Stream (.m3u8) Support Built-in Native CIL HLS Parser & 3-Layer Anti-Ad Filter Relies on external FFmpeg binary Direct .m3u8 & web embed extractor, filters out 5s/15s ads, merges into MP4 without FFmpeg
Transcript & Subtitle Extraction Dedicated [ GET TRANSCRIPT ] button (downloads both .srt & _transcript.txt) Requires extra Python script (yt-dlp-transcript) + srt lib 1-click instant extraction, no Python, LLM AI ready
Packaging & Portability Single portable ~28 KB file for Windows, Linux & macOS Requires multi-megabyte installers or Python/Pip setup Instant distribution via Email, Chat, AirDrop

💡 Summary: While yt-dlp is a heavyweight tool packing an entire Python ecosystem, TokenVector Media Downloader is an ultra-lean, laser-focused native utility: lightning fast, featherlight size, responsive GUI, and 100% dependency-free.

💎 Core Engine: The Power of TokenVector

TokenVector is an advanced programming language designed and developed by Trần Nguyên Hùng, featuring elegant syntax, direct CIL/Assembly interop, and extreme binary optimization:

  • Direct .NET CLR & Win32 Interop: Native instantiation of System.Windows.Forms components, asynchronous thread control, and high-performance network sockets.
  • High-Throughput Smart Buffer: Network streaming utilizing an optimal 128 KB (131072 bytes) buffer to minimize CPU context-switching and saturate network bandwidth.
  • Instant Cancel & Clean Safety Engine: Allows users to halt active downloads instantly via the STOP button, properly releasing file locks and purging incomplete .part temporary files.

✨ Key Features

  • Dedicated "GET TRANSCRIPT" Button (1-Click Subtitles & Transcript Extraction):
    • 🔘 Independent Operation: No need to navigate dropdown menus—paste the URL and click [ GET TRANSCRIPT ] to download immediately.
    • 📝 Simultaneous Dual-Format Output:
      • [Video_Title].srt: Standard subtitle file with millisecond-accurate timestamps, ready for VLC, YouTube, CapCut, Premiere, etc.
      • [Video_Title]_transcript.txt: Formatted timeline transcript with clean [mm:ss] (or [hh:mm:ss]) timestamps on every line, perfectly matching YouTube's video timeline for effortless reading, quick reference, and AI summarization.
    • ⚡ 100% Native TokenVector CIL: Directly negotiates with YouTube InnerTube API (Android Client) to bypass PO token restrictions without Python, yt-dlp.exe, or FFmpeg. Extracts in ~1 second!
  • Standardized Clean English UI:
    • Completely avoids legacy ANSI/Unicode code-page rendering issues on Windows Forms.
    • Symmetrical 3-button layout: [ DOWNLOAD ] | [ GET TRANSCRIPT ] | [ STOP ].
    • Empty default Video URL input for quick and clean paste upon launching.
  • Comprehensive Video & Audio Format Support:
    • 🎬 Video: MP4 (480p Standard - Default), MP4 (720p HD), MP4 (1080p Full HD), MKV (1080p High Quality), WebM (Original Quality).
    • 🎵 Audio: MP3 (Most Popular, 320kbps), M4A (AAC High Quality), WAV (Lossless Uncompressed), FLAC (Lossless Studio Master).
    • 📜 Subtitles / Transcript: Subtitle: Transcript & SRT (.srt & .txt - YouTube Transcript).
  • Dynamic Adaptive ProgressBar:
    • Automatically displays exact percentage when the server provides Content-Length.
    • Seamlessly switches to pulsing marquee animation (ProgressBarStyle.Marquee) for Transfer-Encoding: chunked streams, reporting real-time received megabytes.
  • Custom Output Directory Selection & STA Threading Architecture:
    • Fast, responsive folder picker (Browse...) powered by Single-Threaded Apartment (STA) thread model.
    • Passes native window handle owner and cleans up COM dialog handles properly, completely preventing GUI freezing or (Not Responding) states.
  • Native HLS Stream Downloader (.m3u8 Direct Extraction):
    • 🎬 Automatic M3U8 Detection: Simply paste any direct HLS playlist URL (.m3u8) or supported web player page and click [ DOWNLOAD ]. The engine detects the playlist, resolves variants, downloads .ts segments, and merges them into a clean .mp4 file.
    • ⚡ Zero-Dependency Merging: 100% native CIL binary streaming and packet stitching without needing FFmpeg or external tools.
    • 📊 Segment Progress & Instant Stop: Real-time segment progress counter (X/Y segments - %) with one-click STOP to halt and clean temporary files immediately.
  • Facebook Videos & Reels Downloader:
    • 🔵 Paste any public Facebook video, Reel or fb.watch link and click [ DOWNLOAD ] — no login, no cookies, no yt-dlp/FFmpeg needed.
    • 🔗 Bare links work too: facebook.com/... or fb.watch/... pasted without https:// are completed automatically.
    • 🛡️ If a resolved link turns out to be an expired placeholder page instead of video bytes, it is deleted automatically and reported clearly instead of leaving a fake .mp4 behind.
  • TikTok Videos Downloader:
    • 🎵 Paste a TikTok video link (tiktok.com/@user/video/...) and click [ DOWNLOAD ] — the app resolves the direct MP4 and saves it under the video title (GUI) or as tiktok_video.mp4 (CLI).
  • Facebook CLI notes: the CLI saves Facebook downloads as facebook_video.mp4 and reports a distinct error code for each outcome (0 ok, 2 page/API unreachable, 3 no video link found, 4 file download failed, 5 placeholder pages on every attempt).
  • AI-Ready CLI (--json + SKILL.md): add --json in any position and stdout becomes exactly one machine-readable line, e.g. {"status":"ok","platform":"tiktok","file":"tiktok_video.mp4"} — so any AI agent with shell access can download videos reliably. See SKILL.md for the agent contract (error codes, public-only rule, file verification).
  • Both GUI and CLI Editions Included:
    • tv-downloader-gui.exe: Modern graphical user application (~32 KB).
    • tv-downloader-cli.exe: Terminal utility for scripting and automated workflows (~25 KB). Usage: tv-downloader-cli.exe <media_url> [c_user] [xs].

📦 Project Layout & Structure

TokenVector-Media-Downloader/
├── .github/workflows/        # Automated CI/CD Matrix (Ubuntu, macOS, Windows)
├── src/                      # Native TokenVector source code (.tkv)
│   ├── gui_runner.tkv        # GUI application entrypoint (Entry: run)
│   ├── cli_runner.tkv        # CLI application entrypoint (Entry: main)
│   └── core_engine.tkv       # Download orchestration, network stream & POSIX bridge
├── il_features/              # CIL compiler features & WinForms UI modules
│   ├── win32_gui_window.tkv  # Native WinForms UI & stream decoding logic
│   └── ...                   # TokenVector IL library modules
├── tv-downloader-gui.exe     # Compiled GUI executable (~32 KB, runs on Win/Linux/macOS)
├── tv-downloader-cli.exe     # Compiled CLI executable (~25 KB, runs on Win/Linux/macOS)
├── build.bat                 # Windows automated build script
├── build.sh                  # Linux & macOS automated build script
├── USER_GUIDE.txt            # Quick user manual (Vietnamese)
├── USER_GUIDE_EN.md          # Quick user manual (English)
├── DEV_GUIDE.md              # TokenVector coding & build guide (English)
├── DEV_GUIDE_VI.md           # TokenVector coding & build guide (Vietnamese)
├── SKILL.md                  # Agent contract: use the CLI as an AI tool
├── llms.txt                  # AI-readable project summary
├── LICENSE                   # MIT License
├── README.md                 # English documentation (this file)
└── README.vi.md              # Vietnamese documentation (Tài liệu tiếng Việt)

Running the Application:

  • On Windows:
    • Launch GUI: Double-click tv-downloader-gui.exe.
    • Launch CLI: Open Command Prompt / PowerShell: .\tv-downloader-cli.exe <media_url>.
  • On Linux (Ubuntu/Debian):
    • Prerequisites: sudo apt-get install -y mono-runtime libmono-system-windows-forms4.0-cil libgdiplus xvfb
    • GUI: xvfb-run mono tv-downloader-gui.exe (xvfb-run only needed on headless servers; skip it on desktop).
    • CLI: mono tv-downloader-cli.exe <media_url>
  • On macOS:
    • Prerequisites: Mono MDK + XQuartz.
    • GUI: mono tv-downloader-gui.exe
    • CLI: mono tv-downloader-cli.exe <media_url>

✅ Verified Cross-Platform Status (both files, zero Win32 P/Invoke):

File Windows Linux macOS
tv-downloader-cli.exe (~25 KB) Native ✅ Verified on Ubuntu + Mono 6.8 ✅ (banner, demo flow, live TikTok download byte-identical to Windows) Expected via Mono (covered by CI matrix, not yet run locally)
tv-downloader-gui.exe (~32 KB) Native ✅ Verified rendered & running (Xvfb + openbox screenshot: full form, inputs, buttons, progress) ✅ Expected via Mono + XQuartz (not yet run locally)

Notes: the GUI needs an X server (hence xvfb-run on headless machines) and libgdiplus for text rendering; the os_system bridge auto-selects /bin/sh on POSIX instead of cmd.exe.

🛠️ Building from Source (.tkv)

You can compile the .tkv source code into native executables using the TokenVector Compiler (tkvc.exe) from the TokenVector project:

1. Compile GUI Application:

# From the project root:
tkvc.exe build src\gui_runner.tkv --entry run --out tv-downloader-gui.exe

2. Compile CLI Application:

tkvc.exe build src\cli_runner.tkv --entry main --out tv-downloader-cli.exe

3. Running on Linux & macOS:

The compiled binaries target .NET CIL bytecode, enabling full support for both GUI (Windows Forms) and CLI on Linux and macOS via the Mono runtime:

A. On Linux (Ubuntu / Debian / Linux Mint):

# 1. Install Mono runtime and GDI+ / WinForms libraries:
sudo apt-get update
sudo apt-get install -y mono-runtime mono-devel libgdiplus mono-winforms

# 2. Launch GUI:
mono tv-downloader-gui.exe

# 3. Launch CLI:
mono tv-downloader-cli.exe <media_url>

B. On macOS:

# 1. Install Mono MDK and XQuartz (X11 server for WinForms rendering):
brew install --cask xquartz mono-mdk

# 2. Launch GUI:
mono tv-downloader-gui.exe

# 3. Launch CLI:
mono tv-downloader-cli.exe <media_url>

📄 License

This project is licensed under the MIT License. Feel free to use, modify, and distribute.

💖 Support This Project

If this tool saves you time, consider sponsoring — every coffee keeps the binaries tiny and the updates coming:

👨‍💻 Author & Contact

Engineered with passion using the TokenVector programming language.

About

Ultra-lightweight media downloader (~32KB) written in TokenVector (.tkv) and compiled to native CIL. Download YouTube, Facebook & TikTok with GUI + CLI on Windows, Linux and macOS. Zero dependencies — no Python, yt-dlp or FFmpeg. Auto retry, content validation, HLS and transcript support.

Topics

clicli-toolfacebook-downloaderlinux-appmacos-appmedia-downloadertiktok-downloader-2026tiktok-downloader-apptiktok-downloader-freetokenvectorvideo-dowloaderwindows-appyoutube-downloaderyt-dlpyt-dlp-guiyt-downloaderytdlytdl-coreytdlp

Resources

Readme
License
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages