Frequently Asked Questions

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

Important

Plex cannot read metadata from MKV files. Pinchflat saves files as MP4 by default so leave those settings alone

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
• Create a new Media Profile with the "Media Center" preset
  • NOTE: you can tweak the parent directory specified in Output path template if needed, but it's critical that you don't change anything else about the Output path template
• 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 create a new library just for YouTube (Settings > Manage > Libraries > Add Library). You'll want to enable Prefer local metadata and Use local assets in the "Advanced" library settings section. This may not be ideal for all users in which case you could look into an NFO or YouTube agent for Plex. Plex is also expecting to add NFO support sometime in early 2025 which should remove the need for this setting
• 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.

If the Source is a channel (rather than a playlist), it's only fully indexed once. After that point indexing only looks for new media and changes to recently indexed media. Keep in mind that forcing a source to be indexed from the UI will fully index a channel top-to-bottom.

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. 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 base it on how often the channel uploads and whether you care about getting the latest content immediately. Here are some rough guidelines:

• Is it a channel that uploads multiple times a day? Set it to either 1 hour or 3 hours
• Is it a channel you really care about so you want to index its videos ASAP? Use Fast Indexing
• Is it a channel who's videos are at risk of being deleted within minutes of uploading? Use Fast Indexing
• For all other channels, set it based on the upload schedule. If they upload weekly, set it to index daily. If they upload monthly, set it to index weekly

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 source on your specified frequency, but comparatively slow. You also have to remember that only so many indexing operations can run at the same time which 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 in some weird edge cases (eg: uploading dozens of videos within a few minutes of each other). 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 but the API will give you the fastest and most reliable experience. 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, enable 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
• If you only want videos that meet a certain minimum or maximum duration, enable advanced mode in your Source (upper right) and use the minimum/maximum duration fields

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.

How do I update yt-dlp independently from Pinchflat?

It's usually best to wait for a new release of Pinchflat so I can verify everything works, but if I'm taking too long or it's urgent you can do this:

1. Open the Docker console for Pinchflat as root with docker exec -it --user root pinchflat bash
   • NOTE: you may have to sub out the --user name or the container name if you've named things differently
2. Run yt-dlp -U
3. That's it! There's no need to restart the container