VideoDL Documentation

The parsefromurl() method returns a list of VideoInfo objects. These objects behave like both a dataclass and a dictionary, allowing you to access properties via dot notation or key access.

Common Fields

• source: The client that produced the result.
• title: The video title.
• download_url: The resolved media URL.
• save_path: The output file path.
• ext: The file extension.
• err_msg: Any parsing error message.
• download_with_ffmpeg: Boolean to indicate if ffmpeg should be used.
• download_with_aria2c: Boolean to indicate if aria2c should be used.
• enable_nm3u8dlre: Boolean to indicate if N_m3u8DL-RE should be used.

Modifying Download Behavior

You can modify the VideoInfo objects before calling .download() to force specific download methods.

from videodl import videodl

video_client = videodl.VideoClient()
video_infos = video_client.parsefromurl("URL")

for info in video_infos:
    # Access via dot notation or dict key
    print(info.title)
    print(info['title'])
    
    # Modify download settings
    info["download_with_aria2c"] = True
    info["enable_nm3u8dlre"] = True
    info["download_with_ffmpeg"] = True

video_client.download(video_infos)

Integrate videodl into your Python applications using the VideoClient class. The client can choose suitable parsers, parse URLs into VideoInfo objects, and download the resulting media.

Basic Workflow

1. Initialize: Create a videodl.VideoClient() instance.
2. Parse: Call .parsefromurl(url) to get a list of VideoInfo objects.
3. Download: Pass the list of VideoInfo objects to .download(video_infos).

Configuration via Constructor

• allowed_video_sources: A list of strings specifying which clients to use.
• apply_common_video_clients_only: Boolean to restrict parsing to generic clients.
• init_video_clients_cfg: A dictionary for client-specific settings like work_dir or default_parse_cookies.
• requests_overrides: A dictionary to provide headers or proxies for specific clients.
• clients_threadings: A dictionary to set the number of threads per client.

Many video downloaders in videodl require external CLI tools for decryption, stream parsing, and accelerated downloading. For full functionality, it is highly recommended to install the following tools and ensure they are available in your system PATH.

FFmpeg

Required for all HLS (HTTP Live Streaming) streams. Verify installation:

ffmpeg -version

N_m3u8DL-RE

Highly recommended for performance and compatibility. Specialized for m3u8 streams, it handles encryption, anti-leech headers, and parallel segment downloading. Without it, many clients (e.g., CCTVVideoClient, FoxNewsVideoClient, TencentVideoClient, RedditVideoClient, IQiyiVideoClient, etc.) may fail to parse or download. Verify installation:

N_m3u8DL-RE --version

Bento4

Required for certain encrypted media workflows. Provides utilities like mp4decrypt used by N_m3u8DL-RE for clients like TBNUKVideoClient and PlayerPLVideoClient. Verify installation:

mp4decrypt --version

Node.js

Required for specific JavaScript-based parsing. Only necessary if using YouTubeVideoClient, CCTVVideoClient, or TencentVideoClient. Verify installation:

node -v
npm -v

aria2c

Optional for download acceleration. Used to accelerate downloads (e.g., MP4 files) and enable resuming interrupted downloads. Verify installation:

aria2c --version

When instantiating a client (or a subclass of BaseVideoClient), you can pass several arguments to control request behavior, security, and output:

• auto_set_proxies (bool): Automatically fetch and apply proxies. Useful for sites that block direct requests.
• random_update_ua (bool): Randomly refresh the User-Agent for new sessions to reduce fingerprinting.
• enable_parse_curl_cffi, enable_search_curl_cffi, enable_download_curl_cffi (bool): Use curl_cffi instead of requests for specific operations. Use this for sites with strict request checks.
• max_retries (int): Maximum number of HTTP request retries.
• maintain_session (bool): If True, keeps cookies and session state between requests.
• work_dir (str): The root directory where outputs will be saved (default: "videodl_outputs").
• freeproxy_settings (dict): Settings for the proxy client when auto_set_proxies=True.
• default_search_cookies, default_download_cookies, default_parse_cookies (dict): Default cookies for search, download, or parsing operations (useful for authenticated sessions).