Quick Start

This guide shows the fastest ways to use videodl from the command line and from Python.

videodl supports two common workflows:

  1. Parse and download in one step

  2. Parse first, inspect the result, then download

Quick Use Videodl from Command Line

(1) Download a video from a URL

videodl -i "https://www.acfun.cn/v/ac36491489"

If videodl can find a matching client, it will parse the URL and start downloading automatically.

The demonstration is as follows,


(2) Start interactive mode

If -i is not provided, videodl starts in terminal mode:

videodl

Then enter a video URL when prompted. In interactive mode:

  • enter q to quit

  • enter r to restart the UI

(3) Restrict parsing to specific clients

If the URL belongs to a known platform, specifying the client is usually faster.

videodl -i "https://www.acfun.cn/v/ac36491489" -a "AcFunVideoClient"

You can also provide multiple clients:

videodl -i "URL" -a "AcFunVideoClient,BilibiliVideoClient"

(4) Use only common / generic parsers

videodl -i "URL" -g

This is equivalent to apply_common_video_clients_only=True in Python.

(5) Set client config from the command line

Some options are passed as JSON strings.

Example: change the output directory for one client:

videodl -i "https://www.acfun.cn/v/ac36491489" \
  -a "AcFunVideoClient" \
  -c '{"AcFunVideoClient": {"work_dir": "downloads"}}'

Example: pass custom headers or proxies:

videodl -i "URL" \
  -r '{"AcFunVideoClient": {"headers": {"User-Agent": "Mozilla/5.0"}, "proxies": {"http": "http://127.0.0.1:7890", "https": "http://127.0.0.1:7890"}}}'

(6) CLI options

Usage: videodl [OPTIONS]

Options:
  --version                       Show the version and exit.
  -i, --index-url, --index_url TEXT
                                  URL of the video to download. If not
                                  specified, videodl will start in terminal
                                  mode.
  -a, --allowed-video-sources, --allowed_video_sources TEXT
                                  Platforms to search. Separate multiple
                                  platforms with "," (e.g.,
                                  "AcFunVideoClient,PipixVideoClient"). If not
                                  specified, videodl will search all supported
                                  platforms globally and use the first one
                                  that can download the video url.
  -c, --init-video-clients-cfg, --init_video_clients_cfg TEXT
                                  Config such as `work_dir` for each video
                                  client as a JSON string.
  -r, --requests-overrides, --requests_overrides TEXT
                                  Requests.get kwargs such as `headers` and
                                  `proxies` for each video client as a JSON
                                  string.
  -t, --clients-threadings, --clients_threadings TEXT
                                  Number of threads used for each video client
                                  as a JSON string.
  -g, --apply-common-video-clients-only, --apply_common_video_clients_only
                                  Only apply common video clients.
  --help                          Show this message and exit.

Quick Use Videodl from Python

(1) Create a VideoClient

from videodl import videodl

video_client = videodl.VideoClient()

This creates a high-level client that can:

  • choose a suitable parser

  • parse a URL into one or more VideoInfo objects

  • download the parsed videos

(2) Parse and download in one step

from videodl import videodl

video_client = videodl.VideoClient()
video_infos = video_client.parsefromurl("https://www.acfun.cn/v/ac36491489")
video_client.download(video_infos)

(3) Start interactive mode from Python

from videodl import videodl

video_client = videodl.VideoClient()
video_client.startparseurlcmdui()

(4) Use only selected clients

from videodl import videodl

video_client = videodl.VideoClient(
    allowed_video_sources=["AcFunVideoClient"]
)
video_infos = video_client.parsefromurl("https://www.acfun.cn/v/ac36491489")
video_client.download(video_infos)

(5) Use only common / generic clients

from videodl import videodl

video_client = videodl.VideoClient(apply_common_video_clients_only=True)
video_infos = video_client.parsefromurl("URL")
video_client.download(video_infos)

Parse First, Then Inspect the Result

Sometimes it is useful to inspect the parsed result before downloading.

