vdl 1.0.4

A local-first media workflow toolkit for downloads, playlists, and automation through CLI and MCP interfaces

VDL

VDL is a local-first media workflow toolkit for downloading videos, downloading playlists, crawling websites for downloadable media, managing local link lists, and automating those workflows from the CLI, Python library, tool API, or MCP.

flowchart TD
  StandaloneBinary["curl install.sh<br/>Standalone binary"]
  PythonPkg["pip install vdl<br/>Python package"]
  
  StandaloneBinary --> CLI["vdl CLI"]
  StandaloneBinary --> App["Interactive app"]
  StandaloneBinary --> MCP1["vdl-mcp"]
  
  PythonPkg --> Library["Python library<br/>import vdl"]
  PythonPkg --> CLI
  PythonPkg --> App
  PythonPkg --> Tools["vdl.tools"]
  PythonPkg --> MCP2["MCP server<br/>pip install vdl[mcp]"]
  
  style StandaloneBinary fill:#0277bd,color:#fff
  style PythonPkg fill:#7b1fa2,color:#fff
  style MCP2 fill:#e65100,color:#fff

Install vdl Binary

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

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

This gives you:

• vdl
• vdl-mcp

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.

CLI Commands

Check the installed binary:

vdl --version

Run direct commands:

vdl download https://example.com/video
vdl playlist https://example.com/playlist
vdl resolve https://example.com/playlist
vdl status
vdl doctor

Install as Python Library

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

pip install vdl

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 VDLClient


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


asyncio.run(main())

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:

Demo	Use Case
download_video.py	Download a single video
download_video_with_progress.py	Track download progress in real-time
download_playlist.py	Download an entire playlist
resolve_playlist.py	Inspect playlist items before downloading
download_link_file.py	Batch download URLs from a .txt file
crawl_websites.py	Discover and download media on a webpage

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