Videodl APIs

This document describes the main public APIs for working with video parsing and downloading in videodl.

It focuses on three parts:

VideoClient: the main high-level entry point.
BaseVideoClient: the base class used by site-specific clients.
VideoInfo: the result object returned by parsing and downloading methods.

`VideoClient`

VideoClient is the main class for external use.

It manages multiple video backends, chooses the right parser for a URL, and dispatches downloads to the correct client automatically.

Module path:

videodl.videodl.VideoClient

Constructor:

VideoClient(
    allowed_video_sources: list | None = None,
    init_video_clients_cfg: dict | None = None,
    clients_threadings: dict | None = None,
    requests_overrides: dict | None = None,
    apply_common_video_clients_only: bool = False,
)

Arguments:

allowed_video_sources

A list of enabled client names.
- If this is None or empty, VideoClient enables all registered clients.
- Each item should be a client name such as "AcFunVideoClient".
Example:
```
allowed_video_sources = ["AcFunVideoClient"]
```
init_video_clients_cfg

Per-client initialization settings.
- The key is the client name.
- The value is a dictionary of constructor arguments passed to that client.
- This is useful when different sources need different work directories, cookies, retry settings, or proxy behavior.
Common options include:
- work_dir
- auto_set_proxies
- random_update_ua
- max_retries
- maintain_session
- disable_print
- freeproxy_settings
- default_search_cookies
- default_download_cookies
- default_parse_cookies
Advanced options supported by BaseVideoClient can also be passed here, for example:
- enable_parse_curl_cffi
- enable_search_curl_cffi
- enable_download_curl_cffi
Example:
```
init_video_clients_cfg = {
    "SohuVideoClient": {
        "work_dir": "downloads/sohu",
        "max_retries": 3,
        "maintain_session": True,
    }
}
```
clients_threadings

Per-client download thread counts.
- The key is the client name.
- The value is the number of download threads for that source.
- If a source is not included, 5 is used by default.
Example:
```
clients_threadings = {
    "XinpianchangVideoClient": 3,
}
```

requests_overrides

Per-client request settings used during parsing and downloading.

Typical fields are:

headers
cookies
proxies

Example:

requests_overrides = {
    "TencentVideoClient": {
        "headers": {"User-Agent": "Mozilla/5.0"},
        "cookies": {"sessionid": "example"}
    }
}

apply_common_video_clients_only

Whether to use only the generic parsers.
- False: try platform-specific clients first, then generic parsers if needed.
- True: skip platform-specific clients and use only common parsers.
This can be useful when the target URL is not from a built-in supported site.

`VideoClient.parsefromurl()`

Parse a video URL and return one or more VideoInfo objects.

VideoClient.parsefromurl(url: str) -> list[VideoInfo]

Parsing behavior:

When VideoClient.parsefromurl() is called, VideoClient uses the following strategy:

Check whether the URL looks like a direct media link.
If not, try platform-specific clients, unless apply_common_video_clients_only=True.
If still no valid result is found, try generic parsers.
If needed, fall back to the web media grabber.

This logic is internal. In normal use, only a URL needs to be provided.

A single URL may return:

one item for a normal video,
multiple items for multi-part content,
or an empty result if parsing fails.

Example:

from videodl.videodl import VideoClient

client = VideoClient(
    allowed_video_sources=["AcFunVideoClient"],
    requests_overrides={
        "AcFunVideoClient": {
            "headers": {"User-Agent": "Mozilla/5.0"}
        }
    }
)

video_infos = client.parsefromurl("https://www.acfun.cn/v/ac123456")

for info in video_infos:
    print(info.title)
    print(info.source)
    print(info.download_url)
    print(info.save_path)

`VideoClient.download()`

Download parsed videos.

VideoClient.download(video_infos: list[VideoInfo]) -> list[VideoInfo]

VideoClient automatically groups items by source and sends them to the correct underlying client.

Notes:

video_infos should usually be the output of VideoClient.parsefromurl().
Thread counts come from clients_threadings.
Request settings come from requests_overrides.

Example:

video_infos = client.parsefromurl("https://www.acfun.cn/v/ac123456")
client.download(video_infos)

`VideoClient.startparseurlcmdui()`

Start the interactive terminal UI.

VideoClient.startparseurlcmdui() -> None

In this mode, the program repeatedly asks for a video URL, parses it, and downloads the result.

Special inputs:

q: quit
r: restart

This is mainly for command-line use.

`BaseVideoClient`

BaseVideoClient is the base class for all site-specific clients.

Module path:

videodl.modules.sources.BaseVideoClient

Examples of subclasses include clients such as,

