Making Remote Media Durable
Once yt-dlp has selected a representation, the problem changes from “which media does the user want?” to “how can this representation survive contact with networks, interruptions, fragmented streams, and local media tools?” This chapter follows that operational lifecycle. It distinguishes request-handler negotiation from media-protocol handling, then traces how temporary state, retries, fragment assembly, and post-processing turn remote evidence into a durable artifact—or reveal exactly why they cannot.
Two kinds of negotiation
A selected format contains at least two different instructions. One describes the media: perhaps a direct HTTP file, an HLS playlist, a DASH manifest with fragments, or several streams that must later be merged. The other describes the request environment: which transport can reach the URL, which proxy and TLS behavior apply, which cookies or headers are in scope, and whether a browser-like request is needed. yt-dlp keeps these questions separate because solving one does not solve the other.
The networking layer represents a request in a common form and sends it through a RequestDirector. The director ranks available request handlers according to registered preferences, asks whether each handler supports the URL scheme, proxy arrangement, extensions, and other requested capabilities, and then tries a compatible handler. The built-in choices include the standard urllib and requests paths, a websocket handler for websocket-based transfers, and optional curl_cffi support for cases where browser-like network behavior matters. They share request and response abstractions even though their underlying libraries differ.
This is capability negotiation, not merely a choice of popular HTTP library. A handler can reject a request because it does not support its URL scheme, proxy type, extension, or impersonation target. A handler can also fail while sending it. The director keeps those cases distinct: unsupported means that another handler may be appropriate, while an unexpected handler failure is an error to be reported and, where the defined policy permits, followed by another attempt. The upper extraction and download layers can consequently reason about common categories such as HTTP errors, transport failures, TLS failures, proxy failures, and incomplete reads without knowing every library's exception vocabulary.
The request environment travels with the selected media context. Headers can carry the authentication or referer information the source requires. Cookies are attached through a cookie jar with scope rules rather than treated as a universal string. A proxy may apply to one scheme and not another. TLS verification is a deliberate setting, and browser impersonation changes the request target and often the headers that accompany it. These details belong to the network boundary because they govern whether the URL can be requested at all.
Media-protocol negotiation begins only after that request context is understood. yt-dlp maps normalized protocol information to a suitable file downloader. A direct HTTP representation can use block-oriented HTTP handling. An HLS representation can use the native HLS downloader or delegate to a compatible external path. A DASH representation can use a fragment-aware downloader, while ffmpeg may be selected when it can download or merge the requested inputs in one operation. The downloader is chosen from the representation's protocol and context, not from the name of the request library.
This distinction is useful in a failure report. If a direct URL works through one request handler but not another, the media representation may be sound and the transport capability may be the problem. If the request succeeds but an HLS playlist contains a feature the native downloader cannot handle, the network boundary has done its job; the media-protocol path needs delegation or a different choice. If two streams are individually retrievable but cannot be merged, neither request negotiation nor extraction necessarily failed. The incompatibility belongs to artifact production.
The separation also allows one representation to move between delivery strategies.