ytdl-sub.readthedocs.io

ytdl-sub is a tool whose official documentation is published at ytdl-sub.readthedocs.io, the "ytdl-sub User Guide." The site is documentation only: it explains how to install, configure, and run ytdl-sub. It is not a downloader, streaming service, or place to obtain media itself. Use it when you want to understand what ytdl-sub does and how to set it up; look elsewhere if you just want to download a single video without configuration.

What the User Guide Covers

The guide is organized into sections that map to the work of running ytdl-sub:

The guide also links to a Development and Contributing section for people working on the tool itself.

How the Pieces Fit Together

The section names reveal the core model. A subscription file defines what you want to track. Presets decide how that content is organized and named. The configuration file ties presets and subscriptions together, and plugins and scripting extend behavior beyond the defaults.

A practical example: someone who wants a TV-show-style library does not need to design a naming scheme from scratch. They start from a TV Show Preset, point a subscription file at the source, and adjust only what differs from the preset. The Prebuilt Preset Reference is where to confirm what a given preset actually does before relying on it.

Deciding Whether It Fits Your Task

Choose ytdl-sub when you want repeatable, organized handling of subscribed content and are willing to write or adapt a configuration. Choose a simpler single-video downloader when you have a one-off task and no interest in presets or subscription files.

Two cautions follow from the documentation's structure rather than from any claim on the site. First, the presence of a "Subscription File" section does not establish pricing or access terms for any source; the guide does not state them, so check the relevant service yourself. Second, because the guide maintains Deprecation Notices, configurations copied from older examples may need updating—check that section when an existing setup stops behaving as expected.

Where to Start

Begin with What is ytdl-sub? and Getting Started, then move to Install by Platform for your system. Once installed, pick the preset family matching your media type and consult the Prebuilt Preset Reference before customizing. Keep Debugging and FAQ open for the first run, since configuration errors are the most likely early obstacle.

To get started with ytdl-sub, work through the documentation in this order: Install by Platform → Getting Started → Configuration File → Subscription File → Presets. The install step comes first because everything later depends on a working binary or container. The guide's own navigation lists these sections in that sequence, so following it avoids configuring subscriptions before the tool is actually running.

What the guide covers before you install

The ytdl-sub User Guide is organized into these top-level sections:

• What is ytdl-sub? — the overview page
• Guides — Install by Platform, Getting Started, Development and Contributing
• Prebuilt Presets — TV Show, Music, Music Video, Media Quality, and Helper presets
• Usage Reference — Configuration File, Presets, Subscription File, Plugins, Scripting, Prebuilt Preset Reference, Debugging, FAQ, Deprecation Notices

For a first install, you only need the first two groups. Presets and scripting become relevant once a basic run works.

Step 1: Install for your platform

Open Guides → Install by Platform. The documentation splits installation by platform rather than offering one universal method, so pick the page matching your environment (for example, a container-based setup versus a direct install on your OS). Each page is the authoritative source for its own commands — use it rather than adapting instructions from a different platform.

Expected result: the ytdl-sub command runs and responds (for example, printing its help output) without errors.

Step 2: Complete the Getting Started walkthrough

Guides → Getting Started is written for first-time users and is the intended next stop after installation. Treat it as the checklist that takes you from "installed" to "first successful download." Complete it before touching presets — it establishes the minimum working setup that later configuration builds on.

Step 3: Create your configuration file

The Usage Reference → Configuration File page explains the main config file. This is where global behavior lives. Read it after Getting Started so you understand which settings are global versus per-subscription.

Step 4: Define subscriptions

The Subscription File page covers how you tell ytdl-sub what to download and where to put it. This is the step that turns a working install into an actual library. Keep your first subscription small — one channel or playlist — so a failure is easy to diagnose.

Step 5: Apply presets

Only after a basic subscription works should you move to Prebuilt Presets. The guide groups them by media type:

Start with the preset matching your content type, then layer quality and helper presets as needed.

When something goes wrong

Use Usage Reference → Debugging and the FAQ before changing configuration blindly. The Deprecation Notices page matters if you are following an older tutorial — options shown there may no longer behave as described.

A practical order of operations

1. Install via your platform's page and confirm the command runs.
2. Finish Getting Started end to end.
3. Write a minimal configuration file.
4. Add one small subscription and run it.
5. Add presets for your media type.
6. Scale up subscriptions only after step 4 succeeds.