from videodl import videodl

video_client = videodl.VideoClient(allowed_video_sources=["AcFunVideoClient"])
video_infos = video_client.parsefromurl("https://www.acfun.cn/v/ac36491489")

for info in video_infos:
    print(info["source"])
    print(info["title"])
    print(info["download_url"])
    print(info["save_path"])
    print(info["ext"])
    print(info["err_msg"])

A parsed item is a VideoInfo object. It behaves like both a dataclass object and a dictionary.

For example, both styles work:

info = video_infos[0]
print(info.title)
print(info["title"])

Common fields include:

  • source: which client produced this result

  • title: video title

  • download_url: resolved media URL

  • save_path: output file path

  • ext: file extension

  • err_msg: parsing error, if any

  • download_with_ffmpeg: whether ffmpeg should be used

  • download_with_aria2c: whether aria2c should be used

  • enable_nm3u8dlre: whether N_m3u8DL-RE should be used

Download a Parsed Result Later

Once video_infos is ready, download it like this:

video_client.download(video_infos)

You can also modify the parsed result before downloading.

Example: enable aria2c for a direct file download:

for info in video_infos:
    info["download_with_aria2c"] = True

video_client.download(video_infos)

Example: enable N_m3u8DL-RE for HLS / m3u8 downloads:

for info in video_infos:
    info["enable_nm3u8dlre"] = True

video_client.download(video_infos)

Example: force ffmpeg download:

for info in video_infos:
    info["download_with_ffmpeg"] = True

video_client.download(video_infos)

Common Configuration Examples

(1) Change the output directory

from videodl import videodl

video_client = videodl.VideoClient(
    init_video_clients_cfg={
        "AcFunVideoClient": {
            "work_dir": "downloads"
        }
    },
    allowed_video_sources=["AcFunVideoClient"]
)

(2) Pass cookies for parsing or downloading

from videodl import videodl

cookies = "your cookies here"

video_client = videodl.VideoClient(
    init_video_clients_cfg={
        "SomeVideoClient": {
            "default_parse_cookies": cookies,
            "default_download_cookies": cookies,
        }
    },
    allowed_video_sources=["SomeVideoClient"]
)

(3) Pass custom request options

requests_overrides is useful when a client needs extra headers, cookies, timeout settings, or proxies.

from videodl import videodl

video_client = videodl.VideoClient(
    requests_overrides={
        "AcFunVideoClient": {
            "headers": {
                "User-Agent": "Mozilla/5.0"
            },
            "proxies": {
                "http": "http://127.0.0.1:7890",
                "https": "http://127.0.0.1:7890"
            }
        }
    },
    allowed_video_sources=["AcFunVideoClient"]
)

(4) Set download threads per client

from videodl import videodl

video_client = videodl.VideoClient(
    clients_threadings={
        "AcFunVideoClient": 8
    },
    allowed_video_sources=["AcFunVideoClient"]
)

Direct Media URLs

If the input URL is already a direct media link, videodl will try to handle it directly without needing a platform-specific / general-purpose video client as a parser.

from videodl import videodl

video_client = videodl.VideoClient()
video_infos = video_client.parsefromurl("https://example.com/video.mp4")
video_client.download(video_infos)

Tips

(1) Prefer specific clients when possible

This is usually faster:

video_client = videodl.VideoClient(allowed_video_sources=["AcFunVideoClient"])

than searching through all supported clients.

(2) Generic parsers are useful when platform-specific parsing does not work

Use:

videodl.VideoClient(apply_common_video_clients_only=True)

or on the CLI:

videodl -g -i "URL"

(3) Some download accelerators require external tools

Depending on how a video is parsed, videodl may work with:

  • ffmpeg

  • aria2c

  • N_m3u8DL-RE

Make sure they are installed and available in your environment before enabling them.

(4) A parse result may contain multiple videos

Some URLs may return more than one VideoInfo, so always treat the return value of parsefromurl() as a list.