videodl.modules.sources.ABCVideoClient
videodl.modules.sources.AcFunVideoClient
videodl.modules.sources.ArteTVVideoClient
videodl.modules.sources.BaiduTiebaVideoClient
videodl.modules.sources.BeaconVideoClient
videodl.modules.sources.BilibiliVideoClient
videodl.modules.sources.C56VideoClient
videodl.modules.sources.CCCVideoClient
videodl.modules.sources.CCTVVideoClient
videodl.modules.sources.CCtalkVideoClient
videodl.modules.sources.DongchediVideoClient
videodl.modules.sources.DouyinVideoClient
videodl.modules.sources.DuxiaoshiVideoClient
videodl.modules.sources.EyepetizerVideoClient
videodl.modules.sources.FoxNewsVideoClient
videodl.modules.sources.GeniusVideoClient
videodl.modules.sources.HaokanVideoClient
videodl.modules.sources.HuyaVideoClient
videodl.modules.sources.IQiyiVideoClient
videodl.modules.sources.KakaoVideoClient
videodl.modules.sources.KanKanNewsVideoClient
videodl.modules.sources.Ku6VideoClient
videodl.modules.sources.KuaishouVideoClient
videodl.modules.sources.KugouMVVideoClient
videodl.modules.sources.LeshiVideoClient
videodl.modules.sources.M1905VideoClient
videodl.modules.sources.MGTVVideoClient
videodl.modules.sources.MeipaiVideoClient
videodl.modules.sources.OasisVideoClient
videodl.modules.sources.Open163VideoClient
videodl.modules.sources.PearVideoClient
videodl.modules.sources.PipigaoxiaoVideoClient
videodl.modules.sources.PipixVideoClient
videodl.modules.sources.PlayerPLVideoClient
videodl.modules.sources.PlusFIFAVideoClient
videodl.modules.sources.RedditVideoClient
videodl.modules.sources.RednoteVideoClient
videodl.modules.sources.SinaVideoClient
videodl.modules.sources.SixRoomVideoClient
videodl.modules.sources.SohuVideoClient
videodl.modules.sources.TBNUKVideoClient
videodl.modules.sources.TedVideoClient
videodl.modules.sources.TencentVideoClient
videodl.modules.sources.UnityVideoClient
videodl.modules.sources.WWEVideoClient
videodl.modules.sources.WeSingVideoClient
videodl.modules.sources.WeiboVideoClient
videodl.modules.sources.WeishiVideoClient
videodl.modules.sources.WittyTVVideoClient
videodl.modules.sources.XiguaVideoClient
videodl.modules.sources.XinpianchangVideoClient
videodl.modules.sources.XuexiCNVideoClient
videodl.modules.sources.YinyuetaiVideoClient
videodl.modules.sources.YoukuVideoClient
videodl.modules.sources.YouTubeVideoClient
videodl.modules.sources.ZhihuVideoClient
videodl.modules.sources.ZuiyouVideoClient
…
videodl.modules.common.AnyFetcherVideoClient
videodl.modules.common.BVVideoClient
videodl.modules.common.BugPkVideoClient
videodl.modules.common.GVVIPVideoClient
videodl.modules.common.GVVideoClient
videodl.modules.common.IIILabVideoClient
videodl.modules.common.IM1907VideoClient
videodl.modules.common.JXM3U8VideoClient
videodl.modules.common.KIT9VideoClient
videodl.modules.common.KedouVideoClient
videodl.modules.common.KuKuToolVideoClient
videodl.modules.common.LongZhuVideoClient
videodl.modules.common.LvlongVideoClient
videodl.modules.common.MiZhiVideoClient
videodl.modules.common.NoLogoVideoClient
videodl.modules.common.ODwonVideoClient
videodl.modules.common.PVVideoClient
videodl.modules.common.QZXDPToolsVideoClient
videodl.modules.common.QingtingVideoClient
videodl.modules.common.QwkunsVideoClient
videodl.modules.common.RayVideoClient
videodl.modules.common.SENJiexiVideoClient
videodl.modules.common.SnapAnyVideoClient
videodl.modules.common.SnapWCVideoClient
videodl.modules.common.SpapiVideoClient
videodl.modules.common.VgetVideoClient
videodl.modules.common.VideoFKVideoClient
videodl.modules.common.WoofVideoClient
videodl.modules.common.XCVTSVideoClient
videodl.modules.common.XMFlvVideoClient
videodl.modules.common.XZDXVideoClient
videodl.modules.common.XiaolvfangVideoClient
videodl.modules.common.XiazaitoolVideoClient
videodl.modules.common.ZanqianbaVideoClient
…

In most cases, external users do not create BaseVideoClient directly. Instead, they either:

use VideoClient, or
use a concrete subclass built on top of BaseVideoClient.

Constructor:

BaseVideoClient(
    auto_set_proxies: bool = False,
    random_update_ua: bool = False,
    enable_parse_curl_cffi: bool = False,
    enable_search_curl_cffi: bool = False,
    enable_download_curl_cffi: bool = False,
    max_retries: int = 5,
    maintain_session: bool = False,
    logger_handle = None,
    disable_print: bool = False,
    work_dir: str = "videodl_outputs",
    freeproxy_settings: dict | None = None,
    default_search_cookies: dict | None = None,
    default_download_cookies: dict | None = None,
    default_parse_cookies: dict | None = None,
)

Arguments:

auto_set_proxies

Automatically fetch and apply proxies for requests. Use this when a source frequently blocks direct requests.
random_update_ua

