Frequently Asked Questions

How do I get media into Plex/Jellyfin/Kodi?

There is no explicit media center integration. Instead, Pinchflat can format the filepath and add metadata in a way that is automatically picked up by media center apps. Here's how to do that, including some best practices:

• Ensure Pinchflat's download directory is in a location that's visible to your media center app
• Set up your Media Profile
  • Create a new Media Profile and use the "Media Center" preset. That's it! Or;
  • Ensure your Media Profile is set to save content in an expected location
    • Ideally, save it in a new directory like /shows/
    • Must save media into different "season" folders per-year. These folders must follow the format /Season <number>/. eg: /Season {{ season_from_date }}/
    • Here's a good full output path template: /shows/{{ source_custom_name }}/Season {{ season_from_date }}/{{ season_episode_from_date }} - {{ title }}.{{ ext }}
    • Change the other Media Profile options as you see fit, ensuring you enable everything under "Media Center Options"
• Set up your media center app to look for TV shows in the directory created above. In the example above, you'd configure it to look in the /shows/ directory
  • NOTE: in Plex you likely want to enable Prefer local metadata and Use local assets. This is found in "TV Shows" > Manage Library > Edit > Advanced
• NOTE: I strongly recommend keeping your YouTube content in a separate directory from your normal TV shows. It's good to keep things tidy!

How do I download one-off videos?

This isn't explicitly supported in-app, but there's a very simple workaround! All you have to do is create a new unlisted playlist on YouTube, add the videos you want to that playlist, and add that playlist as a Source in Pinchflat. Don't forget that you can create + add as many unlisted playlists as you'd like if you want to have different download rules for certain videos!

What is indexing/how does it work?

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

There are a few ways to do this. Pinchflat's approach is to build a list of all media belonging to a Source, regardless of any filters or preferences you've applied. It then uses your filters on its internal list of known content to decide what to then download. This has a few benefits, but the biggest one is that changing your filters doesn't mean the Source needs to be indexed again.

How frequently should I be indexing a Source?

It's important to set a smart indexing frequency to ensure all sources can be updated in a timely manner (see below). Being too aggressive with indexing can actually result in you waiting longer for new content than if you had set more patient rules!

There's no hard-and-fast rules here, but you should try to balance channel size vs. upload frequency. Here are some general guidelines:

• Any number of videos and uploads 3+ times a day - use fast indexing (see below)
• 100+ videos and uploads daily or a few times a week - use fast indexing
• 1,000+ videos and uploads a few times a month - use fast indexing
• 100-1,000 videos and uploads a few times a month - index weekly
• 100-1,000 videos and is and uploads rarely or is a dead channel - index monthly
• Under 100 videos is so quick to index that it doesn't matter as much. Just set it based on the general frequency of video uploads (eg: if they upload 2-3 times a month, I'd set it to index weekly)
• If it's a playlist that will rarely change, set it to index monthly

I just added a new Source, why isn't it indexing or downloading?

Pinchflat is configured to only perform a certain number of operations at the same time. This is a necessity since being too aggressive in fetching/downloading content will result in Google rate limiting your IP, causing downloads and indexing to fail. These failures will have a cascading effect, grinding things to a halt. The app is build to gracefully recover from these types of failures but it takes time for Google to ease up on it rate limiting. It's overall very preferable to be more conservative to prevent this situation in the first place.

That said, it's perfectly normal for there to be a substantial delay in downloading if you're adding a bunch of large sources at the same time. Pinchflat uses a few tricks to start downloads as soon as possible but it can still take dozens of hours to do an initial download of a large channel (although subsequent runs can be MUCH faster).

If you want to be sure, check the logs for entries concerning yt-dlp being called. If those are showing up, the app is still chugging along!

My Source isn't indexing on the schedule I set - what gives?

This is expected and can come from a few places.

For the reasons outlined in the question above, it can be due to the app avoiding running too many yt-dlp commands at the same time. If you have many Sources that should index at the same time, it'll stagger them to prevent you from being rate limited.

The other reason is that the next indexing gets scheduled only after the current one completes. For example: if you set your Media Profile to index every 60 minutes and the indexing task takes 30 minutes to complete, it'll actually run every 90 minutes, since that 60 minute interval was only applied after the 30 minute indexing task completed. This is expected because it's the best way to ensure indexing tasks don't overlap and other tasks can run in a timely-ish manner.

For those reasons, it's not recommended to index a large channel frequently. See above for some guidelines on index frequency.

What is Fast Indexing?

Fast Indexing is an option you can set per-source. It's a toggle under the "Index Frequency" field.

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 with frequent indexing will result in you spending most of your time indexing those sources. Only so many indexing operations can run 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 an RSS feed or API calls 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. 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.

RSS is used by default and you can optionally configure an API key if you need Fast Indexing to be as quick and accurate as possible. Most users are fine with just RSS. See the settings page inside Pinchflat for instructions on using the YouTube API.

Fast indexing is not recommended for playlists.

Will Pinchflat delete videos if they're removed from the Source or I change my filters?

Yes and no. There is no logic for deleting files when they're removed from the source or if you update your filters (and this is not planned). However, you can set a Source to automatically delete media after a certain number of days (docs)

I only want certain videos from a Source - how can I only download those?

You have a few options!

• If it's a small number of videos that won't be updated frequently, create a new playlist with those videos and use that as the source
• If the titles always contain certain words, enabled advanced mode in your Source (upper right) and use a "Title Filter Regex". This will only download videos whose titles match that regular expression.
• If you only want to download after a certain date, set the Source's "Download Cutoff Date" to a YYYY-MM-DD date. Only videos uploaded after that date will be downloaded

How can I test that filtering works as expected?

You may want to test your "Title Filter Regex", "Download Cutoff Date", handling of shorts vs. livestreams, etc., before you actually start downloading the content.

The best way to do this is to disable "Download Media" in your Source. The Source will still be indexed, but you can check the "Pending Media" tab when viewing a Source to ensure that only the media you expect is set to be downloaded. NOTE: this page does not update live and you must reload the page to see the latest.

Once you're confident everything is working as expected, update the Source to download media and it'll get to it!

Can I import my existing library into Pinchflat?

This is not currently possible and is not a planned feature.