[Advanced] Custom yt‐dlp options

⚠️ Warning ⚠️

Custom yt-dlp options are very powerful but can easily break the underlying mechanisms used by Pinchflat to keep track of your media. Heads up before you use these:

• I will not provide support for building, using, or troubleshooting custom yt-dlp options except in extremely limited cases
• Bug reports will likely be closed if they can only be reproduced when using custom yt-dlp options
• All guarantees around Pinchflat's ability to manage your media (or generally function as expected) are removed when using custom yt-dlp options
• Future versions may change the yt-dlp arguments Pinchflat uses internally. No attempt at backward-compatibility with custom yt-dlp options will be made
• Custom options only apply to media downloading and cannot be applied to any other internal Pinchflat behaviour (like indexing)

In other words, use at your own risk and don't be surprised if they cause the app to not work as expected. Support will not be given except in extremely limited cases.

Usage

First, read the yt-dlp documentation on configuration. Optionally consider reading the documentation on modifying metadata since that's probably the most common use case for custom options.

Location

Inside your Pinchflat config directory, there will be a /extras/yt-dlp-configs directory. All yt-dlp config files are placed in this directory.

Base config

By default you'll find a file called base-config.txt. This is the "root" config file whose options will be applied to every download operation

Scoped configs

You can optionally apply a config to all downloads belonging to a given Media Profile, Source, or Media Item which allows you to customize behaviour very granularly.

Scoped config files must be created manually and must follow a specific naming scheme:

• Media Profile: media-profile-{{media_profile_id}}-config.txt
• Source: source-{{source_id}}-config.txt
• Media Item: media-item-{{media_item_id}}-config.txt

So if you wanted to create a custom config for the Source with ID 23, your filepath would ultimately look like <config directory>/extras/yt-dlp-configs/source-23-config.txt

Config Precedence Rules

You can mix-and-match scoped configs as much as you like. For example, you can have a custom config for only one Source of a Media Profile and other Sources won't be impacted. You can also use difference scoped configs for a Media Profile and its Sources, but there is a precedence order to how config files are stacked (ordered from most to least important): Media Item > Source > Media Profile > base config.

Options from multiple config files will be combined unless there are duplicate options in which case the config file with the highest precedence is used for that option. eg: if there's a duplicate option in the base config, Media Profile config, and Source Config, the option in the Source's config will be used. See the yt-dlp documentation on --config-locations for more.