Skipping to presets before step 4 is the most common way to end up with a config that fails without a clear cause, since preset behavior depends on a correct base configuration and subscription structure.

ytdl-sub separates what to download from how to store it. A subscription file lists the sources you want (channels, playlists, or individual URLs), and a preset supplies the configuration that decides where files land, how they are named, and what metadata is written. You point a subscription at one or more presets, and ytdl-sub applies that configuration to every entry in the file. The ytdl-sub User Guide documents both pieces under Configuration File, Presets, and Subscription File, with ready-made presets collected in the Prebuilt Preset Reference.

Subscription files: the "what"

A subscription file is a YAML document whose top-level keys are subscription names. Each entry describes a source and the presets to apply. The guide's Subscription File reference covers the available fields; the essential shape is a source URL plus a preset reference:

__preset__:
  overrides:
    tv_show_directory: "/media/TV Shows"

my_show:
  preset: "TV Show"
  source:
    - "https://www.youtube.com/@SomeChannel"

Key behaviors to know:

• One file, many subscriptions. Each top-level key is independent, so a single file can mix a TV channel, a music playlist, and a one-off video.
• Sources are lists. Listing multiple URLs under one subscription treats them as the same logical show or album, which matters for episode and track numbering.
• __preset__ is shared configuration. Anything placed here applies to every subscription in the file unless a subscription overrides it — useful for setting a common output directory once.

Presets: the "how"

A preset is a named bundle of settings: output paths, file naming, metadata/NFO generation, quality selection, and download behavior. Presets can build on other presets, so a specific one like a TV show preset inherits from a general media-quality preset and only changes what it needs.

The guide organizes prebuilt presets into four families:

Helper Presets are smaller building blocks (for example, naming or metadata fragments) that the larger presets compose together. You normally use the family presets directly and only reach for helpers when customizing.

How the two combine

The merge order is the mechanism worth understanding: prebuilt preset → your preset overrides → subscription-level settings → __preset__ defaults. Later layers win. That means you can adopt a prebuilt TV preset wholesale, then change only the output directory, without copying the entire preset definition.

A practical pattern is to define a custom preset that inherits from a prebuilt one:

__preset__:
  preset:
    - "TV Show"
    - "1080p"

my_show:
  overrides:
    tv_show_directory: "/media/TV Shows/My Show"
  source:
    - "https://www.youtube.com/@SomeChannel"

Here the subscription inherits the TV Show structure and the 1080p quality preset, and overrides only the destination folder.

Choosing an approach

• Use prebuilt presets as-is if your library matches a standard shape (TV seasons, artist/album music). This is the fastest path and the one the Getting Started guide walks through.
• Override individual fields when only paths or quality differ — no need to write a full preset.
• Write a custom preset when you need naming or metadata rules the prebuilt families don't cover; inherit from a prebuilt preset so you keep its structure and change only the parts you care about.

Common sticking points

• Preset names are exact. A typo in a preset reference fails silently or errors at run time; check names against the Prebuilt Preset Reference.
• Overrides belong at the right level. A setting under __preset__ affects every subscription in the file; put per-show settings under that subscription's overrides.
• Numbering depends on grouping. Splitting one channel across multiple subscriptions can break episode ordering — keep a single logical show in one subscription.
• Verify before a full run. The guide's Debugging section covers inspecting the resolved configuration, which is the quickest way to confirm your preset merge produced the paths and names you expected.

The ytdl-sub User Guide at ytdl-sub.readthedocs.io organizes its reference material into distinct sections: Configuration File, Presets, Subscription File, Plugins, Scripting, and a separate Prebuilt Preset Reference. Use the Configuration File and Presets pages when you are writing or editing your own config, the Prebuilt Preset Reference when you want to see what presets already exist, and the Plugins and Scripting pages only when built-in options are not enough. The FAQ and Debugging pages are the place to check when something behaves unexpectedly.

What Each Reference Section Covers

The guide's navigation lists the following reference-oriented pages, each aimed at a different task:

The Prebuilt Preset Reference is listed as its own top-level entry, separate from the general Presets page. Treat the Presets page as the explanation of how presets work and the Prebuilt Preset Reference as the catalog of what is available.

