VDL

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.

It is designed around three surfaces:

External products own their own persistence and product workflows. VDL provides the media execution capability; it does not try to become a media library app.

Full developer documentation is live at: https://video-downloader-657d90.gitlab.io

flowchart TD
  StandaloneBinary["Standalone binary<br/>(curl install.sh)"]
  PythonPkg["Python package<br/>(pip install vdl)"]
  
  StandaloneBinary --> CLI["vdl CLI"]
  StandaloneBinary --> App["Interactive app"]
  StandaloneBinary --> MCP1["vdl-mcp"]
  
  PythonPkg --> Library["Python library"]
  PythonPkg --> CLI
  PythonPkg --> App
  PythonPkg --> Tools["vdl.tools"]
  PythonPkg --> MCP2["MCP server<br/>(mcp extra)"]

Install vdl Binary

Use the standalone installer when you want the commands without setting up a Python project:

macOS / Linux:

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

Windows:

irm https://bildcraft.gitlab.io/products/video-downloader/vdl/install.ps1 | iex

This gives you:

• vdl
• vdl-mcp

Re-running the standalone installer is safe:

• installs if VDL is missing
• updates if the installed version is older
• does nothing if the same version is already installed
• checks required dependencies before replacing binaries

Interactive Download App

Start the interactive app with:

vdl

It opens an interactive terminal interface:

The app guides you through:

1. Input — paste a URL, local file path, or .txt link list
2. Quality — choose preferred resolution (best, 2160p, 1440p, 1080p, 720p, 480p, or audio)
3. Output — set download directory (default: ~/Downloads/VDL)
4. Options — save thumbnails and subtitles
5. Mode — download directly or crawl the page for more links

Perfect for downloading single videos, playlists, or discovering downloadable media on websites.

YouTube 4K support

Numbered quality requests are strict: --quality 2160p fails rather than silently saving a lower-resolution file. Add --fallback to permit the best available lower resolution.

VDL installs the yt-dlp PO-token plugin with its normal package dependencies. Some YouTube high-quality streams also require the separate provider service:

Run the matching bgutil provider service separately, bound to loopback only:

docker run --name bgutil-provider -d --init \
  -p 127.0.0.1:4416:4416 \
  brainicism/bgutil-ytdlp-pot-provider:2.0.0

Use vdl doctor to confirm the plugin and local service are ready. VDL does not manage provider updates or tokens; see the provider documentation and yt-dlp PO-token guide.

The interactive app is intentionally stateful: it creates local app directories, SQLite state, and logs so it can provide history/status/session UX.

CLI Commands

Check the installed binary:

vdl --version

Run direct commands:

vdl download https://example.com/video
vdl crawl https://example.com/gallery --first 3
vdl crawl https://example.com/gallery --crawl-pagination --first 3
vdl playlist https://example.com/playlist
vdl resolve https://example.com/playlist
vdl status
vdl doctor

These headless commands are stateless by default. They do not implicitly create the interactive SQLite database or app logs.

Crawl-specific behavior is intentionally different from direct download and playlist flows:

• vdl crawl ... --first 3 means first 3 successful downloads, not first 3 discovered links
• crawl applies its own admission policy, including a default 7 MB minimum file size
• --allow-tiny disables that crawl-only minimum
• --crawl-pagination follows pagination/navigation pages discovered during crawl
• direct downloads and playlists are not guarded by the crawl minimum, which keeps audio and other intentional small downloads working normally

When a site needs authentication, the headless commands can take cookies too:

vdl download --cookies cookies.txt https://example.com/video
vdl crawl --cookies-from-browser firefox https://example.com/gallery --first 3

Install as Python Library

Use the Python package when you want to embed VDL in another Python project:

pip install vdl

The full Python/library docs are live at: https://video-downloader-657d90.gitlab.io/python-api/

That gives you:

• the vdl Python library
• the vdl CLI
• the interactive app entrypoint
• vdl.tools

Use the library directly:

import asyncio

from vdl import CrawlerPolicy, VDLClient


async def main() -> None:
    client = VDLClient()
    result = await client.download("https://example.com/video")
    print(result.status)

    crawl_plan = await client.discover(
        "https://example.com/gallery",
        crawler_policy=CrawlerPolicy(crawl_pagination_pages=True),
    )
    crawl_results = await client.execute_plan(
        crawl_plan,
        crawler_policy=CrawlerPolicy(first_successful=3),
    )
    print(len(crawl_results))


asyncio.run(main())

The library is stateless by default and embeddable. Your application owns any database, history, user library, retries, or product-specific workflow state.

Use the tool surface:

import asyncio

from vdl.tools import download_video


async def main() -> None:
    result = await download_video("https://example.com/video")
    print(result["status"])


asyncio.run(main())

MCP Support

Install the MCP extra when you want vdl-mcp:

pip install "vdl[mcp]"

That adds MCP support on top of the Python package. If you installed the standalone binary, vdl-mcp is already included there too.

Example MCP client config:

{
  "mcpServers": {
    "vdl": {
      "command": "vdl-mcp",
      "args": []
    }
  }
}

Examples

Each demo in demos/ illustrates a single workflow:

All demos use placeholder URLs — copy and edit with your own.