Checkpoint: Trace One Download End to End

This checkpoint uses yt-dlp's central ideas as one working model: an input URL is interpreted by an appropriate extractor, translated into a common result, and evaluated against the user's intent and the media evidence the site actually provides. The aim is not to repeat definitions, but to test whether the handoffs make sense together. By following a few representative paths, the reader can identify what each layer contributes, where a decision changes the route, and why two apparently similar URLs can end in different outcomes.

What crosses the boundaries

The simplest end-to-end trace begins with a user who wants a playable local copy, perhaps with a preferred language or a limit on size. That request contains intent, not site knowledge. It does not say which page to request, which API client to use, whether audio and video are separate, or whether the result will be a direct file or a stream described by fragments. yt-dlp's first job is to find the component that can interpret the supplied URL.

The core consults its ordered extractor registry. A matching extractor owns the first interpretation of the URL and the requests needed to gather evidence from the service. This might be a specialized extractor that knows the site's response structure, or a generic path that recognizes a direct file, HTML5 media element, common metadata, feed, manifest, or embedded player. The selection of the extractor is not yet a selection of the media format. It is a decision about who is qualified to read the page.

The boundary can be stated in terms of ownership. The extractor owns site-specific meaning: which identifier belongs to the item, which response contains the available media, how a page's embedded location relates to the outer page, and which fields are safe to interpret. The shared core owns what happens to the extracted message: it resolves deferred URLs, expands collection entries, normalizes video information, applies filters, selects formats, prepares output, and invokes download or post-processing behavior. The two sides cooperate through a result contract rather than through a shared collection of page-specific assumptions.

The common information dictionary is what crosses that boundary. For a video, the extractor contributes an identity and either a direct media URL or candidate formats. It can also contribute descriptions, thumbnails, subtitles, chapters, availability, live status, language, and other context. The shared processor checks the result, fills or derives common fields where appropriate, and organizes the candidate formats for later selection. The dictionary is not merely a bag of metadata; it is the point at which site evidence becomes a form the rest of yt-dlp can reason about.

A format in that dictionary carries the information needed for the next decision. It may identify a direct file, a manifest, a set of fragments, or a stream that contains only video or only audio. It can record dimensions, codecs, size, language, protocol, and whether the representation may be protected or incomplete. These details remain attached to the candidate as it moves forward. The core does not need to know the original page layout to compare them, but it does need the qualifiers to avoid making a choice that cannot be delivered.

A single request can therefore contain several handoffs:

sequenceDiagram participant U as User participant C as Shared core participant R as Extractor registry participant E as Site extractor participant S as Site evidence U->>C: URL and intent C->>R: Check suitability in order R-->>C: First suitable extractor C->>E: Request extraction E->>S: Page, API, or manifest request S-->>E: Site-specific evidence alt Direct video evidence E-->>C: Video result else Deferred or embedded location E-->>C: URL or transparent result C->>E: Resolve another extractor else Collection evidence E-->>C: Playlist or multi-video result C->>E: Resolve entries end C->>C: Normalize common result C->>C: Evaluate format candidates C-->>U: Selection outcome

The sequence deliberately ends at selection rather than at a finished file. That boundary matters.