# VDL

![VDL logo](docs/assets/vdl-logo.svg)

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.

```mermaid
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:

```bash
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:

```bash
vdl
```

It opens an interactive terminal interface:

![VDL Interactive App](docs/assets/vdl-app.png)

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:

```bash
vdl --version
```

Run direct commands:

```bash
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:

```bash
pip install vdl
```

That gives you:
- the `vdl` Python library
- the `vdl` CLI
- the interactive app entrypoint
- `vdl.tools`

Use the library directly:

```python
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:

```python
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`:

```bash
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:

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

## Examples

Each demo in [`demos/`](demos/) illustrates a single workflow:

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

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