Pinchflat-ngx

Editing "StezStix Fix?"

General Options

Editing Mode

Source URL

URL of a channel, playlist, or single video (required). Single video sources are indexed once and fast indexing is disabled automatically

Source Metadata

Name and description are refreshed from source metadata unless you lock the individual field. Locked fields can still be edited and saved here; the lock only affects automated refreshes.

Source Name

The name shown throughout Pinchflat-ngx. It will be refreshed from source metadata unless locked.

Lock Source Name

Keep the current name when automated metadata refreshes run.

Description

The source description shown in Pinchflat-ngx. It will be refreshed from source metadata unless locked.

Lock Description

Keep the current description when automated metadata refreshes run.

Media Profile

Sets your preferences for what media to look for and how to store it

Indexing Options

Index Frequency

Indexing is the process of checking for media to download. For best results, set this to the longest delay you can tolerate for this source

Use Fast Indexing (pro)

Not recommended for playlists. Single video sources always disable this option. Overrides 'Index Frequency'. See below for more details (seriously, there's a TL;DR that's worth reading)

Indexing Cutoff Date

Stop indexing a channel once it reaches videos uploaded before this date — big time-saver for channels with a large back catalog. Set it a few days before the Download Cutoff Date for safety. Only applies to YouTube channels; ignored for playlists. A few videos from before this date may still be indexed (but not downloaded) — especially on channels with few videos or when Fast Indexing is enabled, since those checks look at the most recent videos regardless of date. Leave blank to index everything

The Indexing Cutoff Date doesn't apply to playlists — they aren't ordered by upload date, so indexing can't safely stop early.

The Indexing Cutoff Date is after the Download Cutoff Date — media between the two dates would never be indexed, so it could never be downloaded. Set it on or before the Download Cutoff Date.

Downloading Options

Download Media

Unchecking still indexes media but it won't be downloaded until you enable this option

Download Public and Unlisted Media

Controls media that yt-dlp reports as public or unlisted

Download Members-only Media

Includes subscriber-only, premium-only, and media that requires authentication

Cookie Behaviour

Uses your YouTube cookies for this source (if configured). 'When Needed' tries to minimize cookie usage except for certain indexing and downloading tasks. See docs

Primary YouTube Player Client

Overrides yt-dlp's default YouTube player-client selection for this source. Default is recommended unless you need a specific client.

Client Fallback Chain

If the primary client encounters an HTTP 403 or bot check, Pinchflat will sequentially try these fallback clients in order (up to 4 total clients).

No fallback clients configured. Only the primary client (or yt-dlp default) will be used.

Select a primary YouTube Player Client above to enable fallback chains.

Maximum of 4 total clients reached (1 primary + 3 fallbacks).

Members-only media may fail without cookies. Configure a cookies.txt file and select a cookie behaviour if you want Pinchflat-ngx to access it; this setting will not enable cookies automatically.

Web Creator requires account cookies. Select All Operations to use this client reliably.

One or more configured player clients (Android, iOS, TV Simply) do not support account cookies. Set Cookie Behaviour to Disabled before saving.

Shared `cookies.txt` file

Ready

Cookie file is configured and ready to use.

/config/extras/cookies.txt

Minimum Duration (seconds)

Minimum duration of the media to be downloaded. Can be blank

Maximum Duration (seconds)

Maximum duration of the media to be downloaded. Can be blank

Download Cutoff Date

Cutoff preset

Automatically download media published on or after this date. Scheduled cleanup also deletes unprotected downloaded media from before this date, including manual downloads, even within their retention period. Leave blank for no cutoff. Prevent Automatic Deletion on a media item's Edit page overrides both cutoff and retention cleanup.

Retention Period (days)

Days from download until media is eligible for scheduled deletion. Leave blank or set 0 to disable age-based deletion. Cutoff cleanup can still delete media sooner. Prevent Automatic Deletion overrides both rules

Advanced Options

Tread carefully

Title Filter Regex

A PCRE-compatible regex. Only media with titles that match this regex will be downloaded. See here for syntax

Source folder

Relative folder under the media root. Pinchflat-ngx applies this before the output template, so keep the template focused on filenames or subfolders inside this directory.

Output path template override

Must end with .{{ ext }}. Same rules as Media Profile output path templates. Click here to load your media profile's output template

Shorts output path template override (optional)

Used for this source's YouTube Shorts. Leave blank to use the media profile's Shorts template, or the primary output path template if neither is set. Must end with .{{ ext }}. Saving leaves existing files in place; later re-downloads and quality upgrades use the new path.

How Shorts are identified

Channel tabs identify Shorts directly. Mixed playlists and fast indexing use the URL and existing duration/aspect-ratio detection, which can misclassify short vertical videos.

Need custom yt-dlp arguments for this source? After saving, add them to extras/yt-dlp-configs/source-123-config.txt using the saved source ID. Pinchflat already loads per-source, per-profile, per-media-item, and base yt-dlp config files during downloads.

Pinchflat saves downloads to media root + source folder + output template.

Use Source folder for the main folder, then keep your template focused on file naming or subfolders inside it.

If both the source folder and the template point to the same folder name, it will be duplicated. Example: source folder Kids plus template Kids/{{ title }}.{{ ext }} becomes Kids/Kids/....

Good examples:

Kids/Bluey
Podcasts/Tech
TV/Documentaries

Indexing is the act of scanning a channel or playlist (aka: source) for new media.

Normal indexing uses yt-dlp to scan the entire source on your specified frequency, but it's very slow for large sources. This is the most accurate way to find uploaded media with the tradeoff being that pairing a large source that's indexed frequently will result in you spending most of your time indexing. Only so many indexing operations can be running at the same time so this can impact your other source's ability to index.

Fast indexing takes a different approach. It still does an initial scan the slow way but after that it uses a secondary mechanism (either RSS or YouTube's API) to frequently check for new videos. This has the potential to be hundreds of times faster, but it can miss videos if the uploader un-privates an old video or uploads dozens of videos in the space of a few minutes.

RSS is used by default but you should enable the YouTube API if you want the best version of fast indexing. This isn't needed for most users but it provides the fastest and most reliable media updates. Here is some documentation on how to get your API key which you can add in the settings page.

To make up for this limitation, a normal index is still run monthly to catch any videos that were missed by fast indexing. Fast indexing overrides the normal index frequency.

TL;DR

In general:

Uses RSS by default which is fine for most users
Create a YouTube API key and add it in your settings for the fastest possible media updates

Fast indexing is great if any of these apply:

The source is large channel and uploads frequently
You want to download a source's new content as soon as possible

Consider not using fast indexing if any of these apply:

The source is a playlist
The source has under 200 videos
The source rarely uploads
You don't mind if it takes longer for new content to be picked up

Custom Source Poster

Use a local JPEG, PNG, or WebP file, or provide a public HTTP(S) URL. This poster takes precedence over fetched artwork until you remove it.

No custom poster is set; the fetched poster is being used.

We can't find the internet

Something went wrong!