Randomly refresh the User-Agent when a new session is created. This can help reduce repeated identical requests.
enable_parse_curl_cffi

Use curl_cffi sessions instead of normal requests sessions for parsing. This option is useful for some sites with stricter request checks.
enable_search_curl_cffi

Use curl_cffi sessions instead of normal requests sessions for searching. This option is useful for some sites with stricter request checks.
enable_download_curl_cffi

Use curl_cffi sessions instead of normal requests sessions for downloading. This option is useful for some sites with stricter request checks.
max_retries

Maximum number of retries for HTTP requests.
maintain_session

Whether to reuse the same HTTP session across requests.
- False: recreate the session more often.
- True: keep cookies and session state between requests.
logger_handle

Optional logger instance. If not provided, a default logger is created.
disable_print

Whether to suppress console output.
work_dir

Root directory for outputs.
freeproxy_settings

Optional settings for the proxy client used when auto_set_proxies=True.
default_search_cookies

Default cookies used for search. This is helpful for sites that require login cookies or other session information.
default_download_cookies

Default cookies used for download. This is helpful for sites that require login cookies or other session information.
default_parse_cookies

Default cookies used for parse. This is helpful for sites that require login cookies or other session information.

`BaseVideoClient.parsefromurl()`

Parse a URL and return VideoInfo objects.

BaseVideoClient.parsefromurl(url: str, request_overrides: dict | None = None) -> list[VideoInfo]

This method is defined by subclasses. BaseVideoClient itself only provides the interface.

request_overrides usually contains request-related fields such as:

headers
cookies
proxies

Each returned VideoInfo should normally include at least:

source
download_url
save_path

A typical subclass may also fill fields such as:

title
identifier
cover_url
raw_data
err_msg

Example:

video_infos = some_client.parsefromurl(
    "https://example.com/video/123",
    request_overrides={
        "headers": {"User-Agent": "Mozilla/5.0"},
        "cookies": {"sessionid": "example"},
    },
)

`BaseVideoClient.download()`

Download one or more videos.

BaseVideoClient.download(
    video_infos: list[VideoInfo],
    num_threadings: int = 5,
    request_overrides: dict | None = None,
) -> list[VideoInfo]

This method handles concurrency and chooses the actual download strategy automatically.

Depending on the data in each VideoInfo, the downloader may use:

normal HTTP download,
ffmpeg,
N_m3u8DL-RE,
aria2c,
separate video/audio download followed by merge.

Returns:

a list of successfully downloaded VideoInfo objects.

Example:

downloaded = some_client.download(video_infos, num_threadings=3)

for item in downloaded:
    print(item.save_path)

`BaseVideoClient.belongto()`

Check whether a URL belongs to a given source.

BaseVideoClient.belongto(url: str, valid_domains: list[str] | set[str] | None = None) -> bool

This is mainly a helper for client implementations, but it can also be useful when building custom routing logic.

Example:

BaseVideoClient.belongto(
    "https://www.acfun.cn/v/ac123456",
    valid_domains={"acfun.cn"},
)
# True

Request helpers for subclass implementations

BaseVideoClient also provides retry-enabled request helpers:

get(url, **kwargs)
post(url, **kwargs)

These methods are mainly intended for subclass authors, not for normal end users.

`VideoInfo`

VideoInfo is the core data object returned by parsing methods and consumed by download methods.

It behaves like both:

an object, for example info.title,
and a dictionary, for example info["title"].

Common fields:

source: client name, such as "AcFunVideoClient"
title: video title
cover_url: cover image URL if available
raw_data: original parsed data
err_msg: error message if parsing failed
identifier: unique ID for the video
download_url: main video download URL or local intermediate file
save_path: output file path
ext: output file extension
default_download_headers: optional per-item headers
default_download_cookies: optional per-item cookies
audio_download_url
audio_save_path
audio_ext
default_audio_download_headers
default_audio_download_cookies
download_with_ffmpeg
enable_nm3u8dlre
download_with_aria2c
ffmpeg_settings
nm3u8dlre_settings
aria2c_settings

Useful properties:

with_valid_download_url:

Returns True when the main download URL is valid.
with_valid_audio_download_url

Returns True when the audio download URL is valid.

Example:

{
    "source": "AcFunVideoClient",
    "title": "Example Video",
    "download_url": "https://example.com/video.m3u8",
    "save_path": "videodl_outputs/AcFunVideoClient/Example Video.mp4",
    "ext": "mp4",
    "identifier": "ac123456"
}

Videodl APIs

VideoClient

VideoClient.parsefromurl()

VideoClient.download()

VideoClient.startparseurlcmdui()

BaseVideoClient

BaseVideoClient.parsefromurl()

BaseVideoClient.download()

BaseVideoClient.belongto()

Request helpers for subclass implementations

VideoInfo

`VideoClient`

`VideoClient.parsefromurl()`

`VideoClient.download()`

`VideoClient.startparseurlcmdui()`

`BaseVideoClient`

`BaseVideoClient.parsefromurl()`

`BaseVideoClient.download()`

`BaseVideoClient.belongto()`

`VideoInfo`