How the Guide Is Organized Around Tasks

The documentation is structured by stage of use rather than as a single alphabetical reference:

• Install by Platform and Getting Started come first, for setup.
• Prebuilt Presets groups ready-made presets by media type: TV Show Presets, Music Presets, Music Video Presets, Media Quality Presets, and Helper Presets.
• Usage Reference collects the Configuration File, Presets, Subscription File, Plugins, and Scripting pages.
• Prebuilt Preset Reference, Debugging, FAQ, and Deprecation Notices sit at the end as lookup and troubleshooting material.

So the practical path is: pick a prebuilt preset category that matches your media, then move into the Usage Reference pages to adapt the configuration, and fall back to Debugging or FAQ if the result is not what you expected.

A Practical Way to Use the Reference

1. Start with Getting Started to confirm your install works.
2. Choose the closest preset category (for example, TV Show Presets or Music Presets) and read its page.
3. Open the Prebuilt Preset Reference to confirm the exact preset names available to you.
4. Write or edit your configuration using the Configuration File and Presets pages, and define what to download in the Subscription File page.
5. Only if the built-in options fall short, read Plugins and Scripting.
6. If a run fails or output is wrong, check Debugging and FAQ before changing your setup further.

The guide also offers the documentation in .rst and .pdf formats alongside the HTML pages, which is useful if you want an offline copy of the reference while editing configuration.

Common Sticking Points

• Confusing the two preset pages. The Presets page explains the mechanism; the Prebuilt Preset Reference lists what exists. Check the reference first to avoid inventing preset names.
• Skipping the Subscription File. Configuration and subscription are separate concerns in this guide; a correct config still needs the subscription file to define what gets downloaded.
• Reaching for Plugins and Scripting too early. These are advanced customization pages; most setups are covered by prebuilt presets plus configuration.
• Ignoring Deprecation Notices. Options change over time, and the notices page flags what has been retired, which prevents debugging a setting that no longer applies.

The guide is maintained by Jesse Bannon, and the site footer carries a 2026 copyright notice, so check the Deprecation Notices page if you are following older examples from elsewhere.

The ytdl-sub User Guide has dedicated FAQ and Debugging sections in its navigation, alongside Deprecation Notices and a full Reference area. When ytdl-sub misbehaves, start with Debugging for diagnostic guidance, check FAQ for known behaviors, confirm your configuration against the Configuration File, Presets, and Subscription File reference pages, and read Deprecation Notices if something that used to work has changed. The Development and Contributing section is the place to look for how to report an issue.

The help sections in the guide

The guide's navigation lists these sections relevant to troubleshooting:

The guide is authored by Jesse Bannon and carries a copyright notice through 2026.

A practical order to work through

1. Reproduce and note the symptom. Write down the command you ran, the subscription or config file involved, and the exact output or missing result.
2. Read Debugging. It is the section intended for diagnosing why output differs from expectations.
3. Check FAQ. If the behavior is common, the answer is likely already stated there.
4. Verify your configuration against the reference pages. Compare your config file, presets, and subscription file with the documented fields and preset definitions. A large share of "it does nothing" cases come down to a preset or field that does not mean what the user assumed.
5. Check Deprecation Notices. If a setup worked previously and now does not, a changed or removed option is a likely cause.
6. Report through Development and Contributing. If the guide does not cover your case, that section describes how to engage with the project.

What to include when asking for help

Since the guide does not document a formal issue template, prepare the details a maintainer would need:

• The ytdl-sub version you are running
• Your configuration file and the relevant subscription file, with credentials removed
• The preset(s) in use
• The command executed and its full output
• What you expected versus what happened

Common sticking points

• Assuming a preset does what its name suggests. Presets are documented in the Prebuilt Preset Reference; verify the actual behavior there rather than inferring from the name.
• Editing config without checking the reference. Field names and nesting are defined in the Configuration File section; small mismatches can silently change behavior.
• Missing a deprecation. Older examples circulating online may use options that have since changed; the Deprecation Notices page is the authority.
• Skipping Debugging because the FAQ has no entry. The Debugging section exists precisely for cases the FAQ does not cover.

The guide does not state pricing or access restrictions for the documentation itself; treat the site as the primary source and check it directly for the current version of each section.