Skip to content

VDL Documentation

VDL is a local-first media workflow runtime for building apps and workflows around video downloads, playlists, page discovery, link lists, progress events, and structured results.

VDL is most useful when you are building an application or automation workflow that needs downloads to be programmable, observable, cancellable, and structured. For simple one-off downloads, lower-level download tools may already be enough; VDL's value is the application layer around media execution.

Three Surfaces

Surface State Model Use It For
Python library Stateless by default Embedding download/discovery capability in another app
Headless CLI Stateless by default Scripts, one-shot jobs, and automation
Interactive app Intentionally stateful Guided terminal UX with local history, status, SQLite, and logs

External products own their own persistence, media library, user history, intelligence features, and product-specific workflows. VDL owns the media download/discovery execution capability.

🚀 Getting Started

📺 Usage

🐍 Python Library

🔧 Advanced

🏗️ Architecture

💻 Development

Features at a Glance

Feature Description
Downloads Single or batch video downloads with quality selection
Playlists Resolve and download with concurrent item fetching
Planning Classify input (URL, file, playlist) locally without network calls
Discovery Crawl web pages for downloadable media using vdl crawl or VDLClient.discover()
State Optional SQLite tracking of downloads and statuses (interactive mode only)
Collision Policy Handle existing files: rename, skip, overwrite, or fail
Progress Real-time callbacks or rich terminal UI with speed/ETA
Cancellation Thread-safe cancellation tokens with per-task control
Config TOML configuration in ~/.config/vdl/, with CLI overrides
Doctor Health check for ffmpeg, yt-dlp, and VDL dependencies
MCP Claude Desktop and AI agent integration via MCP protocol

Architecture Overview

graph TB
    subgraph User["User Interfaces"]
        CLI["CLI<br/>(vdl)"]
        Interactive["Interactive App"]
        MCP["MCP Server<br/>(vdl-mcp)"]
        Library["Python Library"]
    end

    subgraph Core["Core Facade"]
        Client["VDLClient"]
    end

    subgraph Services["Services"]
        Planner["InputPlanner"]
        Execution["DownloadExecutionService"]
        Playlist["PlaylistService"]
        Discovery["DiscoveryService"]
        Doctor["Doctor"]
    end

    subgraph Infrastructure["Infrastructure"]
        Downloader["YtDlpDownloader"]
        Resolver["YtDlpPlaylistResolver"]
        State["SQLiteStateStore<br/>(opt-in)"]
        Config["TomlConfigStore"]
        Logger["FileEventLogger<br/>(opt-in)"]
        Crawler["SiteRuleDiscoveryResolver"]
    end

    External["yt-dlp<br/>ffmpeg<br/>ffprobe"]

    CLI --> Client
    Interactive --> Client
    MCP --> Client
    Library --> Client

    Client --> Planner
    Client --> Execution
    Client --> Playlist
    Client --> Discovery
    Client --> Doctor

    Execution --> Downloader
    Playlist --> Resolver
    Execution --> State
    Discovery --> Crawler
    Downloader --> External
    Resolver --> External

Installation Preview

curl -fsSL https://bildcraft.gitlab.io/products/video-downloader/vdl/install.sh | sh
vdl --version

pip install vdl
# Or with MCP support:
pip install "vdl[mcp]"

git clone https://gitlab.com/bildcraft/products/video-downloader
cd video-downloader
uv sync
PYTHONPATH=src uv run vdl --version

Next Steps