How to Use the youtube-dl Match-Filter System for Precise Video Selection

The youtube-dl match-filter system allows you to filter individual videos after extraction by evaluating metadata conditions such as duration, view count, or uploader name against user-defined expressions.

The match-filter system in youtube-dl provides granular control over which videos are downloaded by evaluating each video's info_dict against custom criteria. Implemented across three core modules in the ytdl-org/youtube-dl repository, this system parses filter expressions at startup and applies them during the download pipeline to skip unwanted content without external scripting.

How the Match-Filter System Works in youtube-dl

The match-filter system operates through a three-stage pipeline that bridges command-line input to runtime video evaluation.

Command-Line Option Registration

The --match-filter argument is defined in youtube_dl/options.py (lines 308-321), where it accepts a raw filter string and stores it in the parameters dictionary. This registration captures the user's filtering intent before any video extraction begins.

Filter Parsing and Compilation

In youtube_dl/utils.py, the match_filter_func (lines 4436-4450) transforms the raw string into an executable closure. This function leverages match_str and _match_one to parse the expression into atomic operations:

• AND semantics are enforced by splitting on the & operator.
• Presence checks validate that a key exists (description) or is absent (!description).
• Numeric comparisons handle operators >, <, >=, <=, !=, and =.
• String literals support single or double quotes, with an optional ? suffix to treat missing values as acceptable.

Runtime Application

During execution, youtube_dl/YoutubeDL.py (lines 826-831) invokes the stored filter function for each video's info_dict. A return value of None permits the download to proceed, while any non-None string (the rejection reason) skips the video and logs the explanation.

Match-Filter Syntax and Operators

The match-filter system supports a specific grammar for constructing filter expressions:

• Key presence — description requires the field to exist.
• Key absence — !description requires the field to be missing.
• Numeric comparison — view_count > 1000, filesize <= 5MiB, duration >= 60.
• String equality — uploader = "Mike Smith", title != "Demo Video".
• Unknown value tolerance — append ? to the operator (dislike_count <? 50) to pass when the field is missing.
• Multiple conditions — join with & for logical AND. No OR operator is provided; chain separate --match-filter invocations if needed.

Practical Examples: Using Match-Filters in youtube-dl

Filter by Duration and Uploader

To download only videos longer than 30 seconds from a specific creator:

youtube-dl --match-filter "duration > 30 & uploader = \"Mike Smith\"" \
           "https://www.youtube.com/playlist?list=PL12345"

Handle Missing Metadata Gracefully

To require a description field while ignoring missing dislike counts:

youtube-dl --match-filter "description & dislike_count <? 50" \
           https://www.youtube.com/watch?v=abc123

The ? suffix after < ensures the filter passes if dislike_count is not provided by the extractor.

Programmatic Filter Usage in Python

For dynamic filter construction, use the Python API directly:

from youtube_dl import YoutubeDL
from youtube_dl.utils import match_filter_func

# Build a filter for videos larger than 5MiB with at least 1,000 views

my_filter = match_filter_func('filesize > 5MiB & view_count >= 1000')

ydl_opts = {'match_filter': my_filter}
with YoutubeDL(ydl_opts) as ydl:
    ydl.download(['https://www.youtube.com/watch?v=xyz789'])

This approach allows runtime generation of filter strings based on external configuration.

Summary

• The match-filter system evaluates video metadata after extraction but before downloading, living in youtube_dl/options.py, youtube_dl/utils.py, and youtube_dl/YoutubeDL.py.
• Filters support numeric comparisons, string matching, presence checks, and logical AND operations via the & operator.
• The ? suffix on operators allows filters to pass when metadata fields are missing, preventing extraction failures.
• Both command-line --match-filter arguments and programmatic match_filter_func calls enable flexible video selection without external scripting.

Frequently Asked Questions

What is the match-filter system in youtube-dl?

The match-filter system is a post-extraction filtering mechanism that evaluates each video's info_dict against user-defined criteria before downloading. According to the ytdl-org/youtube-dl source code, it is implemented across youtube_dl/options.py, youtube_dl/utils.py, and youtube_dl/YoutubeDL.py to parse, compile, and execute filter expressions at runtime.

How do I filter videos by file size or duration?

Use numeric comparison operators within your filter string, such as duration > 60 for videos longer than one minute or filesize <= 5MiB for files under five mebibytes. These expressions are parsed by match_filter_func in youtube_dl/utils.py and evaluated against the numeric values in each video's metadata dictionary.

Can I combine multiple conditions in a single match-filter?

Yes, join conditions with the & operator to enforce logical AND semantics, such as view_count > 1000 & uploader = "Channel Name". The parsing logic in youtube_dl/utils.py splits the expression on & and requires all parts to pass; no OR operator is provided, though you can chain multiple --match-filter invocations to achieve alternative logic.

How does the match-filter system handle missing metadata fields?

By default, comparisons against missing fields fail and reject the video, but appending ? to the operator makes the condition pass when the field is absent, such as dislike_count <? 50. This "unknown-value" tolerance is handled by _match_one in youtube_dl/utils.py, allowing filters to gracefully handle extractors that do not provide specific metadata fields.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}